curl --request POST \
--url https://api.runtools.ai/v1/run \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent": "<string>",
"prompt": "<string>",
"stream": true,
"messages": [
{
"role": "user",
"content": "<string>",
"parts": [
{
"type": "text",
"text": "<string>"
}
]
}
],
"threadId": "<string>",
"config": {
"maxTokens": 123,
"maxTurns": 123,
"temperature": 123
},
"metadata": {}
}
'{
"data": {
"runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"sandboxId": "<string>",
"threadId": "<string>",
"rolloutId": "<string>",
"executionMode": "in_sandbox",
"targetDeviceId": "<string>",
"status": "registered",
"result": "<unknown>",
"usage": {
"promptTokens": 123,
"completionTokens": 123,
"totalTokens": 123,
"inputTokens": 123,
"outputTokens": 123,
"cachedInputTokens": 123,
"reasoningTokens": 123
},
"iterations": 123
}
}Dispatches an agent run by executionMode:
in_sandbox — routes through the linked sandbox runtime.managed — routes into runtools-model-gateway.local-mac — registers and dispatches through RunMesh to the bound device.
Streaming responses are text/event-stream (SSE) with RunTools agent
event frames. Non-streaming returns JSON when complete.curl --request POST \
--url https://api.runtools.ai/v1/run \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent": "<string>",
"prompt": "<string>",
"stream": true,
"messages": [
{
"role": "user",
"content": "<string>",
"parts": [
{
"type": "text",
"text": "<string>"
}
]
}
],
"threadId": "<string>",
"config": {
"maxTokens": 123,
"maxTurns": 123,
"temperature": 123
},
"metadata": {}
}
'{
"data": {
"runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"sandboxId": "<string>",
"threadId": "<string>",
"rolloutId": "<string>",
"executionMode": "in_sandbox",
"targetDeviceId": "<string>",
"status": "registered",
"result": "<unknown>",
"usage": {
"promptTokens": 123,
"completionTokens": 123,
"totalTokens": 123,
"inputTokens": 123,
"outputTokens": 123,
"cachedInputTokens": 123,
"reasoningTokens": 123
},
"iterations": 123
}
}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.
WorkOS session token or RunTools API key (rt_live_* / rt_test_*).
Used in Authorization: Bearer <token> header.
Run completed (non-streaming) or registered (local-mac caller).
Show child attributes