Ladder API

Pipeline Instances

Async ladder execution; returns immediately with an instance ID.

Overview

POST /v1/pipelines/instances starts a ladder execution asynchronously. Unlike the chat completions endpoint (which blocks until the ladder finishes), this endpoint returns immediately with a 202 status and an instanceId. Use this for long-running ladders or when you want to poll for results yourself.

Request Body

Field	Type	Required	Description
`author`	`string`	Yes	Username of the ladder owner
`template`	`string`	Yes	Slug name of the ladder
`model`	`string`	Yes	Model to use for LLM calls
`messages`	`array`	Yes	Array of message objects. The last `user` message becomes `input.context`.
`knobs`	`object`	No	Override default knob values

Response

json

{
  "instanceId": "abc123-def456-...",
  "status": "pending"
}

The response is returned immediately with HTTP 202. The ladder runs in the background. Poll the instance status or check results in Studio.

Example

bash

curl -X POST https://api.redeo.ai/v1/pipelines/instances \
  -H "Authorization: Bearer $REDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "author": "redeo-labs",
    "template": "gated-tot",
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Analyze this."}],
    "knobs": { "branches": 5 }
  }'