Skip to main content

Dispatches

List a pipeline's Dispatch nodes, trigger one by hand with an Idempotency-Key, read dispatch history with per-binding attempt counts, and re-dispatch.

A dispatch is one firing of a Spec's Dispatch node on a pipeline. When a node fires, automatically through its trigger mode or by hand, the platform freezes the selected rows, the projected fields, and a cutoff onto a dispatch record and publishes dispatch.<grain>.requested events that the node's delivery bindings ship to their destinations. The routes below let you inspect a pipeline's Dispatch nodes, trigger one manually, read the dispatch history, and replay a dispatch. They are the API counterpart of the Dispatch panel on a pipeline in the app.

Use GET /v1/pipelines/{id}/dispatch-nodes first to learn which nodes the pipeline's Spec defines: each entry carries the stage_id you pass to the trigger route, the node name, its grain, mode, selection scope and row_source, and any compile errors that stop it from firing. The response also says whether the Spec is published; a node can only be triggered when the Spec has a published version and the pipeline is ready.

A manual trigger accepts an optional body with document_ids and/or product_record_ids (up to 50,000 each). Both narrow the node's own selection, they are intersected with it and never added to it, so you cannot ship rows the node would not select. Send an Idempotency-Key header to make retries safe: a repeat with the same key returns the existing dispatch with 200 and existing: true instead of creating a second one. Manual triggers never read per-request delivery controls from POST /v1/run.

Re-dispatch replays a dispatch from its frozen record: same selection, same projection, same cutoff, and the same per-request destination overrides if the original had any. A failed or stale pending dispatch is repaired in place; any other dispatch produces a new one with mode: "manual" and replay_of pointing at the source. A skipped dispatch (one a run request opted out of) is terminal and answers 409 DISPATCH_SKIPPED_BY_REQUEST; trigger the node manually instead.

GET/v1/pipelines/{id}/dispatch-nodes

Response fields

spec_iduuid | nullThe Spec linked to the pipeline's schema. Null when the schema has no Spec, in which case nodes is empty.
publishedbooleanTrue when the nodes come from the Spec's activated version, false when they come from its snapshot rail.
nodes[].stage_idstringThe id to pass to POST /v1/pipelines/{id}/dispatches/{stageId}.
nodes[].namestring | nullThe node's name. Null when the Spec has no published version.
nodes[].grainstringrow, pipeline, assembly, matcher, or data_product.
nodes[].modestringmanual, on_run_completed, on_stage_completed, on_request_extracted, on_matcher_verdict, on_matcher_done, or on_app_verdict.
nodes[].scopestringThe node's selection scope: all or changed_since.
nodes[].row_sourcestringdocument or product. Present for the row grain only.
nodes[].errorsstring[]Codes of the node's error-level compile diagnostics. Empty for a Spec with no published version.

The list is the one the run page shows, and manual triggers read the same list. When the Spec has a published version, the nodes come from its activated version and each carries the codes of its error-level compile diagnostics in errors; a node with errors cannot fire. A Spec with no published version lists the nodes of its snapshot rail with published: false, name: null and empty errors. A schema without a Spec returns spec_id: null and no nodes. The route needs the read scope; an app service key does not reach it, and an unknown pipeline answers 404.

Response (200) — GET /v1/pipelines/{id}/dispatch-nodes

{
  "spec_id": "5b2e0d7a-3c11-4e0f-9a64-7f1c2d8e9b40",
  "published": true,
  "nodes": [
    {
      "stage_id": "dispatch-month-end",
      "name": "Month-end export",
      "grain": "pipeline",
      "mode": "manual",
      "scope": "all",
      "errors": []
    }
  ]
}
POST/v1/pipelines/{id}/dispatches/{stageId}

Body parameters (optional)

document_idsuuid[]Restrict the node's selection to these documents (max 50,000). Intersected with the node's selection.
product_record_idsuuid[]Restrict the selection to these product records (max 50,000). Intersected with the node's selection.

Headers

Idempotency-KeystringOptional. A repeat with the same key returns the existing dispatch (existing: true).

curl

curl -X POST https://api.talonic.com/v1/pipelines/1a0c681d-ea20-4bb4-8892-01a6d7f834da/dispatches/NODE_ID \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Idempotency-Key: month-end-2026-09" \
  -H "Content-Type: application/json" \
  -d '{}'

Response (201)

{
  "dispatch_id": "7d1f0c2e-5b8a-4c3e-9f21-0a6b4d8e2c11",
  "grain": "pipeline",
  "status": "published",
  "record_count": 248,
  "event_count": 1,
  "existing": false
}
GET/v1/pipelines/{id}/dispatches
GET/v1/pipelines/{id}/dispatches/{dispatchId}
POST/v1/pipelines/{id}/dispatches/{dispatchId}/redispatch

Dispatch statuses

pendingstringCreated; events are being published.
publishedstringEvents published to the node's bindings; see items[] for delivery attempts.
emptystringThe selection matched nothing; no events.
failedstringPublishing failed (see error). Re-dispatch repairs it in place.
supersededstringReplaced by a newer dispatch for the same subject before it shipped.
skippedstringA run request opted this node out. Terminal; re-dispatch returns 409.

Errors

Error responses

404DISPATCH_NODE_NOT_FOUND / not_foundThe stageId is not a Dispatch node of the pipeline's Spec, or the pipeline or dispatch does not exist for your organization.
409DISPATCH_PIPELINE_NOT_READY / DISPATCH_SPEC_UNPUBLISHED / DISPATCH_NODE_INVALID / DISPATCH_NO_DATA_PRODUCTThe node cannot fire yet: the pipeline is not ready, the Spec has no published version, the node has compile errors, or a data_product node has no data product.
409DISPATCH_SKIPPED_BY_REQUESTRe-dispatch of a skipped dispatch. Trigger the node manually instead.
Re-dispatch ships the selection frozen at trigger time. If data changed after the node fired and you want the current rows delivered, trigger the node again (manually or through its trigger mode) so a new selection is frozen.

Frequently asked questions

How do I find the stageId of a Dispatch node?+
Call GET /v1/pipelines/{id}/dispatch-nodes. Each node carries its stage_id; it is the same id shown in the Spec editor and used as signal_filter.match.stage_id on dispatch.* bindings.
Can a manual trigger ship rows the node would not normally select?+
No. document_ids and product_record_ids are intersected with the node's own selection, never added to it. They only narrow what ships.
How do I retry a manual trigger safely?+
Send the same Idempotency-Key header. A repeat returns the existing dispatch with 200 and existing: true instead of creating a second dispatch.
What is the difference between re-dispatch and a new trigger?+
Re-dispatch replays the frozen selection, projection, and cutoff of an earlier dispatch, so it ships the same rows. A new trigger freezes a fresh selection from the current data.