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.
/v1/pipelines/{id}/dispatch-nodesResponse fields
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": []
}
]
}/v1/pipelines/{id}/dispatches/{stageId}Body parameters (optional)
Headers
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
}/v1/pipelines/{id}/dispatches/v1/pipelines/{id}/dispatches/{dispatchId}/v1/pipelines/{id}/dispatches/{dispatchId}/redispatchDispatch statuses
Errors
Error responses