Skip to main content
POST
/
v1
/
run
Stream Run
curl --request POST \
  --url https://api.example.com/v1/run

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.

Set stream to true, or omit it, to receive a Server-Sent Events response from POST /v1/run.
The old WebSocket path for run streams is not the current public streaming API. Use SSE from POST /v1/run.

​
Request

curl -N -X POST https://api.runtools.ai/v1/run \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "agent": "code-assistant",
    "prompt": "Create a tiny TypeScript CLI.",
    "stream": true,
    "threadId": "thr_docs_example"
  }'
Streaming responses include: 
Content-Type: text/event-stream
X-Run-ID: <run-id>
X-Thread-ID: <thread-id>

​
Event Shape

Event names and payloads are produced by the active agent runtime and may vary by execution mode. Clients should parse SSE frames generically: 
async function streamAgentRun() {
  const response = await fetch('https://api.runtools.ai/v1/run', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.RUNTOOLS_API_KEY!,
      'Content-Type': 'application/json',
      'Accept': 'text/event-stream',
    },
    body: JSON.stringify({
      agent: 'code-assistant',
      prompt: 'Run the test suite.',
      stream: true,
    }),
  });

  if (!response.body) throw new Error('No stream body');

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });

    let boundary = buffer.indexOf('\n\n');
    while (boundary !== -1) {
      const frame = buffer.slice(0, boundary);
      buffer = buffer.slice(boundary + 2);
      console.log(frame);
      boundary = buffer.indexOf('\n\n');
    }
  }
}
Common event categories include agent text deltas, tool calls, tool results, errors, and completion frames.

​
Non-Streaming Alternative

Use stream: false when you only need the final result: 
const result = await rt.agent.run('code-assistant', 'Run the tests.', {
  stream: false,
});