> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Session (v0)

> Create a sandbox without sending a prompt

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`](/cloud-api/sessions/launch) instead.

**Required scope:** `sessions:write`

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer runtm_xxx`
</ParamField>

## Body

<ParamField body="agent" type="string" default="claude-code">
  Coding agent: `claude-code`, `codex`, `opencode`, `github-copilot`, `cursor-cli`, `devin-cli`, `gemini-cli`.
</ParamField>

<ParamField body="template" type="string">
  Project template to scaffold: `web-app`, `backend-service`, `static-site`.
</ParamField>

<ParamField body="mode" type="string" default="autopilot">
  Session mode: `autopilot` (auto-approve actions) or `interactive`.
</ParamField>

<ParamField body="github_repo" type="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 }`.
</ParamField>

<ParamField body="source" type="string" default="api">
  Origin of the session, surfaced in telemetry. Defaults to `api` for programmatic callers.
</ParamField>

<ParamField body="on_complete" type="string">
  Lifecycle action when prompts complete: `pause` (default), `destroy`, or `keep_alive`.
</ParamField>

<ParamField body="ttl_minutes" type="integer">
  Maximum session lifetime in minutes (1–1440). Acts as a safety net for background agents.
</ParamField>

## Response

Returns `201` with the created session.

<ResponseField name="id" type="string">Session ID - use this for subsequent prompt/git/destroy calls.</ResponseField>
<ResponseField name="state" type="string">Initial state (typically `creating`).</ResponseField>
<ResponseField name="agent" type="string">Coding agent assigned to the session.</ResponseField>
<ResponseField name="template" type="string | null">Template used.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
<ResponseField name="expires_at" type="string | null">TTL expiry, if `ttl_minutes` was set.</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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']})")
  ```

  ```javascript JavaScript theme={null}
  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})`);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>