Skip to main content
POST
/
orgs
/
{org_id}
/
projects
/
{project_id}
/
compose
curl --request POST \ --url https://api.timbal.ai/orgs/{org_id}/projects/{project_id}/compose \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "rev": "main", "prompt": [ "Review this config file", { "type": "file", "file": { "name": "config.json", "source": { "type": "url", "url": "https://example.com/config.json" } } } ] } '
The prompt field accepts a plain string, an array of content blocks, or a full Message object. Content blocks can be text or files (base64, URL, or server-side path). Supported file types: images (png/jpg/gif/webp/svg), PDFs, and text-readable formats (json, csv, md, yaml, py, rs, etc.).

Authorizations

​
Authorization
string
header
required

Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.

Path Parameters

​
org_id
string
required
​
project_id
string
required

Body

application/json
​
prompt
object
required

The prompt: a plain string, an array of content blocks, or a full Message object.

​
rev
string
required

Branch to run against (worktree is checked out at this rev)

Example:

"main"

​
effort
null | enum<string>

Reasoning effort level. Higher levels let the model think longer before responding, at proportionally higher cost and latency.

Available options:
low,
medium,
high,
max
​
mode
null | enum<string>

Session behavior mode. default bypasses all tool-permission prompts and lets the agent edit files, run shell commands, and call MCP tools freely. plan restricts the agent to read-only tools — it analyses the codebase and produces a plan, without mutating anything.

Available options:
default,
plan
​
model
null | enum<string>

Model family to use. Always resolves to the latest version of that family — specific version pinning is not exposed.

Available options:
sonnet,
opus,
haiku
​
session_id
string | null

Existing session ID to continue a conversation. Omit to start a new session.

Response

200 - text/event-stream

SSE stream of Claude responses