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
string
required
Bearer token. Example:
Bearer runtm_xxxstring
Scope the session to an organization.
Body
string
required
Coding agent to use:
claude-code, codex, cursor, gemini, etc.string
Template ID to initialize the session from.
string
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.string
An approved approval on the calling session, when the callee’s caller
edge requires one.
string
Display name for the session.
string
default:"private"
Session visibility:
private or team.object
Key-value pairs of environment variables to inject into the sandbox.
Response
Returns201 with the created session object.
string
Session ID (e.g.
ses_abc123).string
Display name.
string
Session state:
active, paused, or destroyed.string
Coding agent assigned to the session.
string | null
Template used to initialize the session.
string
URL of the sandbox environment.
string
Session visibility.
string
Owner user ID.
string | null
Organization the session belongs to.
string
ISO 8601 creation timestamp.
string | null
ISO 8601 last update timestamp.
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
}