Sign in

v2

latestOpenAPI 3.0.4Apache 2.0raw.githubusercontent.com2026-07-1754198241.7 KB
Runs

Start a connector route run

Starts a route run and returns the accepted execution record. The optional input can carry lookup keys, batch references, dry-run flags, or caller metadata. Long-running execution is observed through the runs, events, and dead-letter endpoints.

post/routes/{routeId}/runs

Path parameters

routeIdstring uuid required

Stable identifier for a connector route.

Example:1e8ff011-2274-4f16-a7dd-bf0b4fd5262f

Stable identifier of a connector route that composes a source operation, destination operation, optional transformation, and trigger policy.

Request body

{"stackTrail":"components:schemas:StartConnectorRouteRunRequest:properties:input","oasType":"schema","type":"unknown","description":"Optional input payload, connector fields, or batch reference passed to the route.","example":{"employee_id":"E12345","batch_ref":"vault://imports/license-batches/batch-2026-06-18.csv"},"nullable":true}
dryRunboolean

Whether the run should validate and transform without committing destination writes.

invocationBindingIdstring

Stable identifier of the domain invocation binding that caused a connector call.

logicalConnectionBindingIdstring

Stable identifier of a tenant, OU, brand, legal-entity, or channel usage binding for a physical connector instance.

physicalConnectorInstanceIdstring uuid

Stable platform identifier for a configured connector instance.

exchangeMode'PLATFORM_INITIATED_PULL' | 'PLATFORM_INITIATED_PUSH' | 'EXTERNALLY_INITIATED_READ' | 'EXTERNALLY_INITIATED_WRITE' | 'SUBSCRIPTION_CALLBACK' | 'BIDIRECTIONAL_SYNC'

Explicit exchange quadrant. Data direction and initiation side remain separate axes in run responses.

correlationIdstring

Caller-provided correlation id for logs, run events, and downstream traceability.

metadataStringMap

Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

Example request

{
  "input": {
    "batch_ref": "vault://imports/license-batches/batch-2026-06-18.csv"
  },
  "dryRun": false,
  "correlationId": "import-2026-06-18-001",
  "metadata": {
    "initiated_by": "admin@example.com"
  }
}

Response

Connector route run accepted.

runIdstring uuid required

Stable identifier for a connector route or operation run.

routeIdstring uuid

Stable identifier for a connector route.

bindingIdstring uuid

Stable identifier for a connector operation binding.

connectorInstanceIdstring uuid

Stable platform identifier for a configured connector instance.

invocationBindingIdstring

Stable identifier of the domain invocation binding that caused a connector call.

logicalConnectionBindingIdstring

Stable identifier of a tenant, OU, brand, legal-entity, or channel usage binding for a physical connector instance.

physicalConnectorInstanceIdstring uuid

Stable platform identifier for a configured connector instance.

exchangeMode'PLATFORM_INITIATED_PULL' | 'PLATFORM_INITIATED_PUSH' | 'EXTERNALLY_INITIATED_READ' | 'EXTERNALLY_INITIATED_WRITE' | 'SUBSCRIPTION_CALLBACK' | 'BIDIRECTIONAL_SYNC'

Explicit exchange quadrant. Data direction and initiation side remain separate axes in run responses.

dataDirection'INBOUND' | 'OUTBOUND' | 'BIDIRECTIONAL'

Direction of data movement relative to the platform operating the connector.

initiationSide'PLATFORM' | 'EXTERNAL' | 'SUBSCRIPTION_CALLBACK' | 'BIDIRECTIONAL_SYNC'

Side that initiated the exchange.

connectorResourceIdstring uuid

Stable identifier for a resource attached to a connector instance.

operationKind'READ' | 'WRITE' | 'UPDATE' | 'DELETE' | 'UPSERT' | 'QUERY' | 'SEARCH' | 'IMPORT' | 'EXPORT' | 'INVOKE' | 'DISCOVER' | 'VALIDATE'

Reusable operation taxonomy shared by connectors, inventory, policy, and workflows. The operation kind is logical; connector-local details live in operationName.

triggerKind'INLINE' | 'ON_DEMAND' | 'SCHEDULED' | 'EVENT' | 'WEBHOOK' | 'PIPELINE'

Mechanism that initiated the run.

status'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'PARTIALLY_FAILED' | 'CANCELLED' required

Execution status of a route run or connector operation run.

startedAtstring date-time required

Timestamp when execution started.

finishedAtstring date-time

Timestamp when execution finished, if complete.

itemCountinteger

Number of input items seen by the run.

successCountinteger

Number of items processed successfully.

failureCountinteger

Number of items that failed after retries or validation.

correlationIdstring

Caller-provided or runtime-generated correlation id.

metadataStringMap

Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

updatedAtstring date-time

Last update timestamp for this run record.

createdByUserIdstring

Optional user id that initiated or created the run record.

updatedByUserIdstring

Optional user id that last updated the run record.

deletedAtstring date-time

Soft-delete timestamp, if the run record is hidden from normal queries.

Example response

{
  "runId": "9a785884-63ea-4b07-9976-264a1fc595f1",
  "routeId": "1e8ff011-2274-4f16-a7dd-bf0b4fd5262f",
  "connectorInstanceId": "3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5",
  "connectorResourceId": "8d228f50-a86c-4d5f-9eb4-83fdad7d75fa",
  "operationKind": "READ",
  "triggerKind": "ON_DEMAND",
  "status": "PARTIALLY_FAILED",
  "startedAt": "2026-06-18T10:20:00Z",
  "finishedAt": "2026-06-18T10:21:12Z",
  "itemCount": 250,
  "successCount": 247,
  "failureCount": 3,
  "correlationId": "import-2026-06-18-001",
  "metadata": {
    "batch_ref": "vault://imports/license-batches/batch-2026-06-18.csv"
  }
}