API Connectors explained with real setup patterns

API Connectors help teams keep systems aligned without building brittle glue code. This tutorial walks through common setup patterns, what to define first, and how to scale from simple syncing to reliable automation.

Before you integrate: define ownership and boundaries

Most integration problems are not endpoint problems. They are ownership problems.

Decide the source of truth

Pick which system owns each field. Decide where status changes originate. Decide how conflicts are resolved. If you skip this step, the connector becomes a tug of war.

Two line example mapping:

const sourceOfTruth = { status: "platform", priority: "external" };

const sourceOfTruth = { status: "platform", priority: "external" };

const sourceOfTruth = { status: "platform", priority: "external" };

Pattern 1: Read only sync for visibility

Read only sync is the safest starting point.

Validate mapping before actions

Confirm terminology, statuses, and identifiers match what teams expect. This prevents automation from amplifying bad mapping.

await client.connectors.create({ provider: "atlas", mode: "read_only" });

await client.connectors.create({ provider: "atlas", mode: "read_only" });

await client.connectors.create({ provider: "atlas", mode: "read_only" });

Pattern 2: Event based actions for handoffs

Once visibility is stable, add actions.

Start with low risk actions

Create follow ups, send notifications, update noncritical fields. Expand only after trust is established.

Example of an event trigger configuration:

await client.webhooks.create({ event: "issue.status_changed", target: "https://example.com/hook" });

await client.webhooks.create({ event: "issue.status_changed", target: "https://example.com/hook" });

await client.webhooks.create({ event: "issue.status_changed", target: "https://example.com/hook" });

Pattern 3: Production readiness through observability

Failures are normal. Design for them.

Make failures legible

Operators should be able to see what failed and why without digging through logs for an hour. If troubleshooting is difficult, integrations become a burden.