curl -X POST "https://app.runtm.com/api/cloud/sessions" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude-code",
"name": "API refactor",
"visibility": "team",
"env_vars": {
"NODE_ENV": "development"
}
}'
import requests
response = requests.post(
"https://app.runtm.com/api/cloud/sessions",
headers={
"Authorization": "Bearer runtm_xxx",
"X-Organization-Id": "org_abc123",
"Content-Type": "application/json",
},
json={
"agent": "claude-code",
"name": "API refactor",
"visibility": "team",
"env_vars": {"NODE_ENV": "development"},
},
)
session = response.json()
print(f"Created session: {session['id']} at {session['sandbox_url']}")
const response = await fetch(
"https://app.runtm.com/api/cloud/sessions",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_xxx",
"X-Organization-Id": "org_abc123",
"Content-Type": "application/json",
},
body: JSON.stringify({
agent: "claude-code",
name: "API refactor",
visibility: "team",
env_vars: { NODE_ENV: "development" },
}),
}
);
const session = await response.json();
console.log(`Created session: ${session.id} at ${session.sandbox_url}`);
{
"id": "ses_abc123",
"name": "API refactor",
"state": "active",
"agent": "claude-code",
"template_id": null,
"sandbox_url": "https://ses-abc123.runtm.dev",
"visibility": "team",
"user_id": "user_xyz",
"organization_id": "org_abc123",
"created_at": "2026-05-09T21:00:00Z",
"updated_at": null
}
Sessions
Create Session
Create a new cloud session with a coding agent
POST
/
api
/
sessions
curl -X POST "https://app.runtm.com/api/cloud/sessions" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude-code",
"name": "API refactor",
"visibility": "team",
"env_vars": {
"NODE_ENV": "development"
}
}'
import requests
response = requests.post(
"https://app.runtm.com/api/cloud/sessions",
headers={
"Authorization": "Bearer runtm_xxx",
"X-Organization-Id": "org_abc123",
"Content-Type": "application/json",
},
json={
"agent": "claude-code",
"name": "API refactor",
"visibility": "team",
"env_vars": {"NODE_ENV": "development"},
},
)
session = response.json()
print(f"Created session: {session['id']} at {session['sandbox_url']}")
const response = await fetch(
"https://app.runtm.com/api/cloud/sessions",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_xxx",
"X-Organization-Id": "org_abc123",
"Content-Type": "application/json",
},
body: JSON.stringify({
agent: "claude-code",
name: "API refactor",
visibility: "team",
env_vars: { NODE_ENV: "development" },
}),
}
);
const session = await response.json();
console.log(`Created session: ${session.id} at ${session.sandbox_url}`);
{
"id": "ses_abc123",
"name": "API refactor",
"state": "active",
"agent": "claude-code",
"template_id": null,
"sandbox_url": "https://ses-abc123.runtm.dev",
"visibility": "team",
"user_id": "user_xyz",
"organization_id": "org_abc123",
"created_at": "2026-05-09T21:00:00Z",
"updated_at": null
}
Creates a new cloud session backed by a sandbox environment. The session starts in a
pending state and transitions to active once the sandbox is provisioned.
Required scope: sessions:write
Headers
Body
Roster agent UUID to run the session as. Applies the agent’s system
instructions, tags the session with its identity, and fills in its default
template and harness when you don’t pass them — the same overlay a Slack or
Linear trigger gets. Subject to the agent’s
callable_by allowlist; see
Trigger a subagent.Response
Returns201 with the created session object.
curl -X POST "https://app.runtm.com/api/cloud/sessions" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude-code",
"name": "API refactor",
"visibility": "team",
"env_vars": {
"NODE_ENV": "development"
}
}'
import requests
response = requests.post(
"https://app.runtm.com/api/cloud/sessions",
headers={
"Authorization": "Bearer runtm_xxx",
"X-Organization-Id": "org_abc123",
"Content-Type": "application/json",
},
json={
"agent": "claude-code",
"name": "API refactor",
"visibility": "team",
"env_vars": {"NODE_ENV": "development"},
},
)
session = response.json()
print(f"Created session: {session['id']} at {session['sandbox_url']}")
const response = await fetch(
"https://app.runtm.com/api/cloud/sessions",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_xxx",
"X-Organization-Id": "org_abc123",
"Content-Type": "application/json",
},
body: JSON.stringify({
agent: "claude-code",
name: "API refactor",
visibility: "team",
env_vars: { NODE_ENV: "development" },
}),
}
);
const session = await response.json();
console.log(`Created session: ${session.id} at ${session.sandbox_url}`);
{
"id": "ses_abc123",
"name": "API refactor",
"state": "active",
"agent": "claude-code",
"template_id": null,
"sandbox_url": "https://ses-abc123.runtm.dev",
"visibility": "team",
"user_id": "user_xyz",
"organization_id": "org_abc123",
"created_at": "2026-05-09T21:00:00Z",
"updated_at": null
}