curl -X POST "https://app.runtm.com/api/v0/sessions" \
-H "Authorization: Bearer runtm_xxx" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
"ttl_minutes": 60
}'
import requests
response = requests.post(
"https://app.runtm.com/api/v0/sessions",
headers={"Authorization": "Bearer runtm_xxx"},
json={
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
"ttl_minutes": 60,
},
)
session = response.json()
print(f"Created: {session['id']} (state={session['state']})")
const response = await fetch(
"https://app.runtm.com/api/v0/sessions",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_xxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
agent: "claude-code",
template: "backend-service",
on_complete: "pause",
ttl_minutes: 60,
}),
}
);
const session = await response.json();
console.log(`Created: ${session.id} (state=${session.state})`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "creating",
"agent": "claude-code",
"template": "backend-service",
"created_at": "2026-05-09T21:00:00Z",
"expires_at": "2026-05-09T22:00:00Z"
}
Create Session (v0)
Create a sandbox without sending a prompt
POST
/
api
/
v0
/
sessions
curl -X POST "https://app.runtm.com/api/v0/sessions" \
-H "Authorization: Bearer runtm_xxx" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
"ttl_minutes": 60
}'
import requests
response = requests.post(
"https://app.runtm.com/api/v0/sessions",
headers={"Authorization": "Bearer runtm_xxx"},
json={
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
"ttl_minutes": 60,
},
)
session = response.json()
print(f"Created: {session['id']} (state={session['state']})")
const response = await fetch(
"https://app.runtm.com/api/v0/sessions",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_xxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
agent: "claude-code",
template: "backend-service",
on_complete: "pause",
ttl_minutes: 60,
}),
}
);
const session = await response.json();
console.log(`Created: ${session.id} (state=${session.state})`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "creating",
"agent": "claude-code",
"template": "backend-service",
"created_at": "2026-05-09T21:00:00Z",
"expires_at": "2026-05-09T22:00:00Z"
}
Creates a new cloud session backed by a sandbox. The session starts in
creating state and transitions to running once the sandbox is provisioned.
Use this when you need to set up a sandbox up-front and decide what prompt to send later. If you want to fire a prompt at the same time you create the session, use POST /api/v0/sessions/launch instead.
Required scope: sessions:write
Headers
string
required
Bearer token. Example:
Bearer runtm_xxxBody
string
default:"claude-code"
Coding agent:
claude-code, codex, opencode, github-copilot, cursor-cli, devin-cli, gemini-cli.string
Project template to scaffold:
web-app, backend-service, static-site.string
default:"autopilot"
Session mode:
autopilot (auto-approve actions) or interactive.object
GitHub repo metadata for tier selection. Shape:
{ "full_name": "owner/repo", "size_kb": 1024, "requires_docker": false, "has_docker_compose": false, "is_monorepo": false }.string
default:"api"
Origin of the session, surfaced in telemetry. Defaults to
api for programmatic callers.string
Lifecycle action when prompts complete:
pause (default), destroy, or keep_alive.integer
Maximum session lifetime in minutes (1–1440). Acts as a safety net for background agents.
Response
Returns201 with the created session.
string
Session ID - use this for subsequent prompt/git/destroy calls.
string
Initial state (typically
creating).string
Coding agent assigned to the session.
string | null
Template used.
string
ISO 8601 creation timestamp.
string | null
TTL expiry, if
ttl_minutes was set.curl -X POST "https://app.runtm.com/api/v0/sessions" \
-H "Authorization: Bearer runtm_xxx" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
"ttl_minutes": 60
}'
import requests
response = requests.post(
"https://app.runtm.com/api/v0/sessions",
headers={"Authorization": "Bearer runtm_xxx"},
json={
"agent": "claude-code",
"template": "backend-service",
"on_complete": "pause",
"ttl_minutes": 60,
},
)
session = response.json()
print(f"Created: {session['id']} (state={session['state']})")
const response = await fetch(
"https://app.runtm.com/api/v0/sessions",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_xxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
agent: "claude-code",
template: "backend-service",
on_complete: "pause",
ttl_minutes: 60,
}),
}
);
const session = await response.json();
console.log(`Created: ${session.id} (state=${session.state})`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "creating",
"agent": "claude-code",
"template": "backend-service",
"created_at": "2026-05-09T21:00:00Z",
"expires_at": "2026-05-09T22:00:00Z"
}