4. Flows

A flow moves or changes data. It reads objects from one system, applies a mapping, and sends records to its destinations. Anything functional is a flow. Anything that only reports is a report (chapter 6).

In the API paths and MCP tool names a flow is a pipeline. /v1/pipelines/:id is the flow you see at Flows in the app.

A flow's destination can be:

• another system,
• the Golden record, built from what the flow reads,
• a program that scores what the flow reads.

In the app

Open Flows and create a flow. A flow's page has these tabs: Overview, Mapping, Trigger, Destinations, Runs, Failed writes, Repairs, First loads and Access.

What you make is a draft. Nothing syncs until you turn it on.

From the API

Step 1: create a draft

curl -X POST https://api.inferrex.com/v1/pipelines \
  -H "X-API-Key: $INFERREX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-orders-flow-001" \
  -d '{
    "name": "Orders to finance",
    "sourceConnectionId": "SOURCE_CONNECTION_ID",
    "targetConnectionId": "TARGET_CONNECTION_ID",
    "mappingManifestId": "MAPPING_ID"
  }'

The flow starts with status: "draft". It belongs to the environment you are working in (chapter 7). It runs on its source system's sync timing until you give it its own.

A flow's status is one of draft, reviewing, active, paused, error, upgrading or archived.

Step 2: dry run

A dry run reads and converts records and writes nothing. Always dry run before you turn on a flow that writes to a system.

curl -X POST https://api.inferrex.com/v1/pipelines/PIPELINE_ID/dry-run \
  -H "X-API-Key: $INFERREX_API_KEY"

Response shape: { pipelineId, jobId, dryRunJobId, status }. Follow the job:

curl https://api.inferrex.com/v1/jobs/JOB_ID \
  -H "X-API-Key: $INFERREX_API_KEY"

A job's status is queued, running, succeeded, failed or cancelled. When a dry run has succeeded, its result holds what would be written:

{
  recordsRead?: number;
  recordsWouldWrite?: number;
  preview?: {
    recordsRead: number;
    destinations: {
      connectionId: string | null;
      wouldWrite: number;
      held: number;
      samples: {
        targetEntity: string;
        recordId: string;
        source: Record<string, unknown> | null;
        converted: Record<string, unknown>;
      }[];
    }[];
  };
}

Check the samples: source is the record as read, converted is what would be sent. held counts records that would not be sent.

A draft, paused or under-review flow can be dry-run. An archived flow, a flow in error, or a flow between two systems with no mapping is refused.

Step 3: turn it on

curl -X POST https://api.inferrex.com/v1/pipelines/PIPELINE_ID/activate \
  -H "X-API-Key: $INFERREX_API_KEY"

Inferrex runs a first full sync straight away. Response shape: { pipelineId, status, jobId, initialSyncJobId }. Follow the job as above.

If the flow connects two systems, its mapping must be approved first when your workspace requires that. Turning on a flow that is already on does nothing.

Step 4: sync now

curl -X POST https://api.inferrex.com/v1/pipelines/PIPELINE_ID/sync \
  -H "X-API-Key: $INFERREX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"syncType": "incremental"}'

syncType is incremental (the default: only what changed since the last sync), full (everything) or initial (a first full sync). The flow must be active. Response shape: { pipelineId, jobId, syncJobId, status, syncType }.

To stop a running sync or dry run, call POST /v1/jobs/:id/cancel. A queued job is cancelled at once. A running job stops at its next safe point. A run that is already storing and writing records finishes.

Trigger and direction

Set when a flow syncs:

curl -X PUT https://api.inferrex.com/v1/pipelines/PIPELINE_ID/schedule \
  -H "X-API-Key: $INFERREX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduleType": "scheduled", "scheduleCron": "0 9 * * 1-5", "scheduleTimezone": "Europe/London"}'

scheduleType is realtime, scheduled (on the timetable in scheduleCron), after_sync, manual (only when you start it) or system (follow the source system's timing again).

Set the direction with PATCH /v1/pipelines/:id and "direction": forward (source to target), reverse (target back to source) or bidirectional. Reverse and both directions need a flow between two systems with a mapping.

Destinations

A flow can send to more than one destination. Changes to destinations are drafts with a preview.

1. Draft the change:

   curl -X POST https://api.inferrex.com/v1/pipelines/PIPELINE_ID/changes \
     -H "X-API-Key: $INFERREX_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"kind": "add-destination", "connectionId": "DESTINATION_CONNECTION_ID", "mappingId": "MAPPING_ID"}'
   

   kind is add-destination or remove-destination. The response carries a riskLevel and a preview with destinationsBefore and destinationsAfter. Nothing is applied yet.

2. Confirm it: POST /v1/pipelines/:id/changes/:changeId/confirm. With no approval policy for flow changes, or one whose limit the risk is within, the change applies now. Otherwise it waits for approval.

3. If it waits: another member approves with POST /v1/pipelines/:id/changes/:changeId/approve or rejects with .../reject. The person who drafted a change cannot approve it.

4. To drop a draft: POST /v1/pipelines/:id/changes/:changeId/discard.

A destination added to a flow receives nothing until it has its own mapping and is turned on.

Keep a flow's mapping up to date

A flow keeps the mapping version it was turned on with. After you edit and review the mapping:

curl -X POST https://api.inferrex.com/v1/pipelines/PIPELINE_ID/apply-mapping \
  -H "X-API-Key: $INFERREX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mappingVersionId": "MAPPING_VERSION_ID"}'

Send the version you reviewed. If the mapping has changed since, the call is refused so you can review the newer version first.

Limit what a flow may do to a system

PUT /v1/workspace/pipelines/:id/connection-access with { "connectionId": "...", "accessLevel": "read" } stops a flow ever writing to that system. accessLevel is read or read_write. The same system can be read-only in one flow and writable in another.

Other flow operations

Archiving stops the flow and keeps its sync history.

First loads

A first load is the first full copy of a system's existing records. It is tracked at /v1/initial-loads and needs approval (POST /v1/initial-loads/:id/approve) before Inferrex runs it. Estimate the size first with POST /v1/connections/:id/assess-scope (chapter 3).

Automations

An automation runs steps when something happens. Automations live under Flows in the app and at /v1/workflows in the API (tools starting workflows_). Create one with POST /v1/workflows, switch it on with POST /v1/workflows/:id/enable, run it now with POST /v1/workflows/:id/trigger, and read its runs at /v1/workflow-runs.

Next: Golden records and review.