Skip to main content
POST
/
v1
/
run
Run an agent (streaming or one-shot)
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.

Authorizations

Authorization
string
header
required

WorkOS session token or RunTools API key (rt_live_* / rt_test_*). Used in Authorization: Bearer <token> header.

Body

application/json
agent
string
required

Agent slug or UUID.

prompt
string
stream
boolean
default:true
messages
object[]
threadId
string

Optional thread ID for server-managed conversation persistence.

config
object
metadata
object

Response

Run completed (non-streaming) or registered (local-mac caller).

data
object