Pipeline API
Every published pipeline is a versioned HTTP endpoint. There are two ways to call it: the typed /invoke endpoint for JSON in and JSON out, and an OpenAI-compatible /chat/completions endpoint that works as a drop-in for any OpenAI SDK, streaming included.
Base URL
https://trezalabs.comBoth endpoints live under /api/pipelines/<id>, where <id> is the pipeline's id from the dashboard. They accept and return application/json (the streaming variant returns Server-Sent Events).
Authentication
Authenticate with a Treza API key, created on the API keys page in the dashboard and sent as a bearer token:
Authorization: Bearer treza_live_...The key (treza_live_...) is shown once at creation. Store it in a secrets manager. A key can only invoke pipelines owned by the same account, and the pipeline must be published.
Starting a run (POST .../invoke and /chat/completions) needs the pipelines:run scope. Polling a run (GET .../invoke) accepts pipelines:read or pipelines:run. A key without the scope gets 403 with code: "MISSING_SCOPE". See API Keys.
Prerequisites
For a pipeline to accept API calls it must be published and have at least one input node and one output node. The input keys you send and the output keys you receive are derived from those nodes (the pipeline's contract). See Publishing & versioning.
Limits and credits
Rate limit. 60 requests a minute per account, shared by
POST .../invokeand/chat/completions. Past it you get429withcode: "RATE_LIMITED"andretryAfter(seconds), plusRetry-AfterandX-RateLimit-*headers.Concurrent runs. Up to 10 runs of one pipeline can be in progress from
/invokeat once. The next one gets429withcode: "TOO_MANY_CONCURRENT_RUNS".Credits. Runs draw from your account's prepaid credit balance. Before a run starts, the balance has to cover its estimated charge, and on
/invokealso what is already committed to your runs still rendering. Check it withGET /api/account/balanceand the same API key (see Funding an account without a human).
When the balance falls short, the run is refused with 402 before anything is charged:
topUpUrl is where a person adds credits. x402TopUpUrl lets an agent with a wallet top up on its own (see x402 Payments). On /chat/completions the same fields sit inside the error object, with type: "billing_error".
POST /api/pipelines/{id}/invoke
Starts a run of the published pipeline with typed inputs. Runs execute asynchronously on Treza's background workers, so this returns a runId immediately. Poll GET .../invoke for the result. Use this endpoint for video and other long runs.
Request
inputs
object
Map of the pipeline's input keys to values. Keys come from your input nodes.
Response 202 Accepted
runId
Id of the run to poll. Also appears in run history.
status
Always running on accept.
version
The published version serving the run.
statusUrl
Ready-made URL to poll for status and outputs.
GET /api/pipelines/{id}/invoke
Polls a run started by POST .../invoke. Same bearer API key.
Request
runId
The runId returned by POST .../invoke (URL-encode it).
Response
While the run is in progress:
Once finished:
status
running, success, error, partial, or cancelled (stopped before it finished).
outputs
Map keyed by the output nodes' keys of the version that ran (present once finished).
usage
Token counts and provider cost (costUsd) for the run.
durationMs
Wall-clock run time in milliseconds (once finished).
Polling without runId returns 400; a runId this pipeline does not have returns 404.
POST /api/pipelines/{id}/chat/completions
An OpenAI-compatible chat-completions endpoint. Point any OpenAI SDK at it by changing the base URL and API key. The latest user message is fed into the pipeline's entry node, and the output node's value is returned as the assistant message.
curl
The model field is accepted but not used to pick a model (the pipeline's nodes decide that); send any string.
Python (OpenAI SDK)
TypeScript (OpenAI SDK)
Response
A standard OpenAI chat-completion object:
Two response headers help you tie a completion back to a run:
x-treza-run-id
Id of the recorded run.
x-treza-pipeline-version
The published version that served the request.
Streaming
Set "stream": true to receive the response as Server-Sent Events, emitted as chat.completion.chunk objects and terminated by data: [DONE]. The final chunk carries finish_reason: "stop" and a usage block. Any OpenAI SDK's streaming mode works unchanged. The chunks are sent once the run has finished, so streaming does not shorten the wait or the five-minute limit.
Errors
Every error response has an error field. On /invoke it is a message string, often next to a code you can branch on. On /chat/completions every error uses the OpenAI shape { "error": { "message": ..., "type": ..., "code": ... } }, so an OpenAI SDK raises its usual exception with the message intact. code is set where /invoke has one (MISSING_SCOPE, INSUFFICIENT_CREDITS, RATE_LIMITED).
400
Malformed request: no messages on /chat/completions, or no runId when polling /invoke.
401
Missing or invalid API key.
402
Not enough credits for this run (code: "INSUFFICIENT_CREDITS"). See Limits and credits.
403
The key's account does not own this pipeline, or the key lacks the scope (code: "MISSING_SCOPE").
404
Pipeline not found, or (when polling) run not found.
409
Pipeline is not published.
422
/chat/completions only: the pipeline has no entry node or no output node.
429
Rate limit or concurrent-run limit. See Limits and credits.
502
/chat/completions only: the pipeline ran but a node failed, and the error carries that node's message. On /invoke a failed run shows up as status: "error" when you poll.
500
Internal server error.
Related
Build your first pipeline - end-to-end from the canvas.
Publishing & versioning - versions, rollback, and run history.
API Keys - creating keys and choosing scopes.
x402 Payments - topping up credits from an agent's wallet.
Last updated