Stilt API

Stilt Chat Completions

Run a stilt via OpenAI-compatible chat completions.

Overview

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

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

The stilt 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 stilt owner (e.g. `redeo-labs`)
`stilt`	URL path	Slug name of the stilt (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 stilt's `allowedTargets` policy.
`messages`	`array`	Yes	Array of message objects with `role` and `content`. The last `user` message becomes `input.context` inside the stilt.
`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 stilt's final output..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 450,
    "total_tokens": 1650
  }
}

The model field is set to {author}/{stilt}. The usage object reflects the total token consumption across all LLM calls made during the stilt'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 stilt owned by redeo-labs with 7 branches instead of the default. The model field must be allowed by the stilt's allowedTargets. A stilt with strategy: universal accepts any model.

Access Control

A stilt 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-stilt access controls (whitelist/blacklist) configured from the dashboard. If a key doesn't have access to the requested stilt, the API returns 404 (not 403) to avoid leaking stilt existence.