Copy page

Embed SDK

Connector Lifecycle

Saving a connector in the iframe creates it, but data doesn't move until you build a pipeline. This page covers that second half: the shared pipeline primitive, how ingress and egress differ, and how to check status, pause, resume, and delete an integration.

All of the calls below run on your backend, behind the MonadRequest thunk described in the API Reference. The browser sends a connector id; your backend resolves the rest.

The shared primitive

Every pipeline is an input node and an output node joined by an edge. The raw call:

Code
const pipeline = await request(`/v2/${org}/pipelines/`, {
  method: 'POST',
  body: JSON.stringify({
    name,
    enabled: true,
    nodes: [
      { slug: 'in',  component_id: inputId,  component_type: 'input',  enabled: true },
      { slug: 'out', component_id: outputId, component_type: 'output', enabled: true },
    ],
    edges: [
      {
        from_node_instance_id: 'in',
        to_node_instance_id: 'out',
        conditions: { operator: 'always' },
      },
    ],
  }),
});
// Poll GET /v2/{org}/pipelines/{id}/status until status is 'Running'.

Ingress and egress are this same call with the ends swapped. In ingress, the user supplies the input and you supply the output; in egress, you supply the source input and the user supplies the output.

:::info Build is asynchronous POST /v2/{org}/pipelines/ returns before the pipeline is Running. Poll …/status on an interval (about every two seconds, capped) and show a "connecting" state in the meantime. :::

Lifecycle helpers

The SDK ships helpers so you don't hand-roll the common flows. Each takes a request thunk (see the API Reference):

• buildDevNullPipeline({ request, org, inputId, inputName }) — stands up a throwaway sink for a freshly connected input (zero setup).
• findIntegrationPipeline({ request, org, inputId }) — resolves an input's pipeline and enabled state from just the input id. Returns ResolvedIntegration | null.
• setIntegrationEnabled({ request, org, pipelineId, enabled }) — pauses or resumes flow. enableIntegration / disableIntegration are conveniences over it.
• deleteIntegration({ request, org, pipelineId?, inputId?, outputId?, cleanup }) — removes an integration; cleanup decides what gets torn down (below).

Ingress

Your user connects a source. You decide where it flows.

1. The user configures the input; onSave({ id }) fires with the connector id.
2. Build a pipeline from their input to a destination you control. For the zero-setup default, use buildDevNullPipeline. For a real destination, use the raw call above with outputId set to your pre-provisioned store.
3. The source shows up in the tenant's list as Active.

Code
await buildDevNullPipeline({ request, org, inputId, inputName });

See Best Practices for choosing between dev/null, a per-tenant store, and a shared store.

Egress

Your user connects a destination. You already have one source per team, provisioned once (your product's own connector, or a simple HTTP input).

1. The user configures the output; onSave({ id }) fires.
2. Wire your team source to their new output with the same primitive.
3. One source fans out to every destination the tenant adds.

The symmetry: ingress fixes the output (your store) and varies the input; egress fixes the input (your source) and varies the output.

Status, pause, resume

Resolve an integration's state from the connector id, without storing pipeline ids:

Code
const status = await findIntegrationPipeline({ request, org, inputId });
// { org, pipelineId, inputId, outputId?, enabled } | null
// (null means connected but no pipeline)

await setIntegrationEnabled({ // pause
  request,
  org,
  pipelineId: status.pipelineId,
  enabled: false,
});

Show users Active and Paused, not "pipeline." The pipeline is your implementation detail.

Delete and cleanup

Deleting is the other place ingress and egress diverge, because what's safe to remove depends on whether the other end is shared. deleteIntegration takes a cleanup policy:

Policy	Tears down	Use when
CLEANUP_FULL	pipeline, input, and output	Ingress to a throwaway dev/null sink; nothing is shared.
CLEANUP_KEEP_OUTPUT	pipeline and input (keeps the output)	Ingress to a shared store other inputs still feed.
CLEANUP_PIPELINE_ONLY	pipeline only	You want to keep both ends.

For anything the presets don't cover, pass a custom { pipeline?, input?, output? } — an omitted flag defaults to delete. Egress needs a custom policy: keep the shared source (input: false) and remove the pipeline and the user's output. The source feeds other tenants' destinations, so it never gets deleted.

:::warning Resolve-then-act The browser sends a connector id; your backend looks up the pipeline and output ids server-side rather than trusting ids from the client — the same rule as in Tenancy. :::

Next

• Best Practices — default inputs/outputs, catalog caching, and deployment.
• API Reference — the request thunk, options, and route contract.

Support

For additional support contact support@monad.com