Pipeline API

Base URL: your SDK-facing API, locally http://localhost:8081. Read authentication and conventions first. Download OpenAPI 3.0 for the full machine-readable contract.

POST /pipelines

Create a pipeline using the legacy non-idempotent contract

Preserved for existing SDK clients. Each successful request creates a new pipeline, even when the payload is identical. New integrations that must safely retry an unknown HTTP outcome should use /pipelines/idempotent.

Authentication: No header security scheme; read the operation description for body credentials or delivery-token requirements.

Request body

Required.

Content type: application/json. LegacyPipelineCreateRequest

$ref: "#/components/schemas/LegacyPipelineCreateRequest"

Responses

POST /pipelines/idempotent

Atomically create or resolve a pipeline by idempotency key

The key is scoped to the application authenticated by X-API-Key and is retained for the lifetime of the pipeline. Sequential and concurrent requests with the same key and the same creation intent return the same pipeline ID. Tracing metadata may change between retries. Reusing the key for a different creation intent returns 409.

Authentication: ApiKeyAuth

Request body

Required.

Content type: application/json. IdempotentPipelineCreateRequest

$ref: "#/components/schemas/IdempotentPipelineCreateRequest"

Responses

POST /pipelines/by-idempotency-key

Find a pipeline by its application-scoped idempotency key

Uses a request body so the idempotency key is not placed in the URL or routine access logs.

Authentication: ApiKeyAuth

Request body

Required.

Content type: application/json. PipelineIdempotencyLookupRequest

$ref: "#/components/schemas/PipelineIdempotencyLookupRequest"

Responses

GET /pipelines/{pipelineId}

Get pipeline status and stage execution details

Authentication: ApiKeyAuth

Parameters

Responses

POST /pipelines/{pipelineId}/cancel

Cancel a non-terminal pipeline

Atomically marks the authenticated application's pipeline and its unfinished stages as cancelled. Cancellation of an already-running handler is cooperative; stale results are fenced by execution metadata.

Authentication: ApiKeyAuth

Parameters

Responses

POST /pipelines/{pipelineId}/stages

Append stages to an existing pipeline

Authentication: ApiKeyAuth

Parameters

Request body

Required.

Content type: application/json. AppendStagesRequest

$ref: "#/components/schemas/AppendStagesRequest"

Responses

POST /stages/{stageId}/resume

Resume a stage waiting for external approval

Authentication: ApiKeyAuth

Parameters

Request body

Required.

Content type: application/json. ResumeStageRequest

$ref: "#/components/schemas/ResumeStageRequest"

Responses

GET /version

Server version and licence tier

Authentication: No header security scheme; read the operation description for body credentials or delivery-token requirements.

Responses

POST /logs

Record a legacy free-form log line

Legacy log ingestion. This handler does not authenticate request headers. An optional body apiKey associates the log with an application when its hash matches a non-disabled key. Missing or unmatched keys still permit an unscoped log; this lookup does not check key expiry. It does not return 401 for key validation. Prefer stage-result logs or worker events for worker integrations.

Authentication: No header security scheme; read the operation description for body credentials or delivery-token requirements.

Request body

Required.

Content type: application/json. LogRequest

$ref: "#/components/schemas/LogRequest"

Responses