# Sessions

The sessions running on your AI teams.



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## List sessions [#list-sessions]

    <ApiEndpointHeader method="GET" path="/v1/sessions" scope="sessions:read" />

    The sessions the key's holder can see, narrowed by the key's team restriction.

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>

      <ApiParam name="team" type="string">
        Only sessions of this AI team.
      </ApiParam>

      <ApiParam name="status" type="string">
        Only sessions in this state. One of `starting`, `running`, `stopped`, `error`.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [Session](#session) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of sessions.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/sessions \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/sessions",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "session",
          "id": "sess_0a843Y2wTmED2k3FJPP56X",
          "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
          "name": "Weekly competitor scan",
          "status": "running",
          "engine": "claude",
          "run_with": "personal",
          "owner": "user_yFfQdB3rxA41x3cTD5fx2Q",
          "permission_mode": "default",
          "token_count": 184320,
          "cost_usd": 2.41,
          "last_activity_at": "2026-10-14T16:05:31.000Z",
          "created_at": "2026-10-14T15:20:02.000Z",
          "created_by": {
            "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
            "name": "Maya Chen"
          }
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get a session [#get-a-session]

    <ApiEndpointHeader method="GET" path="/v1/sessions/{session_id}" scope="sessions:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Session](#session) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The session.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "session",
      "id": "sess_0a843Y2wTmED2k3FJPP56X",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Weekly competitor scan",
      "status": "running",
      "engine": "claude",
      "run_with": "personal",
      "owner": "user_yFfQdB3rxA41x3cTD5fx2Q",
      "permission_mode": "default",
      "token_count": 184320,
      "cost_usd": 2.41,
      "last_activity_at": "2026-10-14T16:05:31.000Z",
      "created_at": "2026-10-14T15:20:02.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Rename a session [#rename-a-session]

    <ApiEndpointHeader method="PATCH" path="/v1/sessions/{session_id}" scope="sessions:operate" />

    The name only. Who a session belongs to, its mode and its terminal stay in HQ.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="name" type="string" required="true" />
    </ApiParams>

    **Returns** a [Session](#session) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The session.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PATCH https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"name":"Competitor scan, October"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X', {
          method: 'PATCH',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ name: 'Competitor scan, October' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.patch(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"name": "Competitor scan, October"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "session",
      "id": "sess_0a843Y2wTmED2k3FJPP56X",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Weekly competitor scan",
      "status": "running",
      "engine": "claude",
      "run_with": "personal",
      "owner": "user_yFfQdB3rxA41x3cTD5fx2Q",
      "permission_mode": "default",
      "token_count": 184320,
      "cost_usd": 2.41,
      "last_activity_at": "2026-10-14T16:05:31.000Z",
      "created_at": "2026-10-14T15:20:02.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Delete a session [#delete-a-session]

    <ApiEndpointHeader method="DELETE" path="/v1/sessions/{session_id}" scope="sessions:delete" />

    An org owner or admin only. Stops it if it runs, then deletes it and its schedules.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="204">
        Deleted.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X', {
          method: 'DELETE',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(res.status);
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Deleted.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get a session's token usage [#get-a-sessions-token-usage]

    <ApiEndpointHeader method="GET" path="/v1/sessions/{session_id}/usage" scope="sessions:read" />

    The newest `limit` usage samples, returned oldest first.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [SessionUsage](#sessionusage) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The usage samples.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/usage \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/usage', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/usage",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "session_usage",
      "session": "sess_0a843Y2wTmED2k3FJPP56X",
      "samples": [
        {
          "at": "2026-10-14T15:00:00.000Z",
          "tokens": 12880,
          "cost_usd": 0.17
        },
        {
          "at": "2026-10-14T16:00:00.000Z",
          "tokens": 40112,
          "cost_usd": 0.52
        }
      ]
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Create a session [#create-a-session]

    <ApiEndpointHeader method="POST" path="/v1/teams/{team_id}/sessions" scope="sessions:create" />

    Creates a session on the AI team and, unless `start` is false, starts it. `run_with:
    "personal"` binds the member the user key acts as (their own Claude or ChatGPT login); a
    service key cannot (422 `personal_login_not_available`). `run_with: "team_key"` also needs
    `sessions:run_with_team_key` on the team. The plan's session limit applies. When the AI
    team is paused, a start answers 409 `workspace_paused`, and while its Cloud Computer is
    being updated or resized, 409 `workspace_updating`; while it is too busy for another
    session, 409 `machine_busy` (either way the session is created, stopped). Requires an
    `Idempotency-Key`.
    On an AI team that turned on Protected files, a Codex session (named, or the team's only engine) needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise.

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string" required="true">
        Required here. The same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422; while the first
        request is still running, 409 `idempotency_in_progress`.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="run_with" type="string" required="true">
        personal: the user key's own member's login. team_key: the AI team's key. One of `personal`, `team_key`.
      </ApiParam>

      <ApiParam name="engine" type="string">
        Required on a team that runs both engines. One of `claude`, `codex`.
      </ApiParam>

      <ApiParam name="name" type="string" />

      <ApiParam name="start" type="boolean" />

      <ApiParam name="permission_mode" type="string">
        One of `default`, `acceptEdits`, `bypassPermissions`.
      </ApiParam>
    </ApiParams>

    **Returns** a [Session](#session) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The session, starting (or stopped when `start` was false).
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/sessions \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"run_with":"personal"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/sessions', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ run_with: 'personal' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/sessions",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"run_with": "personal"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "session",
      "id": "sess_0a843Y2wTmED2k3FJPP56X",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Weekly competitor scan",
      "status": "running",
      "engine": "claude",
      "run_with": "personal",
      "owner": "user_yFfQdB3rxA41x3cTD5fx2Q",
      "permission_mode": "default",
      "token_count": 184320,
      "cost_usd": 2.41,
      "last_activity_at": "2026-10-14T16:05:31.000Z",
      "created_at": "2026-10-14T15:20:02.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Start a session [#start-a-session]

    <ApiEndpointHeader method="POST" path="/v1/sessions/{session_id}/start" scope="sessions:operate" />

    Starts a stopped session. Its owner, or an org owner or admin, may start it. A service key
    never starts an unclaimed personal-login session (starting it would bind a login). When the
    AI team is paused, the answer is 409 `workspace_paused`; while its Cloud Computer is being
    updated or resized, 409 `workspace_updating`; while it is too busy for another session,
    409 `machine_busy`.
    On an AI team that turned on Protected files, a Codex session start needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Session](#session) object.

    <ApiParams title="Responses">
      <ApiParam name="202">
        The session, starting. Follow `GET /sessions/{session_id}` or its event stream.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/start \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/start', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/start",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 202"
    {
      "object": "session",
      "id": "sess_0a843Y2wTmED2k3FJPP56X",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Weekly competitor scan",
      "status": "running",
      "engine": "claude",
      "run_with": "personal",
      "owner": "user_yFfQdB3rxA41x3cTD5fx2Q",
      "permission_mode": "default",
      "token_count": 184320,
      "cost_usd": 2.41,
      "last_activity_at": "2026-10-14T16:05:31.000Z",
      "created_at": "2026-10-14T15:20:02.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Stop a session [#stop-a-session]

    <ApiEndpointHeader method="POST" path="/v1/sessions/{session_id}/stop" scope="sessions:operate" />

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Session](#session) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The session, stopped.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/stop \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/stop', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/stop",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "session",
      "id": "sess_0a843Y2wTmED2k3FJPP56X",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Weekly competitor scan",
      "status": "running",
      "engine": "claude",
      "run_with": "personal",
      "owner": "user_yFfQdB3rxA41x3cTD5fx2Q",
      "permission_mode": "default",
      "token_count": 184320,
      "cost_usd": 2.41,
      "last_activity_at": "2026-10-14T16:05:31.000Z",
      "created_at": "2026-10-14T15:20:02.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Restart a session [#restart-a-session]

    <ApiEndpointHeader method="POST" path="/v1/sessions/{session_id}/restart" scope="sessions:operate" />

    Stops and starts the session. `fresh` starts a new conversation instead of resuming. When
    the AI team is paused, the answer is 409 `workspace_paused`; while its Cloud Computer is
    being updated or resized, 409 `workspace_updating`; while it is too busy for another
    session, 409 `machine_busy`. Either way a running session keeps running.
    On an AI team that turned on Protected files, a Codex session restart needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="fresh" type="boolean">
        Start a new conversation instead of resuming the last one.
      </ApiParam>
    </ApiParams>

    **Returns** a [Session](#session) object.

    <ApiParams title="Responses">
      <ApiParam name="202">
        The session, starting again.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/restart \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"fresh":false}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/restart', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ fresh: false }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/restart",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"fresh": False},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 202"
    {
      "object": "session",
      "id": "sess_0a843Y2wTmED2k3FJPP56X",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Weekly competitor scan",
      "status": "running",
      "engine": "claude",
      "run_with": "personal",
      "owner": "user_yFfQdB3rxA41x3cTD5fx2Q",
      "permission_mode": "default",
      "token_count": 184320,
      "cost_usd": 2.41,
      "last_activity_at": "2026-10-14T16:05:31.000Z",
      "created_at": "2026-10-14T15:20:02.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Interrupt the current turn [#interrupt-the-current-turn]

    <ApiEndpointHeader method="POST" path="/v1/sessions/{session_id}/interrupt" scope="sessions:type" />

    Presses Esc in the session, as the Chat view's Stop button does. The same keyboard rule as
    sending a message applies. While Claude is holding a message from another session, Esc
    would decline it: the answer is `409 held_peer_message` and nothing is pressed. Deliver or
    deny the message in the session in HQ, then interrupt again.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="204">
        Esc was pressed.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/interrupt \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/interrupt', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(res.status);
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/interrupt",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Esc was pressed.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## List a session's conversation [#list-a-sessions-conversation]

    <ApiEndpointHeader method="GET" path="/v1/sessions/{session_id}/items" scope="sessions:chat.read" />

    The conversation as HQ's Chat view shows it: messages, tool uses, thinking markers and
    notices, masked. Newest page by default; page with the `start_cursor` / `end_cursor` the
    response returns. Never wakes a sleeping machine (409 while it sleeps).

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="after" type="string">
        A cursor from this session (`end_cursor`, or an event `id`); return what follows it.
      </ApiParam>

      <ApiParam name="before" type="string">
        A cursor from this session (`start_cursor`); return what precedes it.
      </ApiParam>

      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [SessionItemList](#sessionitemlist) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of items, oldest first.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "session_item",
          "id": "item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw",
          "type": "message",
          "seq": 214,
          "at": "2026-10-14T16:05:31.000Z",
          "engine": "claude",
          "role": "assistant",
          "content": [
            {
              "type": "text",
              "text": "Three competitors changed their pricing this week. The brief is in reports/weekly.md."
            }
          ]
        }
      ],
      "has_more": false,
      "start_cursor": "c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjQ4MjEzfQ",
      "end_cursor": "c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjUxODc3fQ"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get a tool use's or a thinking block's detail [#get-a-tool-uses-or-a-thinking-blocks-detail]

    <ApiEndpointHeader method="GET" path="/v1/sessions/{session_id}/items/{item_id}/detail" scope="sessions:chat.read" />

    The masked detail behind an item's `detail_ref` (256 KiB at most).

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>

      <ApiParam name="item_id" type="string" required="true">
        A session item id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="ref" type="string" required="true">
        The item's `detail_ref`.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [SessionItemDetail](#sessionitemdetail) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The detail.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items/item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw/detail?ref=d1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsInUiOltbNTE4NzcsMV1dLCJyIjpbWzUyNDEwLDBdXX0" \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items/item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw/detail?ref=d1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsInUiOltbNTE4NzcsMV1dLCJyIjpbWzUyNDEwLDBdXX0', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items/item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw/detail?ref=d1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsInUiOltbNTE4NzcsMV1dLCJyIjpbWzUyNDEwLDBdXX0",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "session_item_detail",
      "kind": "diff",
      "tool": "Edit",
      "target": ["reports/weekly.md"],
      "files": null,
      "diff": [
        {
          "path": "reports/weekly.md",
          "before": "## Pricing\n\nNo changes.\n",
          "after": "## Pricing\n\nThree competitors changed their pricing.\n"
        }
      ],
      "output": null,
      "error": null,
      "thinking": null,
      "truncated": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Stream a session's events [#stream-a-sessions-events]

    <ApiEndpointHeader method="GET" path="/v1/sessions/{session_id}/events" scope="sessions:chat.read" />

    Server-Sent Events: `session.message.completed`, `session.tool_use.started|completed|failed`,
    `session.thinking.completed`, `session.notice`, `session.status`, `session.input_required`,
    `session.turn.completed` and `session.message.status_changed`, each a JSON event envelope.
    Reconnect with `Last-Event-ID` to resume without a gap. `: ping` every 15 s; `stream.rotate`
    at 50 minutes (reconnect); `stream.reset` when you fell behind (list the items, then
    reconnect). A stream never wakes the machine. At most 4 streams per session.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="after" type="string">
        A cursor from this session (`end_cursor`, or an event `id`); return what follows it.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Last-Event-ID" type="string">
        The `id` of the last event you received.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="200">
        The event stream.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -N https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/events \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/events', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        const decoder = new TextDecoder();
        for await (const chunk of res.body) {
          process.stdout.write(decoder.decode(chunk, { stream: true }));
        }
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/events",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
            stream=True,
        )
        for line in res.iter_lines(decode_unicode=True):
            print(line)
        ```
      </Tab>
    </Tabs>

    ```text title="Response 200"
    id: c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjUxODc3fQ
    event: session.message.completed
    data: {"id":"evt_9OvoJuvytSGhqe71vQ9tqx","object":"event","type":"session.message.completed","api_version":"2026-11-01","created_at":"2026-10-14T16:05:31.000Z","org_id":"org_3SvwLF4ulih8bHz5KtmNOO","team_id":"team_3kQ9vX2mR8tLpZ4wYc1aBd","resource":{"type":"session","id":"sess_0a843Y2wTmED2k3FJPP56X"},"data":{"session_id":"sess_0a843Y2wTmED2k3FJPP56X","item_id":"item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw","seq":214,"at":"2026-10-14T16:05:31.000Z","engine":"claude","role":"assistant","content":[{"type":"text","text":"The brief is in reports/weekly.md."}]}}

    event: session.turn.completed
    data: {"id":"evt_Q2m8XcR4tV7bN1kL9pZ3wD","object":"event","type":"session.turn.completed","api_version":"2026-11-01","created_at":"2026-10-14T16:05:33.000Z","org_id":"org_3SvwLF4ulih8bHz5KtmNOO","team_id":"team_3kQ9vX2mR8tLpZ4wYc1aBd","resource":{"type":"session","id":"sess_0a843Y2wTmED2k3FJPP56X"},"data":{"session_id":"sess_0a843Y2wTmED2k3FJPP56X"}}
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Send a message [#send-a-message]

    <ApiEndpointHeader method="POST" path="/v1/sessions/{session_id}/messages" scope="sessions:type" />

    Sends a prompt to a running session; follow `session.message.status_changed` on the event
    stream, or this message. A personal-login session accepts messages only from its owner's own
    user key (403 `session_not_owned` for anyone else); a team-key session needs
    `sessions:run_with_team_key`. A sleeping machine is woken (`waiting_for: "wake"`). A prompt
    is typed at most once. Requires an `Idempotency-Key`.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string" required="true">
        Required here. The same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422; while the first
        request is still running, 409 `idempotency_in_progress`.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="content" type="array of object" required="true" />
    </ApiParams>

    **Returns** a [Message](#message) object.

    <ApiParams title="Responses">
      <ApiParam name="202">
        Accepted. Delivery continues in the background.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{
            "content": [
              {
                "type": "text",
                "text": "List the open pull requests"
              }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ content: [{ type: 'text', text: 'List the open pull requests' }] }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={
                "content": [{"type": "text", "text": "List the open pull requests"}],
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 202"
    {
      "object": "message",
      "id": "msg_jtGNtRjFCseJiNrAp3v6bQ",
      "session": "sess_0a843Y2wTmED2k3FJPP56X",
      "status": "accepted",
      "waiting_for": null,
      "code": null,
      "text_bytes": 27,
      "image_count": 0,
      "delivered_item": null,
      "deadline_at": "2026-10-14T16:20:31.000Z",
      "created_at": "2026-10-14T16:05:31.000Z",
      "updated_at": "2026-10-14T16:05:31.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get a message's delivery state [#get-a-messages-delivery-state]

    <ApiEndpointHeader method="GET" path="/v1/sessions/{session_id}/messages/{message_id}" scope="sessions:chat.read" />

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>

      <ApiParam name="message_id" type="string" required="true">
        A message id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Message](#message) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The message.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages/msg_jtGNtRjFCseJiNrAp3v6bQ \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages/msg_jtGNtRjFCseJiNrAp3v6bQ', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages/msg_jtGNtRjFCseJiNrAp3v6bQ",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "message",
      "id": "msg_jtGNtRjFCseJiNrAp3v6bQ",
      "session": "sess_0a843Y2wTmED2k3FJPP56X",
      "status": "accepted",
      "waiting_for": null,
      "code": null,
      "text_bytes": 27,
      "image_count": 0,
      "delivered_item": null,
      "deadline_at": "2026-10-14T16:20:31.000Z",
      "created_at": "2026-10-14T16:05:31.000Z",
      "updated_at": "2026-10-14T16:05:31.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Answer a permission, plan or question card [#answer-a-permission-plan-or-question-card]

    <ApiEndpointHeader method="POST" path="/v1/sessions/{session_id}/actions" scope="sessions:type" />

    Answers the card a `session.input_required` event announced (`answerable_via_api: true`),
    naming its `instance_id` and `digest`. The server re-reads the screen and types only the
    recorded keys for the choice. The keyboard rule of messages applies. Requires an
    `Idempotency-Key`.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string" required="true">
        Required here. The same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422; while the first
        request is still running, 409 `idempotency_in_progress`.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="instance_id" type="string" required="true" />

      <ApiParam name="digest" type="string" required="true" />

      <ApiParam name="intent" type="string">
        One of `select`, `toggle`, `otherText`, `next`, `back`, `review`, `submit`, `cancel`.
      </ApiParam>

      <ApiParam name="choice_id" type="string" />

      <ApiParam name="text" type="string" />
    </ApiParams>

    **Returns** a [SessionActionResult](#sessionactionresult) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The answer was applied.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/actions \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"instance_id":"m_8f2c41","digest":"a3f9c27e"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/actions', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ instance_id: 'm_8f2c41', digest: 'a3f9c27e' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/actions",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"instance_id": "m_8f2c41", "digest": "a3f9c27e"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "session_action",
      "status": "applied",
      "digest": "b71d04c5"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### Session [#session]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="team" type="string" />

      <ApiParam name="name" type="string" />

      <ApiParam name="status" type="string">
        Open-ended: starting, running, stopped, error.
      </ApiParam>

      <ApiParam name="engine" type="string or null" />

      <ApiParam name="run_with" type="string or null">
        personal (the owner's own login) or team_key.
      </ApiParam>

      <ApiParam name="owner" type="string or null" />

      <ApiParam name="permission_mode" type="string" />

      <ApiParam name="token_count" type="integer" />

      <ApiParam name="cost_usd" type="number" />

      <ApiParam name="last_activity_at" type="string or null" />

      <ApiParam name="created_at" type="string or null" />

      <ApiParam name="created_by" type="UserRef" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Session object"
    {
      "object": "session",
      "id": "sess_0a843Y2wTmED2k3FJPP56X",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Weekly competitor scan",
      "status": "running",
      "engine": "claude",
      "run_with": "personal",
      "owner": "user_yFfQdB3rxA41x3cTD5fx2Q",
      "permission_mode": "default",
      "token_count": 184320,
      "cost_usd": 2.41,
      "last_activity_at": "2026-10-14T16:05:31.000Z",
      "created_at": "2026-10-14T15:20:02.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### SessionUsage [#sessionusage]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="session" type="string" />

      <ApiParam name="samples" type="array of object" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The SessionUsage object"
    {
      "object": "session_usage",
      "session": "sess_0a843Y2wTmED2k3FJPP56X",
      "samples": [
        {
          "at": "2026-10-14T15:00:00.000Z",
          "tokens": 12880,
          "cost_usd": 0.17
        },
        {
          "at": "2026-10-14T16:00:00.000Z",
          "tokens": 40112,
          "cost_usd": 0.52
        }
      ]
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### SessionItemList [#sessionitemlist]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" required="true" />

      <ApiParam name="data" type="array of SessionItem" required="true" />

      <ApiParam name="has_more" type="boolean" required="true" />

      <ApiParam name="start_cursor" type="string or null" />

      <ApiParam name="end_cursor" type="string or null" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The SessionItemList object"
    {
      "object": "list",
      "data": [
        {
          "object": "session_item",
          "id": "item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw",
          "type": "message",
          "seq": 214,
          "at": "2026-10-14T16:05:31.000Z",
          "engine": "claude",
          "role": "assistant",
          "content": [
            {
              "type": "text",
              "text": "Three competitors changed their pricing this week. The brief is in reports/weekly.md."
            }
          ]
        }
      ],
      "has_more": false,
      "start_cursor": "c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjQ4MjEzfQ",
      "end_cursor": "c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjUxODc3fQ"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### SessionItemDetail [#sessionitemdetail]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="kind" type="string">
        Open-ended: diff, command, file_list, raw, thinking.
      </ApiParam>

      <ApiParam name="tool" type="string or null" />

      <ApiParam name="target" type="array of string or null" />

      <ApiParam name="files" type="array of string or null" />

      <ApiParam name="diff" type="array of object or null" />

      <ApiParam name="output" type="string or null" />

      <ApiParam name="error" type="string or null" />

      <ApiParam name="thinking" type="string or null" />

      <ApiParam name="truncated" type="boolean" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The SessionItemDetail object"
    {
      "object": "session_item_detail",
      "kind": "diff",
      "tool": "Edit",
      "target": ["reports/weekly.md"],
      "files": null,
      "diff": [
        {
          "path": "reports/weekly.md",
          "before": "## Pricing\n\nNo changes.\n",
          "after": "## Pricing\n\nThree competitors changed their pricing.\n"
        }
      ],
      "output": null,
      "error": null,
      "thinking": null,
      "truncated": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### Message [#message]

    A prompt sent over the API. Its text is never stored or returned.

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="session" type="string" />

      <ApiParam name="status" type="string">
        Open-ended: accepted, queued, typing, submitted, delivered, unconfirmed, blocked_by_moment, failed.
      </ApiParam>

      <ApiParam name="waiting_for" type="string or null">
        While queued: wake, ready or moment.
      </ApiParam>

      <ApiParam name="code" type="string or null">
        Why it failed, when it did.
      </ApiParam>

      <ApiParam name="text_bytes" type="integer" />

      <ApiParam name="image_count" type="integer" />

      <ApiParam name="delivered_item" type="string or null">
        The conversation item that proved delivery.
      </ApiParam>

      <ApiParam name="deadline_at" type="string (date-time)" />

      <ApiParam name="created_at" type="string (date-time)" />

      <ApiParam name="updated_at" type="string (date-time)" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Message object"
    {
      "object": "message",
      "id": "msg_jtGNtRjFCseJiNrAp3v6bQ",
      "session": "sess_0a843Y2wTmED2k3FJPP56X",
      "status": "accepted",
      "waiting_for": null,
      "code": null,
      "text_bytes": 27,
      "image_count": 0,
      "delivered_item": null,
      "deadline_at": "2026-10-14T16:20:31.000Z",
      "created_at": "2026-10-14T16:05:31.000Z",
      "updated_at": "2026-10-14T16:05:31.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### SessionActionResult [#sessionactionresult]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="status" type="string" />

      <ApiParam name="digest" type="string or null">
        The card's new digest, for a next press on the same card.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The SessionActionResult object"
    {
      "object": "session_action",
      "status": "applied",
      "digest": "b71d04c5"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
