Ladder API

Ladder Chat Completions

Run a ladder via OpenAI-compatible chat completions.

Overview

POST /v1/{author}/{ladder}/chat/completions runs a LADR ladder and returns the result in OpenAI-compatible format. The ladder is identified by the author (username) and ladder (slug name) in the URL path.

This endpoint is fully OpenAI-compatible; anything that talks to OpenAI can call a ladder by changing the base URL and the path. The response shape is identical to /v1/chat/completions.

The ladder may execute multiple LLM calls, loops, gates, and recursion internally. The caller only sees the final output from the exit step.

URL Parameters

Parameter	Location	Description
`author`	URL path	Username of the ladder owner (e.g. `redeo-labs`)
`ladder`	URL path	Slug name of the ladder (e.g. `gated-tot`)

Example URL: https://api.redeo.ai/v1/redeo-labs/gated-tot/chat/completions

Request Body

Field	Type	Required	Description
`model`	`string`	Yes	Model to use for LLM calls. Must be allowed by the ladder's `allowedTargets` policy.
`messages`	`array`	Yes	Array of message objects with `role` and `content`. The last `user` message becomes `input.context` inside the ladder.
`knobs`	`object`	No	Override default knob values. Keys are knob IDs, values are numbers. Out-of-range values are clamped.
`stream`	`boolean`	No	Not yet supported. Must be omitted or `false`.

Response Shape

The response uses the standard OpenAI chat completion format:

json

{
  "id": "redeo-<instance-id>",
  "object": "chat.completion",
  "created": 1716234567,
  "model": "redeo-labs/gated-tot",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The ladder's final output..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 450,
    "total_tokens": 1650
  }
}

The model field is set to {author}/{ladder}. The usage object reflects the total token consumption across all LLM calls made during the ladder's execution (all steps, all nodes, all loops).

Example

bash

curl https://api.redeo.ai/v1/redeo-labs/gated-tot/chat/completions \
  -H "Authorization: Bearer $REDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What is the best programming language for systems programming?"}],
    "knobs": { "branches": 7 }
  }'

This runs the gated-tot ladder owned by redeo-labs with 7 branches instead of the default. The model field must be allowed by the ladder's allowedTargets. A ladder with strategy: universal accepts any model.

Access Control

A ladder must be visible to the caller's account. Visibility rules:

Private; only the owner can call it
Unlisted - anyone with the URL can call it
Public - anyone can discover and call it

API keys can also have per-ladder access controls (whitelist/blacklist) configured from the dashboard. If a key doesn't have access to the requested ladder, the API returns 404 (not 403) to avoid leaking ladder existence.