Skip to main content
POST
/
v1
/
run
curl -X POST https://api.runtools.ai/v1/run/my-code-bot \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a React todo app with TypeScript"
  }'

{
  "data": {
    "id": "run_abc123",
    "status": "completed",
    "output": "I've created a React todo app with TypeScript...",
    "devUrl": "https://sandbox-xyz.sandboxes.runtools.ai",
    "files": [
      "/src/App.tsx",
      "/src/components/Todo.tsx",
      "/src/types.ts"
    ],
    "usage": {
      "inputTokens": 1234,
      "outputTokens": 5678
    }
  }
}
The actual endpoint is POST /v1/run with agentSlug in the request body (not a path parameter). The orchestrator resolves the agent, finds its sandbox, and forwards to the FC Agent which runs the agent in the VM’s runtime.

​
Request Body

​
message
string
required
User message / task for the agent
​
stream
boolean
default:"false"
Enable streaming response
​
params
object
Custom parameters to pass to the run
​
mounts
array
Persistent storage mounts for this run. Each mount has workspaceId and path.
​
context
object
Additional context

​
Response (Non-Streaming)

​
id
string
Run ID
​
status
string
Final status: completed, failed, cancelled
​
output
string
Agent’s final response
​
devUrl
string
Dev server URL if applicable
​
files
array
Files created/modified
​
usage
object
Token usage stats
curl -X POST https://api.runtools.ai/v1/run/my-code-bot \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a React todo app with TypeScript"
  }'

{
  "data": {
    "id": "run_abc123",
    "status": "completed",
    "output": "I've created a React todo app with TypeScript...",
    "devUrl": "https://sandbox-xyz.sandboxes.runtools.ai",
    "files": [
      "/src/App.tsx",
      "/src/components/Todo.tsx",
      "/src/types.ts"
    ],
    "usage": {
      "inputTokens": 1234,
      "outputTokens": 5678
    }
  }
}

​
Streaming Response

Set stream: true for Server-Sent Events: 
curl -X POST https://api.runtools.ai/v1/run/my-code-bot \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"message": "Create a todo app", "stream": true}'
Events: 
event: thinking
data: {"content": "I'll create a React todo app..."}

event: tool_call
data: {"tool": "bash", "input": {"command": "npm create vite"}}

event: tool_result
data: {"output": "Done"}

event: file_edit
data: {"path": "/src/App.tsx", "diff": "..."}

event: dev_url
data: {"url": "https://sandbox-xyz.sandboxes.runtools.ai"}

event: complete
data: {"output": "Your todo app is ready!"}