curl -X POST "https://app.runtm.com/api/v0/sessions/launch" \
-H "Authorization: Bearer runtm_xxx" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Build a REST API with FastAPI that manages TODO items",
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
"ttl_minutes": 60
}'
import requests
import time
# Launch the agent
response = requests.post(
"https://app.runtm.com/api/v0/sessions/launch",
headers={"Authorization": "Bearer runtm_xxx"},
json={
"prompt": "Build a REST API with FastAPI that manages TODO items",
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
},
)
session_id = response.json()["id"]
# Poll for completion
while True:
status = requests.get(
f"https://app.runtm.com/api/v0/sessions/{session_id}",
headers={"Authorization": "Bearer runtm_xxx"},
).json()
prompt_status = (status.get("last_prompt") or {}).get("status", "idle")
if prompt_status in ("completed", "error", "timed_out"):
print(f"Done: {prompt_status}")
break
time.sleep(5)
const response = await fetch(
"https://app.runtm.com/api/v0/sessions/launch",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_xxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "Build a REST API with FastAPI that manages TODO items",
agent: "claude-code",
template: "backend-service",
on_complete: "pause",
}),
}
);
const { id } = await response.json();
console.log(`Launched session: ${id}. Poll GET /api/v0/sessions/${id} for status.`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "creating",
"message": "Agent launched. Poll GET /api/v0/sessions/{id} for status."
}
Launch Agent (v0)
Create a session and fire a prompt in one call
POST
/
api
/
v0
/
sessions
/
launch
curl -X POST "https://app.runtm.com/api/v0/sessions/launch" \
-H "Authorization: Bearer runtm_xxx" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Build a REST API with FastAPI that manages TODO items",
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
"ttl_minutes": 60
}'
import requests
import time
# Launch the agent
response = requests.post(
"https://app.runtm.com/api/v0/sessions/launch",
headers={"Authorization": "Bearer runtm_xxx"},
json={
"prompt": "Build a REST API with FastAPI that manages TODO items",
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
},
)
session_id = response.json()["id"]
# Poll for completion
while True:
status = requests.get(
f"https://app.runtm.com/api/v0/sessions/{session_id}",
headers={"Authorization": "Bearer runtm_xxx"},
).json()
prompt_status = (status.get("last_prompt") or {}).get("status", "idle")
if prompt_status in ("completed", "error", "timed_out"):
print(f"Done: {prompt_status}")
break
time.sleep(5)
const response = await fetch(
"https://app.runtm.com/api/v0/sessions/launch",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_xxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "Build a REST API with FastAPI that manages TODO items",
agent: "claude-code",
template: "backend-service",
on_complete: "pause",
}),
}
);
const { id } = await response.json();
console.log(`Launched session: ${id}. Poll GET /api/v0/sessions/${id} for status.`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "creating",
"message": "Agent launched. Poll GET /api/v0/sessions/{id} for status."
}
Creates a new cloud session, configures lifecycle policy, and fires the prompt as a background task. Returns immediately with the session ID - poll
GET /api/v0/sessions/{id} for status via the last_prompt field.
This is the core “fire and forget” endpoint for programmatic agent workflows. It’s the recommended entry point for Slack triggers, Linear automations, GitHub Actions, MCP servers, and any other webhook-driven integration.
Required scopes: sessions:write and sessions:prompt
Need to follow up after launch? Use
POST /api/v0/sessions/{id}/prompt to send another prompt (SSE stream), POST /api/v0/sessions/{id}/git to commit/push/open a PR, and DELETE /api/v0/sessions/{id} to clean up.Headers
string
required
Bearer token. Example:
Bearer runtm_xxxBody
string
required
The task/prompt for the agent (1–100,000 characters).
string
default:"claude-code"
Coding agent:
claude-code, codex, github-copilot, or opencode.string
Roster agent UUID to run the session as — the subagent entry point. The run
takes that agent’s system instructions, identity and defaults, and is graded
against its rubric. Subject to the agent’s
callable_by allowlist; see
Trigger a subagent.string
An approved approval on the calling session, when the callee’s caller
edge requires one. Resolved within the last 10 minutes.
string
Project template:
web-app, backend-service, static-site.string
Model to use:
sonnet, opus, haiku, opusplan.string
default:"autopilot"
Session mode:
autopilot or interactive.boolean
default:false
Enable plan mode (read-only analysis without making changes).
string
default:"pause"
Lifecycle action when the prompt completes:
pause, destroy, or keep_alive.integer
Max session lifetime in minutes (1–1440, default 60).
integer
default:15
Max minutes for prompt execution before timeout (1–120).
object
GitHub repo metadata:
{"full_name": "owner/repo", "size_kb": 1024}.Response
Returns201 with the session ID and initial state.
string
Session ID. Use this to poll status.
string
Initial state (
creating).string
Human-readable status message.
curl -X POST "https://app.runtm.com/api/v0/sessions/launch" \
-H "Authorization: Bearer runtm_xxx" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Build a REST API with FastAPI that manages TODO items",
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
"ttl_minutes": 60
}'
import requests
import time
# Launch the agent
response = requests.post(
"https://app.runtm.com/api/v0/sessions/launch",
headers={"Authorization": "Bearer runtm_xxx"},
json={
"prompt": "Build a REST API with FastAPI that manages TODO items",
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
},
)
session_id = response.json()["id"]
# Poll for completion
while True:
status = requests.get(
f"https://app.runtm.com/api/v0/sessions/{session_id}",
headers={"Authorization": "Bearer runtm_xxx"},
).json()
prompt_status = (status.get("last_prompt") or {}).get("status", "idle")
if prompt_status in ("completed", "error", "timed_out"):
print(f"Done: {prompt_status}")
break
time.sleep(5)
const response = await fetch(
"https://app.runtm.com/api/v0/sessions/launch",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_xxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "Build a REST API with FastAPI that manages TODO items",
agent: "claude-code",
template: "backend-service",
on_complete: "pause",
}),
}
);
const { id } = await response.json();
console.log(`Launched session: ${id}. Poll GET /api/v0/sessions/${id} for status.`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "creating",
"message": "Agent launched. Poll GET /api/v0/sessions/{id} for status."
}