Skip to main content
POST
/
v1
/
run
curl -X POST https://api.runtools.ai/v1/run \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "code-assistant",
    "prompt": "Run the tests and summarize failures.",
    "stream": false,
    "config": {
      "maxTurns": 12
    }
  }'

{
  "data": {
    "runId": "run_abc123",
    "sandboxId": "sandbox-abc123",
    "executionMode": "in_sandbox",
    "status": "completed",
    "result": "The test suite is green.",
    "usage": {
      "inputTokens": 1480,
      "outputTokens": 322
    },
    "iterations": 4,
    "threadId": "thr_abc123"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

POST /v1/run is the canonical agent run endpoint. Set stream: false for JSON responses. When stream is omitted or true, the endpoint returns Server-Sent Events for sandbox-backed and managed agents.

​
Request Body

​
agent
string
required
Agent slug or ID.
​
prompt
string
User prompt. Either prompt or messages is required.
​
messages
array
Caller-managed conversation history. Use this when you do not want server-managed thread history.
​
threadId
string
Persist the run into a server-managed thread. Reuse the same ID to continue the thread.
​
stream
boolean
default:"true"
false returns JSON. true returns Server-Sent Events.
​
config
object
Per-run overrides: maxTokens, maxTurns, and temperature.
​
metadata
object
Caller metadata stored with the run.

​
Response

​
runId
string
Run ID.
​
status
string
Run status, such as completed, registered, or dispatched.
​
result
string
Final assistant response for non-streaming runs.
​
threadId
string
Thread ID when threading is active.
​
usage
object
Token usage when available.
curl -X POST https://api.runtools.ai/v1/run \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "code-assistant",
    "prompt": "Run the tests and summarize failures.",
    "stream": false,
    "config": {
      "maxTurns": 12
    }
  }'

{
  "data": {
    "runId": "run_abc123",
    "sandboxId": "sandbox-abc123",
    "executionMode": "in_sandbox",
    "status": "completed",
    "result": "The test suite is green.",
    "usage": {
      "inputTokens": 1480,
      "outputTokens": 322
    },
    "iterations": 4,
    "threadId": "thr_abc123"
  }
}

​
Thread APIs

curl "https://api.runtools.ai/v1/run/threads?agent=code-assistant" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

const threads = await rt.agent.threads('code-assistant');
const detail = await rt.agent.getThread(threads[0].id, 'code-assistant');
await rt.agent.deleteThread(threads[0].id, 'code-assistant');

​
Legacy Per-Agent Endpoint

POST /v1/agents/{slug}/run still exists, but new code should prefer POST /v1/run because it has the same request shape used by the SDK and thread helpers.