---
title: "Run a Spec as a pipeline"
method: POST
path: "/v1/pipelines"
tags: ["Pipelines"]
---

# Run a Spec as a pipeline

`POST /v1/pipelines`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/pipelines`
- Auth: HTTP bearer

Compiles the named Spec's saved rail into a pipeline and starts processing the documents in one call. The Spec must have a composed rail; otherwise a 400 is returned (use POST /v1/jobs for an ad-hoc run with no rail). Requires write scope.

## Request body

- object
  - `schema_id` string, uuid, required: The Spec to run (a user_schema with a composed rail).
  - `document_ids` string[], required
  - `name` string
  - `pipeline_mode` 'new' | 'append': Explicit override of the Spec's configured pipeline mode. `append` adds the documents to the newest eligible existing pipeline on the Spec (config-matching, under the size cap) instead of creating one; the response's `appended` reports which happened. Omitted → the Spec's own setting (default `new`).

## Response `201`

Created pipeline run with links to progress + data-product. `appended: true` marks an append-mode reuse of an existing pipeline (its id is returned). `run_id` is the submission-group identifier stamped on this call's documents — usable as the `run_id` filter on the results/documents reads.

## Other responses

- `400`: The Spec has no composed rail, or the body failed validation.
- `413`: The request exceeds the tested per-run document ceiling.
- `429`: The pipeline queue lacks tested headroom; retry after the advised delay.
- `503`: Pipeline queue headroom or durable fan-out could not be verified.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)