# Authentication

> Create an API key and authenticate requests.

Source: https://www.ellipsis.dev/docs/api/authentication

Create a key under **API > API keys** in the dashboard. Copy the secret when it is shown; it cannot be retrieved later.

## Bearer token

Store the key in `ELLIPSIS_API_TOKEN`:

```bash
export ELLIPSIS_API_TOKEN="ellipsis_key_..."
```

Send it on each request:

```bash
curl https://api.ellipsis.dev/v1/identity \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

The identity response identifies the account and credential. An API key acts for its account, with no individual user identity.

## Permissions

An invalid or revoked token returns `401`. A valid credential without access returns `403`.

Account financial settings require an owner or organization administrator's user credential. API keys and sandbox credentials cannot change them.

Revoke a key from the dashboard when it is no longer needed. Keep keys on your server; do not embed them in browser code or committed configuration.

---

# API overview

> Start sessions, run automations, and integrate reviews with the Ellipsis API.

Source: https://www.ellipsis.dev/docs/api

The base URL is `https://api.ellipsis.dev/v1`. Authenticate with a bearer token from the dashboard's **API** page.

## Start a session

```bash
curl https://api.ellipsis.dev/v1/sessions \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": "api-environment",
  "lifecycle": {
    "interactive": false
  },
  "budget": 3,
  "claude_code": {
    "prompt": "Run the tests and report failures."
  }
}'
```

The response contains `session.id`. Creation returns before the task finishes.

## Choose a resource

| Resource                               | Operations                                              |
| -------------------------------------- | ------------------------------------------------------- |
| [Sessions](/docs/api/sessions)         | Start tasks, send messages, inspect changes and results |
| [Automations](/docs/api/automations)   | Manage saved definitions and invoke them                |
| [Environments](/docs/api/environments) | Manage reusable sandbox configuration                   |
| [Secrets](/docs/api/secrets)           | Store credentials referenced by environments            |
| [Reviews](/docs/api/reviews)           | Run and inspect pull request reviews                    |
| [Account](/docs/api/account)           | Read model support, budget, and usage                   |
| [Integrations](/docs/api/integrations) | Read connected integrations and available repositories  |

The reference covers supported integration workflows. The [OpenAPI document](/openapi.v1.json) also contains endpoints used by the dashboard.

## SDKs

The [Python SDK](/docs/api/python-sdk) and [TypeScript SDK](/docs/api/typescript-sdk) provide session handles, streaming, pagination, and typed errors.

## Errors and retries

Errors use `{"error":{"code":"...","message":"..."}}`. Branch on `code`; message text can change.

| Status       | Action                                               |
| ------------ | ---------------------------------------------------- |
| `400`, `422` | Correct the request or unsupported configuration     |
| `401`, `403` | Check the credential and its permissions             |
| `404`        | Check the resource ID and account                    |
| `409`        | Resolve a conflict, such as a git-managed definition |
| `429`        | Respect `Retry-After`                                |
| `5xx`        | Retry with backoff                                   |

Do not blindly retry session creation after an ambiguous timeout; it can create another session. Tag requests with `metadata` and check existing sessions when needed. Message sends support an `idempotency_key`.

## Pagination

Paginated endpoints accept `limit` and `cursor`. Pass the returned `next_cursor` until `has_more` is false. SDK iterators fetch subsequent pages automatically.

---

# Python SDK

> Start sessions, stream records, and invoke automations from Python.

Source: https://www.ellipsis.dev/docs/api/python-sdk

## Install

Python 3.10 or newer. The `stream` extra enables live session streaming.

```bash
pip install 'ellipsis-dev[stream]'
```

## Start a session

```python
import os

from ellipsis import Ellipsis
from ellipsis.models import ClaudeConfig

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
handle = client.sessions.run(
    claude_code=ClaudeConfig(prompt="Run the tests and report failures."),
    environment="api-environment",
    lifecycle={"interactive": False},
    budget=3,
)
session = handle.wait(timeout=900)
print(session.lifecycle.status, session.lifecycle.last_execution_result)
```

`run` returns a handle while work continues. `wait` polls until the session settles. A timeout stops waiting and leaves the session running.

Use `sessions.handle(session_id)` to attach to an existing session.

## Continue a conversation

Leave `lifecycle.interactive` enabled to accept messages:

```python
handle = client.sessions.run(
    claude_code=ClaudeConfig(prompt="Investigate the failing validation test."),
    environment="api-environment",
    budget=5,
)
handle.wait(timeout=900)
handle.send("Add a regression test.", idempotency_key="add-test")
handle.wait(timeout=900)
handle.stop()
```

The same message key is accepted once per session. A message during an active turn waits for the next turn.

## Invoke an automation

```python
response = client.agents.run(
    "test-repair",
    prompt="Investigate the request validation tests.",
)
session = client.sessions.handle(response.session.id).wait()
print(session.lifecycle.last_execution_result)
```

For an automation with an input schema, pass `input` instead:

```python
response = client.agents.run(
    "classify-change",
    input={"description": "Reject expired reset tokens"},
)
```

## Stream a session

See [Session events](/docs/api/session-events) for every modeled event and complete JSON examples.

```python
import asyncio
import os

from ellipsis import AsyncEllipsis
from ellipsis.models import ClaudeConfig

async def main():
    async with AsyncEllipsis(
        api_key=os.environ["ELLIPSIS_API_TOKEN"]
    ) as client:
        handle = await client.sessions.run(
            claude_code=ClaudeConfig(prompt="Explain how to test a request validator."),

            lifecycle={"interactive": False},
        )
        outcome = await handle.stream(lambda frame: print(frame.type))
        print(outcome.type)

asyncio.run(main())
```

Use `AsyncEllipsis` for asynchronous requests and streaming. Complete records persist; partial text deltas are live-only.

## Read results

```python
for execution in client.sessions.executions(handle.id).executions:
    if execution.result is not None:
        print(execution.result.text)

for session in client.sessions.list(days=7):
    print(session.id, session.lifecycle.last_execution_result)
```

SDK page iterators fetch every page. For manual pagination, use `items`, `has_more`, and `next_cursor`.

## Errors

```python
from ellipsis import APIError

try:
    client.sessions.get("session_missing")
except APIError as error:
    print(error.status, error.code)
```

The client defaults to a 60-second request timeout and two retries for transport errors, `429`, `502`, `503`, and `504`. Configure `timeout` and `max_retries` when creating it.

---

# Session events

> Every modeled session event, with JSON examples for platform, harness, and streaming consumers.

Source: https://www.ellipsis.dev/docs/api/session-events

Read session records through [List records](/docs/api/sessions/get-sessions-session_id-records) or receive them in a live stream's `records_append` frames. Open an event to see its example JSON and detailed field specification. Events are grouped by producer and ordered roughly from startup through execution to completion and recovery.

The session's own `event` field identifies the external event that started it. The records on this page describe activity throughout that session. See [Sessions](/docs/sessions#inspect-the-result) for `source` and `event` fields.

Examples are illustrative, independent messages, not a consecutive transcript. Optional native fields vary by harness version. Platform and transport types are listed in full; native harnesses can also send additional types through [unknown records](#unknown-records).

- [Platform](#platform): session, sandbox, inbox, and turn events.
- [Claude Code](#claude-code): native messages and turn results.
- [Codex](#codex): native app-server notifications.
- [WebSocket frames](#websocket-frames): delivery, live output, and connection state.
- [Historical formats](#historical-formats): records retained from older sessions.

For the important transitions and how turns, idle periods, and closure relate, start with [Lifecycle](/docs/lifecycle).

## Read an event

| Field                  | How to use it                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `kind`                 | Select the typed record variant: `platform`, `claude_code`, `codex_app_server`, `claude_sdk`, `codex`, or `unknown`. |
| `source`               | Identify the producer: `lifecycle`, `claude_code`, or `codex`.                                                       |
| `record_format`        | Select the payload version; existing history retains its original format.                                            |
| `record_type`          | Identify the event within its format.                                                                                |
| `payload`              | Read the platform fields or the unchanged native message.                                                            |
| `feed_seq`             | Order records within a session and resume the stream after this position.                                            |
| `stream_seq`           | Order records within an execution.                                                                                   |
| `session_execution_id` | Correlate records with an execution; null for events before an execution exists.                                     |
| `turn_id`              | Correlate records with a turn when one applies.                                                                      |
| `session_message_id`   | Correlate inbox events and native user echoes so a message can render once.                                          |

Use `kind` and `record_type` to narrow platform records. For native records, narrow `kind` first, then `payload.type` (Claude and historical Codex) or `payload.method` (current Codex). Native payloads can have their own `kind` field, such as `"push"` in a Claude Git notification; it is event data, not the envelope's record variant. Claude rate limits are the exception: `record_type` is `rate_limit`, while `payload.type` is `rate_limit_event`.

The field specifications below come from the SDK schema. **Required** means the field must be present; `null` in its type means its value can be null. Expand nested fields to inspect their properties and variants. Required fields within a variant apply when that variant is used. Examples show one possible payload; optional native fields may be absent.

Both SDKs expose `SessionRecord` and `StreamFrame`:

```python
from ellipsis.models import SessionRecord
from ellipsis.frames import StreamFrame
```

```typescript
import type { SessionRecord, StreamFrame } from '@ellipsis-dev/sdk';
```

## Platform

These records use `kind: "platform"`, `source: "lifecycle"`, and `record_format: "ellipsis_lifecycle@1"`. Events describe individual changes; not every session produces every type.

<a id="session_scheduled"></a>

### session_scheduled

The session was created and queued for execution.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_scheduled",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": null,
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 1,
  "stream_seq": 0,
  "payload": {
    "source": "api",
    "config_name": null,
    "config_commit_sha": null
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "session_scheduled". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.source` | `string` | Required |  |
| `payload.config_commit_sha` | `string \| null` | Optional |  |
| `payload.config_name` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="message_received"></a>

### message_received

A prompt, follow-up, or event-generated message entered the inbox; `closes_session` marks a final message.

The opening prompt can carry its initial `turn_id` before `message_delivered`
arrives. Use that identity to reconcile the session's opening prompt without
duplicating it. Follow-ups remain unassigned until delivery; receipt alone does
not mean the agent has consumed a message.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "message_received",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": null,
  "turn_id": null,
  "session_message_id": "message_example",
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "message_id": "message_example",
    "body": "Run the tests and report failures.",
    "author": "priya-shah",
    "sender_attribution_type": "github_user",
    "sender_attribution_id": "12345",
    "closes_session": false
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "message_received". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.author` | `string \| null` | Optional |  |
| `payload.body` | `string` | Required |  |
| `payload.closes_session` | `boolean` | Optional |  |
| `payload.message_id` | `string` | Required |  |
| `payload.sender_attribution_id` | `string \| null` | Optional |  |
| `payload.sender_attribution_type` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="session_starting"></a>

### session_starting

An execution is starting after its initial checks passed; `wake_index` distinguishes a fresh start from a later wake.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_starting",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "attempt": 0,
    "wake_index": 0
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "session_starting". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.attempt` | `integer` | Required |  |
| `payload.wake_index` | `integer` | Required |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="session_cancelled"></a>

### session_cancelled

An initial check cancelled execution before a sandbox was provisioned, with a reason you can display.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_cancelled",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": null,
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "reason": "The session budget has been exhausted."
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "session_cancelled". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.reason` | `string` | Required |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="sandbox_starting"></a>

### sandbox_starting

Sandbox preparation began for the listed repositories.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "sandbox_starting",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "repositories": ["your-org/api-repo"]
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "sandbox_starting". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.repositories` | `array<string>` | Required |  |
| `payload.repositories.[]` | `string` |  |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="sandbox_phase"></a>

### sandbox_phase

A sandbox preparation phase started, completed, or failed, with optional timing and details.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "sandbox_phase",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "phase": "setup",
    "status": "completed",
    "step": "build_base",
    "duration_ms": 2400,
    "detail": null
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "sandbox_phase". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.detail` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.duration_ms` | `integer \| null` | Optional |  |
| `payload.phase` | `string` | Required |  |
| `payload.status` | `string` | Required |  |
| `payload.step` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="sandbox_output"></a>

### sandbox_output

A chunk of stdout or stderr arrived from sandbox preparation or lifecycle scripts.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "sandbox_output",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "phase": "clone",
    "step": "your-org/api-repo",
    "stream": "stdout",
    "chunk": 0,
    "lines": ["Cloning into 'api-repo'..."]
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "sandbox_output". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.chunk` | `integer` | Required |  |
| `payload.lines` | `array<string>` | Required |  |
| `payload.lines.[]` | `string` |  |  |
| `payload.phase` | `string` | Required |  |
| `payload.step` | `string \| null` | Optional |  |
| `payload.stream` | `string` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="sandbox_ready"></a>

### sandbox_ready

The sandbox is ready to launch the harness, with cache and preparation timing information.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "sandbox_ready",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "repositories": ["your-org/api-repo"],
    "cache_tier": "exact",
    "phase_timings": {
      "clone": 2.4
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "sandbox_ready". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.cache_tier` | `string \| null` | Optional |  |
| `payload.phase_timings` | `object` | Optional | Additional properties are allowed. |
| `payload.phase_timings.[key]` | `number` |  |  |
| `payload.repositories` | `array<string>` | Required |  |
| `payload.repositories.[]` | `string` |  |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="session_resumed"></a>

### session_resumed

A later execution successfully restored the existing native conversation.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_resumed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "wake_index": 1
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "session_resumed". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.wake_index` | `integer` | Required |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="turn_started"></a>

### turn_started

A platform turn began.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "turn_started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "turn_id": "turn_example",
    "turn_index": 0
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "turn_started". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.turn_id` | `string` | Required |  |
| `payload.turn_index` | `integer` | Required |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="message_delivered"></a>

### message_delivered

An inbox message was delivered to the identified turn.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "message_delivered",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": "message_example",
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "message_id": "message_example",
    "turn_id": "turn_example"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "message_delivered". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.message_id` | `string` | Required |  |
| `payload.turn_id` | `string` | Required |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="turn_completed"></a>

### turn_completed

A platform turn completed successfully.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "turn_completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "turn_id": "turn_example",
    "turn_index": 0,
    "duration_ms": 4200
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "turn_completed". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.duration_ms` | `integer \| null` | Optional |  |
| `payload.turn_id` | `string` | Required |  |
| `payload.turn_index` | `integer` | Required |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="turn_failed"></a>

### turn_failed

A platform turn ended unsuccessfully; this event alone does not mean its messages will be requeued.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "turn_failed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "turn_id": "turn_example",
    "turn_index": 0
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "turn_failed". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.turn_id` | `string` | Required |  |
| `payload.turn_index` | `integer` | Required |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="message_requeued"></a>

### message_requeued

A previously delivered message returned to the inbox for redelivery during failure recovery.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "message_requeued",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": "message_example",
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "message_id": "message_example",
    "turn_id": "turn_example"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "message_requeued". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.message_id` | `string` | Required |  |
| `payload.turn_id` | `string` | Required |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="session_retrying"></a>

### session_retrying

Execution will retry after a temporary infrastructure failure before the agent acted.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_retrying",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "reason": "The sandbox could not be started. Retrying.",
    "attempt": 1
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "session_retrying". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.attempt` | `integer` | Required |  |
| `payload.reason` | `string` | Required |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="outbox_collected"></a>

### outbox_collected

A code-review session collected its review output, including raw files, parsed findings, and parsing errors.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "outbox_collected",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "raw": {},
    "findings": [],
    "parse_errors": [],
    "parser_version": "1"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "outbox_collected". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.findings` | `array<object>` | Optional |  |
| `payload.findings.[]` | `object` |  | Additional properties are allowed. |
| `payload.parse_errors` | `array<object>` | Optional |  |
| `payload.parse_errors.[]` | `object` |  | Additional properties are allowed. |
| `payload.parser_version` | `string` | Required |  |
| `payload.raw` | `object` | Optional | Additional properties are allowed. |
| `payload.raw.[key]` | `string` |  |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="session_idle"></a>

### session_idle

The execution loop ended and the persistent conversation is parked until another message arrives.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_idle",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {},
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "session_idle". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="session_closed"></a>

### session_closed

The conversation closed permanently after its final turn or the end of a one-shot session.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_closed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {},
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "platform". |
| `source` | `string` | Required | Must be "lifecycle". |
| `record_format` | `string` | Required | Must be "ellipsis_lifecycle@1". |
| `record_type` | `string` | Required | Must be "session_closed". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

`sandbox_phase.status` currently uses `started`, `completed`, and `failed`. Treat phase names, steps, and statuses as open strings. A sandbox can emit many phase and output records. During environment preparation, `step: "build_base"` distinguishes the reusable base from the full source checkout; `step: "after_checkout"` identifies source preparation. Session startup hooks report `step: "before_start"`. A reused snapshot skips its build steps, while `before_start` runs before each session start or resume.

`session_idle` marks a parked conversation, not every pause between turns. Session success, failure, and stop status arrive through the [`session` frame](#session); there are no separate `session_completed`, `session_failed`, or `session_stopped` platform records.

## Claude Code

Current Claude records use `kind: "claude_code"`, `source: "claude_code"`, and `record_format: "claude_jsonl@1"`. A native `result` ends a harness turn, not necessarily the whole session.

<a id="claude-system"></a>

### system

Reports harness metadata, including initialization, status, compaction, hooks, and background-task activity through `subtype`.

**Example JSON**

```json
{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "system",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "system",
    "subtype": "init",
    "model": "claude-sonnet-5",
    "tools": ["Bash", "Read"],
    "cwd": "/workspace",
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_code". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "system". |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.subtype` | `string` | Required |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-vcs-state-changed"></a>

### system

Reports a Git state change through `subtype: vcs_state_changed`; `payload.kind` identifies the operation, such as a push.

This notification is part of the current turn's activity. It does not complete or fail the turn. Its native `kind`, `cwd`, and other fields are preserved in `payload`; `record_type` remains `system`.

**Example JSON**

```json
{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "system",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "system",
    "subtype": "vcs_state_changed",
    "kind": "push",
    "cwd": "/workspace",
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_code". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "system". |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.subtype` | `string` | Required |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-user"></a>

### user

Carries a user-message echo or tool results supplied back to Claude; this example is a tool result.

**Example JSON**

```json
{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "user",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "user",
    "message": {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "tool_example",
          "content": "12 passed",
          "is_error": false
        }
      ]
    },
    "parent_tool_use_id": null,
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_code". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "user". |
| `payload.isReplay` | `boolean \| null` | Optional |  |
| `payload.message` | `object` | Required | Additional properties are allowed. |
| `payload.message.content` | `string \| array<object>` | Required | Matches at least one variant below. |
| `payload.message.content.variant 1` | `string` |  |  |
| `payload.message.content.variant 2` | `array<object>` |  |  |
| `payload.message.content.variant 2.[]` | `object` |  | Matches exactly one variant below. |
| `payload.message.content.variant 2.[].type = "text"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "text".type` | `string` | Required | Must be "text". |
| `payload.message.content.variant 2.[].type = "text".text` | `string` | Required |  |
| `payload.message.content.variant 2.[].type = "thinking"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "thinking".type` | `string` | Required | Must be "thinking". |
| `payload.message.content.variant 2.[].type = "thinking".signature` | `string` | Required |  |
| `payload.message.content.variant 2.[].type = "thinking".thinking` | `string` | Required |  |
| `payload.message.content.variant 2.[].type = "tool_use"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "tool_use".type` | `string` | Required | Must be "tool_use". |
| `payload.message.content.variant 2.[].type = "tool_use".id` | `string` | Required |  |
| `payload.message.content.variant 2.[].type = "tool_use".input` | `object` | Optional | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "tool_use".name` | `string` | Required |  |
| `payload.message.content.variant 2.[].type = "tool_result"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "tool_result".type` | `string` | Required | Must be "tool_result". |
| `payload.message.content.variant 2.[].type = "tool_result".content` | `string \| array<object> \| null` | Optional | Matches at least one variant below. |
| `payload.message.content.variant 2.[].type = "tool_result".content.variant 1` | `string` |  |  |
| `payload.message.content.variant 2.[].type = "tool_result".content.variant 2` | `array<object>` |  |  |
| `payload.message.content.variant 2.[].type = "tool_result".content.variant 2.[]` | `object` |  | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "tool_result".is_error` | `boolean \| null` | Optional |  |
| `payload.message.content.variant 2.[].type = "tool_result".tool_use_id` | `string` | Required |  |
| `payload.message.content.variant 2.[].type = "server_tool_use"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "server_tool_use".type` | `string` | Required | Must be "server_tool_use". |
| `payload.message.content.variant 2.[].type = "server_tool_use".id` | `string` | Required |  |
| `payload.message.content.variant 2.[].type = "server_tool_use".input` | `object` | Optional | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "server_tool_use".name` | `string` | Required |  |
| `payload.message.content.variant 2.[].type = "server_tool_result"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "server_tool_result".type` | `string` | Required | Must be "server_tool_result". |
| `payload.message.content.variant 2.[].type = "server_tool_result".content` | `object` | Optional | Additional properties are allowed. |
| `payload.message.content.variant 2.[].type = "server_tool_result".tool_use_id` | `string` | Required |  |
| `payload.message.role` | `string` | Required | Must be "user". |
| `payload.parent_tool_use_id` | `string \| null` | Optional |  |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-assistant"></a>

### assistant

Carries completed assistant content, including text, thinking, and tool calls.

**Example JSON**

```json
{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "assistant",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "assistant",
    "message": {
      "type": "message",
      "role": "assistant",
      "id": "message_native",
      "model": "claude-sonnet-5",
      "content": [
        {
          "type": "text",
          "text": "I will run the tests."
        },
        {
          "type": "tool_use",
          "id": "tool_example",
          "name": "Bash",
          "input": {
            "command": "pytest -q"
          }
        }
      ],
      "usage": {
        "input_tokens": 1200,
        "output_tokens": 80,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      },
      "stop_reason": "tool_use"
    },
    "parent_tool_use_id": null,
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": ["Bash"],
  "tokens_info": {
    "input_tokens": 1200,
    "output_tokens": 80,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "num_turns": 0,
    "cost_usd": 0
  },
  "cost": null,
  "duration": null,
  "model": "claude-sonnet-5",
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_code". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "assistant". |
| `payload.error` | `string \| null` | Optional |  |
| `payload.message` | `object` | Required | Additional properties are allowed. |
| `payload.message.type` | `string` | Required | Must be "message". |
| `payload.message.content` | `array<object>` | Required |  |
| `payload.message.content.[]` | `object` |  | Matches exactly one variant below. |
| `payload.message.content.[].type = "text"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.[].type = "text".type` | `string` | Required | Must be "text". |
| `payload.message.content.[].type = "text".text` | `string` | Required |  |
| `payload.message.content.[].type = "thinking"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.[].type = "thinking".type` | `string` | Required | Must be "thinking". |
| `payload.message.content.[].type = "thinking".signature` | `string` | Required |  |
| `payload.message.content.[].type = "thinking".thinking` | `string` | Required |  |
| `payload.message.content.[].type = "tool_use"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.[].type = "tool_use".type` | `string` | Required | Must be "tool_use". |
| `payload.message.content.[].type = "tool_use".id` | `string` | Required |  |
| `payload.message.content.[].type = "tool_use".input` | `object` | Optional | Additional properties are allowed. |
| `payload.message.content.[].type = "tool_use".name` | `string` | Required |  |
| `payload.message.content.[].type = "tool_result"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.[].type = "tool_result".type` | `string` | Required | Must be "tool_result". |
| `payload.message.content.[].type = "tool_result".content` | `string \| array<object> \| null` | Optional | Matches at least one variant below. |
| `payload.message.content.[].type = "tool_result".content.variant 1` | `string` |  |  |
| `payload.message.content.[].type = "tool_result".content.variant 2` | `array<object>` |  |  |
| `payload.message.content.[].type = "tool_result".content.variant 2.[]` | `object` |  | Additional properties are allowed. |
| `payload.message.content.[].type = "tool_result".is_error` | `boolean \| null` | Optional |  |
| `payload.message.content.[].type = "tool_result".tool_use_id` | `string` | Required |  |
| `payload.message.content.[].type = "server_tool_use"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.[].type = "server_tool_use".type` | `string` | Required | Must be "server_tool_use". |
| `payload.message.content.[].type = "server_tool_use".id` | `string` | Required |  |
| `payload.message.content.[].type = "server_tool_use".input` | `object` | Optional | Additional properties are allowed. |
| `payload.message.content.[].type = "server_tool_use".name` | `string` | Required |  |
| `payload.message.content.[].type = "server_tool_result"` | `object` |  | Additional properties are allowed. |
| `payload.message.content.[].type = "server_tool_result".type` | `string` | Required | Must be "server_tool_result". |
| `payload.message.content.[].type = "server_tool_result".content` | `object` | Optional | Additional properties are allowed. |
| `payload.message.content.[].type = "server_tool_result".tool_use_id` | `string` | Required |  |
| `payload.message.id` | `string \| null` | Optional |  |
| `payload.message.model` | `string` | Required |  |
| `payload.message.role` | `string` | Required | Must be "assistant". |
| `payload.message.stop_reason` | `string \| null` | Optional |  |
| `payload.message.stop_sequence` | `string \| null` | Optional |  |
| `payload.message.usage` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.message.usage.cache_creation` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.message.usage.cache_creation_input_tokens` | `integer` | Optional |  |
| `payload.message.usage.cache_read_input_tokens` | `integer` | Optional |  |
| `payload.message.usage.input_tokens` | `integer` | Optional |  |
| `payload.message.usage.output_tokens` | `integer` | Optional |  |
| `payload.parent_tool_use_id` | `string \| null` | Optional |  |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-rate_limit"></a>

### rate_limit

Reports rate-limit status and reset information; the native payload names the event `rate_limit_event`.

**Example JSON**

```json
{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "rate_limit",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "rate_limit_event",
    "rate_limit_info": {
      "status": "allowed",
      "rateLimitType": "five_hour",
      "utilization": 0.25,
      "resetsAt": 1789066800
    },
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_code". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "rate_limit_event". |
| `payload.rate_limit_info` | `object` | Required | Additional properties are allowed. |
| `payload.rate_limit_info.overageDisabledReason` | `string \| null` | Optional |  |
| `payload.rate_limit_info.overageResetsAt` | `integer \| null` | Optional |  |
| `payload.rate_limit_info.overageStatus` | `string \| null` | Optional |  |
| `payload.rate_limit_info.rateLimitType` | `string \| null` | Optional |  |
| `payload.rate_limit_info.resetsAt` | `integer \| null` | Optional |  |
| `payload.rate_limit_info.status` | `string` | Required |  |
| `payload.rate_limit_info.utilization` | `number \| null` | Optional |  |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-result"></a>

### result

Reports a harness turn outcome with its output, elapsed time, usage, and reported cost.

**Example JSON**

```json
{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "result",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "result",
    "subtype": "success",
    "is_error": false,
    "num_turns": 1,
    "duration_ms": 4200,
    "duration_api_ms": 3100,
    "result": "All 12 tests passed.",
    "total_cost_usd": 0.01,
    "usage": {
      "input_tokens": 1200,
      "output_tokens": 80,
      "cache_read_input_tokens": 0,
      "cache_creation_input_tokens": 0
    },
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": {
    "input_tokens": 1200,
    "output_tokens": 80,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "num_turns": 0,
    "cost_usd": 0
  },
  "cost": 1000,
  "duration": 4200,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_code". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "result". |
| `payload.duration_api_ms` | `integer` | Required |  |
| `payload.duration_ms` | `integer` | Required |  |
| `payload.errors` | `array<string> \| null` | Optional |  |
| `payload.errors.[]` | `string` |  |  |
| `payload.is_error` | `boolean` | Required |  |
| `payload.modelUsage` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.num_turns` | `integer` | Required |  |
| `payload.result` | `string \| null` | Optional |  |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.stop_reason` | `string \| null` | Optional |  |
| `payload.structured_output` | `any JSON value` | Optional |  |
| `payload.subtype` | `string` | Required |  |
| `payload.total_cost_usd` | `number \| null` | Optional |  |
| `payload.usage` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.usage.cache_creation` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.usage.cache_creation_input_tokens` | `integer` | Optional |  |
| `payload.usage.cache_read_input_tokens` | `integer` | Optional |  |
| `payload.usage.input_tokens` | `integer` | Optional |  |
| `payload.usage.output_tokens` | `integer` | Optional |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-conversation_reset"></a>

### conversation_reset

Reports that Claude switched to a new native conversation identifier.

**Example JSON**

```json
{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "conversation_reset",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "conversation_reset",
    "new_conversation_id": "33333333-3333-4333-8333-333333333333",
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_code". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "conversation_reset". |
| `payload.new_conversation_id` | `string` | Required |  |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

`system.subtype` is an open string. Examples include `init`, `compact_boundary`, `status`, `vcs_state_changed`, `task_started`, `task_progress`, `task_notification`, `task_updated`, `hook_started`, and `hook_response`; these remain `system` records, not separate `record_type` values.

A `result.subtype` distinguishes `success` from outcomes such as `error_during_execution`, `error_max_turns`, `error_max_structured_output_retries`, and historical `error_max_budget_usd` results.

Content blocks such as `text`, `thinking`, `tool_use`, and `tool_result` are nested payloads, not separate session events. Native `stream_event` messages supply live [`delta` frames](#delta); their original per-token messages are not retained as records.

## Codex

Current Codex records use `source: "codex"` and `record_format: "codex_app_server@1"`. The modeled notifications use `kind: "codex_app_server"`; additional native notifications use `kind: "unknown"` while retaining their method and payload.

<a id="codex-remoteControl-status-changed"></a>

### remoteControl/status/changed

Reports the native app-server remote-control status as an unknown record.

**Example JSON**

```json
{
  "kind": "unknown",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "remoteControl/status/changed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "remoteControl/status/changed",
    "params": {
      "status": "disabled",
      "serverName": "sandbox",
      "installationId": "installation_example",
      "environmentId": null
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "unknown". |
| `source` | `string` | Required | Original producer. Unknown producers remain readable as unknown records. |
| `record_format` | `string` | Required | Original versioned payload format. |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-thread-started"></a>

### thread/started

Announces the native thread and its metadata.

**Example JSON**

```json
{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "thread/started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "thread/started",
    "params": {
      "thread": {
        "id": "thread_example",
        "cliVersion": "0.145.0",
        "modelProvider": "openai",
        "cwd": "/workspace/api-repo",
        "turns": []
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex_app_server". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_app_server@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.params` | `object` | Required | Additional properties are allowed. |
| `payload.params.thread` | `object` | Required | Additional properties are allowed. |
| `payload.params.thread.cliVersion` | `string` | Required |  |
| `payload.params.thread.cwd` | `string` | Required |  |
| `payload.params.thread.id` | `string` | Required |  |
| `payload.params.thread.modelProvider` | `string` | Required |  |
| `payload.params.thread.turns` | `array<object>` | Required |  |
| `payload.params.thread.turns.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].error` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.thread.turns.[].error.additionalDetails` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].error.codexErrorInfo` | `string \| object \| null` | Optional | Matches at least one variant below. |
| `payload.params.thread.turns.[].error.codexErrorInfo.variant 1` | `string` |  |  |
| `payload.params.thread.turns.[].error.codexErrorInfo.variant 2` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].error.message` | `string` | Required |  |
| `payload.params.thread.turns.[].id` | `string` | Required |  |
| `payload.params.thread.turns.[].items` | `array<object>` | Required |  |
| `payload.params.thread.turns.[].items.[]` | `object` |  | Matches exactly one variant below. |
| `payload.params.thread.turns.[].items.[].type = "userMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "userMessage".type` | `string` | Required | Must be "userMessage". |
| `payload.params.thread.turns.[].items.[].type = "userMessage".clientId` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content` | `array<object>` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[]` | `object` |  | Matches exactly one variant below. |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[].type = "text"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[].type = "text".type` | `string` | Required | Must be "text". |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[].type = "text".text` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[].type = "text".text_elements` | `array<object>` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[].type = "text".text_elements.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[].type = "localImage"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[].type = "localImage".type` | `string` | Required | Must be "localImage". |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[].type = "localImage".detail` | `string \| null` | Optional | Allowed values: "auto", "low", "high", "original". |
| `payload.params.thread.turns.[].items.[].type = "userMessage".content.[].type = "localImage".path` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "userMessage".id` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "agentMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "agentMessage".type` | `string` | Required | Must be "agentMessage". |
| `payload.params.thread.turns.[].items.[].type = "agentMessage".id` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "agentMessage".phase` | `string \| null` | Optional | Allowed values: "commentary", "final_answer". |
| `payload.params.thread.turns.[].items.[].type = "agentMessage".text` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "reasoning"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "reasoning".type` | `string` | Required | Must be "reasoning". |
| `payload.params.thread.turns.[].items.[].type = "reasoning".content` | `array<string>` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "reasoning".content.[]` | `string` |  |  |
| `payload.params.thread.turns.[].items.[].type = "reasoning".id` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "reasoning".summary` | `array<string>` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "reasoning".summary.[]` | `string` |  |  |
| `payload.params.thread.turns.[].items.[].type = "plan"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "plan".type` | `string` | Required | Must be "plan". |
| `payload.params.thread.turns.[].items.[].type = "plan".id` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "plan".text` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "commandExecution"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".type` | `string` | Required | Must be "commandExecution". |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".aggregatedOutput` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".command` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".commandActions` | `array<object>` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".commandActions.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".cwd` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".durationMs` | `integer \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".exitCode` | `integer \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".id` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".processId` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "commandExecution".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.thread.turns.[].items.[].type = "fileChange"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "fileChange".type` | `string` | Required | Must be "fileChange". |
| `payload.params.thread.turns.[].items.[].type = "fileChange".changes` | `array<object>` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "fileChange".changes.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "fileChange".changes.[].kind` | `object` | Required | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "fileChange".changes.[].diff` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "fileChange".changes.[].path` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "fileChange".id` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "fileChange".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.thread.turns.[].items.[].type = "webSearch"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "webSearch".type` | `string` | Required | Must be "webSearch". |
| `payload.params.thread.turns.[].items.[].type = "webSearch".action` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "webSearch".id` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "webSearch".query` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".type` | `string` | Required | Must be "mcpToolCall". |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".appContext` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".appContext.actionName` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".appContext.appName` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".appContext.connectorId` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".appContext.linkId` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".appContext.resourceUri` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".arguments` | `any JSON value` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".durationMs` | `integer \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".error` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".error.message` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".id` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".mcpAppResourceUri` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".pluginId` | `string \| null` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".result` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".result._meta` | `any JSON value` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".result.content` | `array<any JSON value>` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".result.content.[]` | `any JSON value` |  |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".result.structuredContent` | `any JSON value` | Optional |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".server` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed". |
| `payload.params.thread.turns.[].items.[].type = "mcpToolCall".tool` | `string` | Required |  |
| `payload.params.thread.turns.[].items.[].type = "contextCompaction"` | `object` |  | Additional properties are allowed. |
| `payload.params.thread.turns.[].items.[].type = "contextCompaction".type` | `string` | Required | Must be "contextCompaction". |
| `payload.params.thread.turns.[].items.[].type = "contextCompaction".id` | `string` | Required |  |
| `payload.params.thread.turns.[].status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "interrupted". |
| `payload.method` | `string` | Required | Must be "thread/started". |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-thread-status-changed"></a>

### thread/status/changed

Reports native thread activity, such as becoming active or idle, as an unknown record.

**Example JSON**

```json
{
  "kind": "unknown",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "thread/status/changed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "thread/status/changed",
    "params": {
      "threadId": "thread_example",
      "status": {
        "type": "idle"
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "unknown". |
| `source` | `string` | Required | Original producer. Unknown producers remain readable as unknown records. |
| `record_format` | `string` | Required | Original versioned payload format. |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-turn-started"></a>

### turn/started

Announces the start of a native turn.

**Example JSON**

```json
{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "turn/started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "turn/started",
    "params": {
      "threadId": "thread_example",
      "turn": {
        "id": "native_turn_example",
        "status": "inProgress",
        "items": [],
        "error": null
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex_app_server". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_app_server@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.params` | `object` | Required | Additional properties are allowed. |
| `payload.params.threadId` | `string` | Required |  |
| `payload.params.turn` | `object` | Required | Additional properties are allowed. |
| `payload.params.turn.error` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.error.additionalDetails` | `string \| null` | Optional |  |
| `payload.params.turn.error.codexErrorInfo` | `string \| object \| null` | Optional | Matches at least one variant below. |
| `payload.params.turn.error.codexErrorInfo.variant 1` | `string` |  |  |
| `payload.params.turn.error.codexErrorInfo.variant 2` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.error.message` | `string` | Required |  |
| `payload.params.turn.id` | `string` | Required |  |
| `payload.params.turn.items` | `array<object>` | Required |  |
| `payload.params.turn.items.[]` | `object` |  | Matches exactly one variant below. |
| `payload.params.turn.items.[].type = "userMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "userMessage".type` | `string` | Required | Must be "userMessage". |
| `payload.params.turn.items.[].type = "userMessage".clientId` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "userMessage".content` | `array<object>` | Required |  |
| `payload.params.turn.items.[].type = "userMessage".content.[]` | `object` |  | Matches exactly one variant below. |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text".type` | `string` | Required | Must be "text". |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text".text` | `string` | Required |  |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text".text_elements` | `array<object>` | Optional |  |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text".text_elements.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "localImage"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "localImage".type` | `string` | Required | Must be "localImage". |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "localImage".detail` | `string \| null` | Optional | Allowed values: "auto", "low", "high", "original". |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "localImage".path` | `string` | Required |  |
| `payload.params.turn.items.[].type = "userMessage".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "agentMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "agentMessage".type` | `string` | Required | Must be "agentMessage". |
| `payload.params.turn.items.[].type = "agentMessage".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "agentMessage".phase` | `string \| null` | Optional | Allowed values: "commentary", "final_answer". |
| `payload.params.turn.items.[].type = "agentMessage".text` | `string` | Required |  |
| `payload.params.turn.items.[].type = "reasoning"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "reasoning".type` | `string` | Required | Must be "reasoning". |
| `payload.params.turn.items.[].type = "reasoning".content` | `array<string>` | Optional |  |
| `payload.params.turn.items.[].type = "reasoning".content.[]` | `string` |  |  |
| `payload.params.turn.items.[].type = "reasoning".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "reasoning".summary` | `array<string>` | Optional |  |
| `payload.params.turn.items.[].type = "reasoning".summary.[]` | `string` |  |  |
| `payload.params.turn.items.[].type = "plan"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "plan".type` | `string` | Required | Must be "plan". |
| `payload.params.turn.items.[].type = "plan".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "plan".text` | `string` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "commandExecution".type` | `string` | Required | Must be "commandExecution". |
| `payload.params.turn.items.[].type = "commandExecution".aggregatedOutput` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "commandExecution".command` | `string` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution".commandActions` | `array<object>` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution".commandActions.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "commandExecution".cwd` | `string` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution".durationMs` | `integer \| null` | Optional |  |
| `payload.params.turn.items.[].type = "commandExecution".exitCode` | `integer \| null` | Optional |  |
| `payload.params.turn.items.[].type = "commandExecution".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution".processId` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "commandExecution".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.turn.items.[].type = "fileChange"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "fileChange".type` | `string` | Required | Must be "fileChange". |
| `payload.params.turn.items.[].type = "fileChange".changes` | `array<object>` | Required |  |
| `payload.params.turn.items.[].type = "fileChange".changes.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "fileChange".changes.[].kind` | `object` | Required | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "fileChange".changes.[].diff` | `string` | Required |  |
| `payload.params.turn.items.[].type = "fileChange".changes.[].path` | `string` | Required |  |
| `payload.params.turn.items.[].type = "fileChange".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "fileChange".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.turn.items.[].type = "webSearch"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "webSearch".type` | `string` | Required | Must be "webSearch". |
| `payload.params.turn.items.[].type = "webSearch".action` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "webSearch".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "webSearch".query` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "mcpToolCall".type` | `string` | Required | Must be "mcpToolCall". |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.actionName` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.appName` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.connectorId` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.linkId` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.resourceUri` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".arguments` | `any JSON value` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".durationMs` | `integer \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".error` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "mcpToolCall".error.message` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".mcpAppResourceUri` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".pluginId` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".result` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "mcpToolCall".result._meta` | `any JSON value` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".result.content` | `array<any JSON value>` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".result.content.[]` | `any JSON value` |  |  |
| `payload.params.turn.items.[].type = "mcpToolCall".result.structuredContent` | `any JSON value` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".server` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed". |
| `payload.params.turn.items.[].type = "mcpToolCall".tool` | `string` | Required |  |
| `payload.params.turn.items.[].type = "contextCompaction"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "contextCompaction".type` | `string` | Required | Must be "contextCompaction". |
| `payload.params.turn.items.[].type = "contextCompaction".id` | `string` | Required |  |
| `payload.params.turn.status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "interrupted". |
| `payload.method` | `string` | Required | Must be "turn/started". |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-item-started"></a>

### item/started

Announces the start of a message, command, file change, or another conversation item.

**Example JSON**

```json
{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "item/started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "item/started",
    "params": {
      "threadId": "thread_example",
      "turnId": "native_turn_example",
      "item": {
        "type": "commandExecution",
        "id": "command_example",
        "command": "pytest -q",
        "cwd": "/workspace/api-repo",
        "commandActions": [],
        "status": "inProgress"
      }
    }
  },
  "tools": ["Bash"],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex_app_server". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_app_server@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.params` | `object` | Required | Additional properties are allowed. |
| `payload.params.item` | `object` | Required | Matches exactly one variant below. |
| `payload.params.item.type = "userMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "userMessage".type` | `string` | Required | Must be "userMessage". |
| `payload.params.item.type = "userMessage".clientId` | `string \| null` | Optional |  |
| `payload.params.item.type = "userMessage".content` | `array<object>` | Required |  |
| `payload.params.item.type = "userMessage".content.[]` | `object` |  | Matches exactly one variant below. |
| `payload.params.item.type = "userMessage".content.[].type = "text"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "userMessage".content.[].type = "text".type` | `string` | Required | Must be "text". |
| `payload.params.item.type = "userMessage".content.[].type = "text".text` | `string` | Required |  |
| `payload.params.item.type = "userMessage".content.[].type = "text".text_elements` | `array<object>` | Optional |  |
| `payload.params.item.type = "userMessage".content.[].type = "text".text_elements.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "userMessage".content.[].type = "localImage"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "userMessage".content.[].type = "localImage".type` | `string` | Required | Must be "localImage". |
| `payload.params.item.type = "userMessage".content.[].type = "localImage".detail` | `string \| null` | Optional | Allowed values: "auto", "low", "high", "original". |
| `payload.params.item.type = "userMessage".content.[].type = "localImage".path` | `string` | Required |  |
| `payload.params.item.type = "userMessage".id` | `string` | Required |  |
| `payload.params.item.type = "agentMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "agentMessage".type` | `string` | Required | Must be "agentMessage". |
| `payload.params.item.type = "agentMessage".id` | `string` | Required |  |
| `payload.params.item.type = "agentMessage".phase` | `string \| null` | Optional | Allowed values: "commentary", "final_answer". |
| `payload.params.item.type = "agentMessage".text` | `string` | Required |  |
| `payload.params.item.type = "reasoning"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "reasoning".type` | `string` | Required | Must be "reasoning". |
| `payload.params.item.type = "reasoning".content` | `array<string>` | Optional |  |
| `payload.params.item.type = "reasoning".content.[]` | `string` |  |  |
| `payload.params.item.type = "reasoning".id` | `string` | Required |  |
| `payload.params.item.type = "reasoning".summary` | `array<string>` | Optional |  |
| `payload.params.item.type = "reasoning".summary.[]` | `string` |  |  |
| `payload.params.item.type = "plan"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "plan".type` | `string` | Required | Must be "plan". |
| `payload.params.item.type = "plan".id` | `string` | Required |  |
| `payload.params.item.type = "plan".text` | `string` | Required |  |
| `payload.params.item.type = "commandExecution"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "commandExecution".type` | `string` | Required | Must be "commandExecution". |
| `payload.params.item.type = "commandExecution".aggregatedOutput` | `string \| null` | Optional |  |
| `payload.params.item.type = "commandExecution".command` | `string` | Required |  |
| `payload.params.item.type = "commandExecution".commandActions` | `array<object>` | Required |  |
| `payload.params.item.type = "commandExecution".commandActions.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "commandExecution".cwd` | `string` | Required |  |
| `payload.params.item.type = "commandExecution".durationMs` | `integer \| null` | Optional |  |
| `payload.params.item.type = "commandExecution".exitCode` | `integer \| null` | Optional |  |
| `payload.params.item.type = "commandExecution".id` | `string` | Required |  |
| `payload.params.item.type = "commandExecution".processId` | `string \| null` | Optional |  |
| `payload.params.item.type = "commandExecution".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.item.type = "fileChange"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "fileChange".type` | `string` | Required | Must be "fileChange". |
| `payload.params.item.type = "fileChange".changes` | `array<object>` | Required |  |
| `payload.params.item.type = "fileChange".changes.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "fileChange".changes.[].kind` | `object` | Required | Additional properties are allowed. |
| `payload.params.item.type = "fileChange".changes.[].diff` | `string` | Required |  |
| `payload.params.item.type = "fileChange".changes.[].path` | `string` | Required |  |
| `payload.params.item.type = "fileChange".id` | `string` | Required |  |
| `payload.params.item.type = "fileChange".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.item.type = "webSearch"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "webSearch".type` | `string` | Required | Must be "webSearch". |
| `payload.params.item.type = "webSearch".action` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.item.type = "webSearch".id` | `string` | Required |  |
| `payload.params.item.type = "webSearch".query` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "mcpToolCall".type` | `string` | Required | Must be "mcpToolCall". |
| `payload.params.item.type = "mcpToolCall".appContext` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.item.type = "mcpToolCall".appContext.actionName` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".appContext.appName` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".appContext.connectorId` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall".appContext.linkId` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".appContext.resourceUri` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".arguments` | `any JSON value` | Required |  |
| `payload.params.item.type = "mcpToolCall".durationMs` | `integer \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".error` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.item.type = "mcpToolCall".error.message` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall".id` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall".mcpAppResourceUri` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".pluginId` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".result` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.item.type = "mcpToolCall".result._meta` | `any JSON value` | Optional |  |
| `payload.params.item.type = "mcpToolCall".result.content` | `array<any JSON value>` | Required |  |
| `payload.params.item.type = "mcpToolCall".result.content.[]` | `any JSON value` |  |  |
| `payload.params.item.type = "mcpToolCall".result.structuredContent` | `any JSON value` | Optional |  |
| `payload.params.item.type = "mcpToolCall".server` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed". |
| `payload.params.item.type = "mcpToolCall".tool` | `string` | Required |  |
| `payload.params.item.type = "contextCompaction"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "contextCompaction".type` | `string` | Required | Must be "contextCompaction". |
| `payload.params.item.type = "contextCompaction".id` | `string` | Required |  |
| `payload.params.threadId` | `string` | Required |  |
| `payload.params.turnId` | `string` | Required |  |
| `payload.method` | `string` | Required | Must be "item/started". |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-item-completed"></a>

### item/completed

Supplies a completed item, including its content, output, or outcome.

**Example JSON**

```json
{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "item/completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "item/completed",
    "params": {
      "threadId": "thread_example",
      "turnId": "native_turn_example",
      "item": {
        "type": "commandExecution",
        "id": "command_example",
        "command": "pytest -q",
        "cwd": "/workspace/api-repo",
        "commandActions": [],
        "status": "completed",
        "aggregatedOutput": "12 passed",
        "exitCode": 0,
        "durationMs": 4200
      }
    }
  },
  "tools": ["Bash"],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex_app_server". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_app_server@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.params` | `object` | Required | Additional properties are allowed. |
| `payload.params.item` | `object` | Required | Matches exactly one variant below. |
| `payload.params.item.type = "userMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "userMessage".type` | `string` | Required | Must be "userMessage". |
| `payload.params.item.type = "userMessage".clientId` | `string \| null` | Optional |  |
| `payload.params.item.type = "userMessage".content` | `array<object>` | Required |  |
| `payload.params.item.type = "userMessage".content.[]` | `object` |  | Matches exactly one variant below. |
| `payload.params.item.type = "userMessage".content.[].type = "text"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "userMessage".content.[].type = "text".type` | `string` | Required | Must be "text". |
| `payload.params.item.type = "userMessage".content.[].type = "text".text` | `string` | Required |  |
| `payload.params.item.type = "userMessage".content.[].type = "text".text_elements` | `array<object>` | Optional |  |
| `payload.params.item.type = "userMessage".content.[].type = "text".text_elements.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "userMessage".content.[].type = "localImage"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "userMessage".content.[].type = "localImage".type` | `string` | Required | Must be "localImage". |
| `payload.params.item.type = "userMessage".content.[].type = "localImage".detail` | `string \| null` | Optional | Allowed values: "auto", "low", "high", "original". |
| `payload.params.item.type = "userMessage".content.[].type = "localImage".path` | `string` | Required |  |
| `payload.params.item.type = "userMessage".id` | `string` | Required |  |
| `payload.params.item.type = "agentMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "agentMessage".type` | `string` | Required | Must be "agentMessage". |
| `payload.params.item.type = "agentMessage".id` | `string` | Required |  |
| `payload.params.item.type = "agentMessage".phase` | `string \| null` | Optional | Allowed values: "commentary", "final_answer". |
| `payload.params.item.type = "agentMessage".text` | `string` | Required |  |
| `payload.params.item.type = "reasoning"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "reasoning".type` | `string` | Required | Must be "reasoning". |
| `payload.params.item.type = "reasoning".content` | `array<string>` | Optional |  |
| `payload.params.item.type = "reasoning".content.[]` | `string` |  |  |
| `payload.params.item.type = "reasoning".id` | `string` | Required |  |
| `payload.params.item.type = "reasoning".summary` | `array<string>` | Optional |  |
| `payload.params.item.type = "reasoning".summary.[]` | `string` |  |  |
| `payload.params.item.type = "plan"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "plan".type` | `string` | Required | Must be "plan". |
| `payload.params.item.type = "plan".id` | `string` | Required |  |
| `payload.params.item.type = "plan".text` | `string` | Required |  |
| `payload.params.item.type = "commandExecution"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "commandExecution".type` | `string` | Required | Must be "commandExecution". |
| `payload.params.item.type = "commandExecution".aggregatedOutput` | `string \| null` | Optional |  |
| `payload.params.item.type = "commandExecution".command` | `string` | Required |  |
| `payload.params.item.type = "commandExecution".commandActions` | `array<object>` | Required |  |
| `payload.params.item.type = "commandExecution".commandActions.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "commandExecution".cwd` | `string` | Required |  |
| `payload.params.item.type = "commandExecution".durationMs` | `integer \| null` | Optional |  |
| `payload.params.item.type = "commandExecution".exitCode` | `integer \| null` | Optional |  |
| `payload.params.item.type = "commandExecution".id` | `string` | Required |  |
| `payload.params.item.type = "commandExecution".processId` | `string \| null` | Optional |  |
| `payload.params.item.type = "commandExecution".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.item.type = "fileChange"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "fileChange".type` | `string` | Required | Must be "fileChange". |
| `payload.params.item.type = "fileChange".changes` | `array<object>` | Required |  |
| `payload.params.item.type = "fileChange".changes.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "fileChange".changes.[].kind` | `object` | Required | Additional properties are allowed. |
| `payload.params.item.type = "fileChange".changes.[].diff` | `string` | Required |  |
| `payload.params.item.type = "fileChange".changes.[].path` | `string` | Required |  |
| `payload.params.item.type = "fileChange".id` | `string` | Required |  |
| `payload.params.item.type = "fileChange".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.item.type = "webSearch"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "webSearch".type` | `string` | Required | Must be "webSearch". |
| `payload.params.item.type = "webSearch".action` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.item.type = "webSearch".id` | `string` | Required |  |
| `payload.params.item.type = "webSearch".query` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "mcpToolCall".type` | `string` | Required | Must be "mcpToolCall". |
| `payload.params.item.type = "mcpToolCall".appContext` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.item.type = "mcpToolCall".appContext.actionName` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".appContext.appName` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".appContext.connectorId` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall".appContext.linkId` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".appContext.resourceUri` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".arguments` | `any JSON value` | Required |  |
| `payload.params.item.type = "mcpToolCall".durationMs` | `integer \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".error` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.item.type = "mcpToolCall".error.message` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall".id` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall".mcpAppResourceUri` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".pluginId` | `string \| null` | Optional |  |
| `payload.params.item.type = "mcpToolCall".result` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.item.type = "mcpToolCall".result._meta` | `any JSON value` | Optional |  |
| `payload.params.item.type = "mcpToolCall".result.content` | `array<any JSON value>` | Required |  |
| `payload.params.item.type = "mcpToolCall".result.content.[]` | `any JSON value` |  |  |
| `payload.params.item.type = "mcpToolCall".result.structuredContent` | `any JSON value` | Optional |  |
| `payload.params.item.type = "mcpToolCall".server` | `string` | Required |  |
| `payload.params.item.type = "mcpToolCall".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed". |
| `payload.params.item.type = "mcpToolCall".tool` | `string` | Required |  |
| `payload.params.item.type = "contextCompaction"` | `object` |  | Additional properties are allowed. |
| `payload.params.item.type = "contextCompaction".type` | `string` | Required | Must be "contextCompaction". |
| `payload.params.item.type = "contextCompaction".id` | `string` | Required |  |
| `payload.params.threadId` | `string` | Required |  |
| `payload.params.turnId` | `string` | Required |  |
| `payload.method` | `string` | Required | Must be "item/completed". |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-thread-tokenUsage-updated"></a>

### thread/tokenUsage/updated

Reports cumulative native thread usage and usage for the latest model call.

**Example JSON**

```json
{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "thread/tokenUsage/updated",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "thread/tokenUsage/updated",
    "params": {
      "threadId": "thread_example",
      "turnId": "native_turn_example",
      "tokenUsage": {
        "total": {
          "inputTokens": 1200,
          "outputTokens": 80,
          "cachedInputTokens": 0,
          "reasoningOutputTokens": 0,
          "totalTokens": 1280
        },
        "last": {
          "inputTokens": 1200,
          "outputTokens": 80,
          "cachedInputTokens": 0,
          "reasoningOutputTokens": 0,
          "totalTokens": 1280
        },
        "modelContextWindow": 272000
      }
    }
  },
  "tools": null,
  "tokens_info": {
    "input_tokens": 1200,
    "output_tokens": 80,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "num_turns": 0,
    "cost_usd": 0
  },
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex_app_server". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_app_server@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.params` | `object` | Required | Additional properties are allowed. |
| `payload.params.threadId` | `string` | Required |  |
| `payload.params.tokenUsage` | `object` | Required | Additional properties are allowed. |
| `payload.params.tokenUsage.last` | `object` | Required | Additional properties are allowed. |
| `payload.params.tokenUsage.last.cacheWriteInputTokens` | `integer` | Optional |  |
| `payload.params.tokenUsage.last.cachedInputTokens` | `integer` | Required |  |
| `payload.params.tokenUsage.last.inputTokens` | `integer` | Required |  |
| `payload.params.tokenUsage.last.outputTokens` | `integer` | Required |  |
| `payload.params.tokenUsage.last.reasoningOutputTokens` | `integer` | Required |  |
| `payload.params.tokenUsage.last.totalTokens` | `integer` | Required |  |
| `payload.params.tokenUsage.modelContextWindow` | `integer \| null` | Optional |  |
| `payload.params.tokenUsage.total` | `object` | Required | Additional properties are allowed. |
| `payload.params.tokenUsage.total.cacheWriteInputTokens` | `integer` | Optional |  |
| `payload.params.tokenUsage.total.cachedInputTokens` | `integer` | Required |  |
| `payload.params.tokenUsage.total.inputTokens` | `integer` | Required |  |
| `payload.params.tokenUsage.total.outputTokens` | `integer` | Required |  |
| `payload.params.tokenUsage.total.reasoningOutputTokens` | `integer` | Required |  |
| `payload.params.tokenUsage.total.totalTokens` | `integer` | Required |  |
| `payload.params.turnId` | `string` | Required |  |
| `payload.method` | `string` | Required | Must be "thread/tokenUsage/updated". |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-account-rateLimits-updated"></a>

### account/rateLimits/updated

Reports native account rate-limit information as an unknown record.

**Example JSON**

```json
{
  "kind": "unknown",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "account/rateLimits/updated",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "account/rateLimits/updated",
    "params": {
      "rateLimits": {
        "limitId": "codex",
        "limitName": null,
        "primary": null,
        "secondary": null,
        "credits": null,
        "planType": null
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "unknown". |
| `source` | `string` | Required | Original producer. Unknown producers remain readable as unknown records. |
| `record_format` | `string` | Required | Original versioned payload format. |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-error"></a>

### error

Reports a native error and whether Codex intends to retry it.

**Example JSON**

```json
{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "error",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "error",
    "params": {
      "threadId": "thread_example",
      "turnId": "native_turn_example",
      "error": {
        "message": "The model request timed out."
      },
      "willRetry": true
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex_app_server". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_app_server@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.params` | `object` | Required | Additional properties are allowed. |
| `payload.params.error` | `object` | Required | Additional properties are allowed. |
| `payload.params.error.additionalDetails` | `string \| null` | Optional |  |
| `payload.params.error.codexErrorInfo` | `string \| object \| null` | Optional | Matches at least one variant below. |
| `payload.params.error.codexErrorInfo.variant 1` | `string` |  |  |
| `payload.params.error.codexErrorInfo.variant 2` | `object` |  | Additional properties are allowed. |
| `payload.params.error.message` | `string` | Required |  |
| `payload.params.threadId` | `string` | Required |  |
| `payload.params.turnId` | `string` | Required |  |
| `payload.params.willRetry` | `boolean` | Required |  |
| `payload.method` | `string` | Required | Must be "error". |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-turn-completed"></a>

### turn/completed

Reports a native turn ending with status `completed`, `failed`, or `interrupted`.

Command `item/completed` notifications can arrive after this native event. For a successful turn, Ellipsis waits up to two seconds for pending command notifications before emitting the platform [`turn_completed`](#turn_completed) event. Commands left running in the background do not keep the platform turn open indefinitely.

**Example JSON**

```json
{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "turn/completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "turn/completed",
    "params": {
      "threadId": "thread_example",
      "turn": {
        "id": "native_turn_example",
        "status": "completed",
        "items": [],
        "error": null
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex_app_server". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_app_server@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.params` | `object` | Required | Additional properties are allowed. |
| `payload.params.threadId` | `string` | Required |  |
| `payload.params.turn` | `object` | Required | Additional properties are allowed. |
| `payload.params.turn.error` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.error.additionalDetails` | `string \| null` | Optional |  |
| `payload.params.turn.error.codexErrorInfo` | `string \| object \| null` | Optional | Matches at least one variant below. |
| `payload.params.turn.error.codexErrorInfo.variant 1` | `string` |  |  |
| `payload.params.turn.error.codexErrorInfo.variant 2` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.error.message` | `string` | Required |  |
| `payload.params.turn.id` | `string` | Required |  |
| `payload.params.turn.items` | `array<object>` | Required |  |
| `payload.params.turn.items.[]` | `object` |  | Matches exactly one variant below. |
| `payload.params.turn.items.[].type = "userMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "userMessage".type` | `string` | Required | Must be "userMessage". |
| `payload.params.turn.items.[].type = "userMessage".clientId` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "userMessage".content` | `array<object>` | Required |  |
| `payload.params.turn.items.[].type = "userMessage".content.[]` | `object` |  | Matches exactly one variant below. |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text".type` | `string` | Required | Must be "text". |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text".text` | `string` | Required |  |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text".text_elements` | `array<object>` | Optional |  |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "text".text_elements.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "localImage"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "localImage".type` | `string` | Required | Must be "localImage". |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "localImage".detail` | `string \| null` | Optional | Allowed values: "auto", "low", "high", "original". |
| `payload.params.turn.items.[].type = "userMessage".content.[].type = "localImage".path` | `string` | Required |  |
| `payload.params.turn.items.[].type = "userMessage".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "agentMessage"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "agentMessage".type` | `string` | Required | Must be "agentMessage". |
| `payload.params.turn.items.[].type = "agentMessage".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "agentMessage".phase` | `string \| null` | Optional | Allowed values: "commentary", "final_answer". |
| `payload.params.turn.items.[].type = "agentMessage".text` | `string` | Required |  |
| `payload.params.turn.items.[].type = "reasoning"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "reasoning".type` | `string` | Required | Must be "reasoning". |
| `payload.params.turn.items.[].type = "reasoning".content` | `array<string>` | Optional |  |
| `payload.params.turn.items.[].type = "reasoning".content.[]` | `string` |  |  |
| `payload.params.turn.items.[].type = "reasoning".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "reasoning".summary` | `array<string>` | Optional |  |
| `payload.params.turn.items.[].type = "reasoning".summary.[]` | `string` |  |  |
| `payload.params.turn.items.[].type = "plan"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "plan".type` | `string` | Required | Must be "plan". |
| `payload.params.turn.items.[].type = "plan".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "plan".text` | `string` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "commandExecution".type` | `string` | Required | Must be "commandExecution". |
| `payload.params.turn.items.[].type = "commandExecution".aggregatedOutput` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "commandExecution".command` | `string` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution".commandActions` | `array<object>` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution".commandActions.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "commandExecution".cwd` | `string` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution".durationMs` | `integer \| null` | Optional |  |
| `payload.params.turn.items.[].type = "commandExecution".exitCode` | `integer \| null` | Optional |  |
| `payload.params.turn.items.[].type = "commandExecution".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "commandExecution".processId` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "commandExecution".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.turn.items.[].type = "fileChange"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "fileChange".type` | `string` | Required | Must be "fileChange". |
| `payload.params.turn.items.[].type = "fileChange".changes` | `array<object>` | Required |  |
| `payload.params.turn.items.[].type = "fileChange".changes.[]` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "fileChange".changes.[].kind` | `object` | Required | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "fileChange".changes.[].diff` | `string` | Required |  |
| `payload.params.turn.items.[].type = "fileChange".changes.[].path` | `string` | Required |  |
| `payload.params.turn.items.[].type = "fileChange".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "fileChange".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "declined". |
| `payload.params.turn.items.[].type = "webSearch"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "webSearch".type` | `string` | Required | Must be "webSearch". |
| `payload.params.turn.items.[].type = "webSearch".action` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "webSearch".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "webSearch".query` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "mcpToolCall".type` | `string` | Required | Must be "mcpToolCall". |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.actionName` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.appName` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.connectorId` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.linkId` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".appContext.resourceUri` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".arguments` | `any JSON value` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".durationMs` | `integer \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".error` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "mcpToolCall".error.message` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".id` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".mcpAppResourceUri` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".pluginId` | `string \| null` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".result` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "mcpToolCall".result._meta` | `any JSON value` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".result.content` | `array<any JSON value>` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".result.content.[]` | `any JSON value` |  |  |
| `payload.params.turn.items.[].type = "mcpToolCall".result.structuredContent` | `any JSON value` | Optional |  |
| `payload.params.turn.items.[].type = "mcpToolCall".server` | `string` | Required |  |
| `payload.params.turn.items.[].type = "mcpToolCall".status` | `string` | Required | Allowed values: "inProgress", "completed", "failed". |
| `payload.params.turn.items.[].type = "mcpToolCall".tool` | `string` | Required |  |
| `payload.params.turn.items.[].type = "contextCompaction"` | `object` |  | Additional properties are allowed. |
| `payload.params.turn.items.[].type = "contextCompaction".type` | `string` | Required | Must be "contextCompaction". |
| `payload.params.turn.items.[].type = "contextCompaction".id` | `string` | Required |  |
| `payload.params.turn.status` | `string` | Required | Allowed values: "inProgress", "completed", "failed", "interrupted". |
| `payload.method` | `string` | Required | Must be "turn/completed". |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

An item's `type` distinguishes `userMessage`, `agentMessage`, `reasoning`, `plan`, `commandExecution`, `fileChange`, `webSearch`, `mcpToolCall`, and `contextCompaction`. These are item variants inside notifications, not separate event methods.

`item/agentMessage/delta` supplies live [`delta` frames](#delta) with `kind: "text"`. Readable `item/reasoning/summaryTextDelta` notifications supply `kind: "thinking"` previews. Each preview replaces the first-line prefix of the current summary section; `item/reasoning/summaryPartAdded` starts a new section. Raw reasoning deltas are not included in these previews. Native incremental tool and plan notifications are not forwarded as separate customer events; completed items carry their durable content. Native RPC acknowledgements are not session records.

## WebSocket frames

Connect using the [Python SDK](/docs/api/python-sdk#stream-a-session) or [TypeScript SDK](/docs/api/typescript-sdk#stream-a-session). The public endpoint is `wss://api.ellipsis.dev/v1/sessions/{session_id}/stream?protocol=6`; authenticate with a bearer token.

Each WebSocket message contains one frame. `records_append` is the only frame that advances the resume cursor. Reconnect with `after_seq` set to the last received `feed_seq`, or let the SDK manage reconnects. If `after_seq` is less than `earliest_feed_seq - 1`, part of the requested history is no longer retained.

<a id="snapshot"></a>

### snapshot

The first frame contains the current session, pending inbox messages, and the earliest retained feed position; records follow separately.

**Example JSON**

```json
{
  "type": "snapshot",
  "protocol": 6,
  "earliest_feed_seq": 1,
  "session": {
    "id": "session_example",
    "source": "api",
    "event": null,
    "cost": {
      "llm": 0,
      "cpu": 0,
      "memory": 0,
      "fee": 0,
      "total": 0
    },
    "tokens": {
      "input": 0,
      "output": 0,
      "cache_read": 0,
      "cache_creation": 0,
      "total": 0,
      "model": "claude-sonnet-5"
    },
    "parent": null,
    "attribution": {
      "type": "api_key",
      "id": "key_example",
      "user": null
    },
    "budget": 3.0,
    "agent": null,
    "handler": null,
    "environment": {
      "id": null,
      "source": "platform_default",
      "repositories": [],
      "variables": [],
      "compute": {
        "cpu": null,
        "memory": null,
        "timeout": null
      },
      "hooks": {
        "post_start": null,
        "post_clone": null,
        "build_base": null,
        "after_checkout": null,
        "before_start": null
      },
      "mcp_servers": []
    },
    "metadata": {},
    "git": null,
    "summary": null,
    "permissions": {
      "ellipsis": true,
      "github": {
        "permissions": null,
        "repositories": null
      }
    },
    "skills": [],
    "output": null,
    "lifecycle": {
      "interactive": true,
      "status": "working",
      "detail": null,
      "conversation": "open",
      "prompting": {
        "enabled": true,
        "blocked_reason": null,
        "detail": null,
        "surface_name": null
      },
      "last_execution_result": null,
      "stopped": null,
      "archived": null,
      "timestamps": {
        "created_at": "2026-09-10T14:00:00+00:00",
        "updated_at": "2026-09-10T14:00:00+00:00",
        "last_activity_at": "2026-09-10T14:00:00+00:00",
        "last_message_at": "2026-09-10T14:00:00+00:00"
      }
    },
    "claude_code": {
      "model": "claude-sonnet-5",
      "effort": null,
      "fallback_model": null,
      "max_turns": null,
      "settings": null,
      "prompt": "Run the tests and report failures."
    },
    "codex": null
  },
  "messages": []
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `type` | `string` | Required | Must be "snapshot". |
| `earliest_feed_seq` | `integer \| null` | Required | The retention head: the lowest feed_seq still stored for this session, or null when it has no stored records. A client resuming from after_seq < earliest_feed_seq - 1 knows history is truncated. |
| `messages` | `array<object>` | Required | The session's open (pending) inbox messages. |
| `messages.[]` | `object` |  | Additional properties are allowed. |
| `messages.[].author` | `string \| null` | Required | Display attribution of the message's sender. |
| `messages.[].body` | `string` | Required | The message text, with one `[Image #N]` placeholder per attached image. |
| `messages.[].created_at` | `string` | Required | When the message was created. Format: date-time. |
| `messages.[].delivered_at` | `string \| null` | Required | When the message was delivered to the agent, if it has been. Format: date-time. |
| `messages.[].delivered_turn_id` | `string \| null` | Required | Identifier of the turn the message was delivered into, if any. |
| `messages.[].feed_seq` | `integer \| null` | Required | Where the message sits in the session's feed — placement metadata only, NOT a resume cursor (only records_append frames advance the cursor). Null for older rows. |
| `messages.[].id` | `string` | Required | Unique identifier of the message. |
| `messages.[].images` | `array<object>` | Required | Images attached to the message, metadata only: index, media type, size. The bytes go to the model, never over the stream. |
| `messages.[].images.[]` | `object` |  | Additional properties are allowed. |
| `messages.[].images.[].index` | `integer` | Required | 1-based position: the N in `[Image #N]`. |
| `messages.[].images.[].media_type` | `string` | Required | The image's MIME type. |
| `messages.[].images.[].size_bytes` | `integer` | Required | Size of the decoded image, in bytes. |
| `messages.[].sender_attribution_id` | `string \| null` | Required | Identifier of the principal that sent the message, if attributed. |
| `messages.[].sender_attribution_type` | `string \| null` | Required | Kind of principal that sent the message, if attributed. Allowed values: "github_user", "linear_user", "slack_user", "api_key". |
| `messages.[].session_id` | `string` | Required | Identifier of the session the message belongs to. |
| `messages.[].status` | `string` | Required | Delivery status of the message. Allowed values: "pending", "delivered". |
| `protocol` | `integer` | Required | Echoes the protocol version the server is serving. |
| `session` | `object` | Required | The session's current state. Additional properties are not allowed. |
| `session.source` | `string` | Required | Where the session came from (e.g. react, web, api, cli, mention, cron). Allowed values: "react", "web", "api", "cli", "mention", "cron". |
| `session.agent` | `object \| null` | Required | The agent the session was started from, or null for a raw session started with POST /v1/sessions. Additional properties are allowed. |
| `session.agent.config` | `object` | Required | The agent definition the session was started from, frozen when the session was created. Additional properties are not allowed. |
| `session.agent.config.ellipsis` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.ellipsis.kind` | `string` | Required | Must be "agent". |
| `session.agent.config.ellipsis.description` | `string \| null` | Required |  |
| `session.agent.config.ellipsis.enabled` | `boolean` | Required |  |
| `session.agent.config.ellipsis.metadata` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.ellipsis.metadata.annotations` | `object` | Required | Additional properties are allowed. |
| `session.agent.config.ellipsis.metadata.annotations.[key]` | `string` |  |  |
| `session.agent.config.ellipsis.metadata.labels` | `array<string>` | Required |  |
| `session.agent.config.ellipsis.metadata.labels.[]` | `string` |  |  |
| `session.agent.config.ellipsis.name` | `string \| null` | Required |  |
| `session.agent.config.ellipsis.version` | `string` | Required |  |
| `session.agent.config.input` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.input.json_schema` | `object \| null` | Required | Additional properties are allowed. |
| `session.agent.config.input.message` | `string \| null` | Required |  |
| `session.agent.config.session` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.budget` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.budget.day` | `number \| null` | Required |  |
| `session.agent.config.session.budget.month` | `number \| null` | Required |  |
| `session.agent.config.session.budget.session` | `number \| null` | Required | Greater than: 0. |
| `session.agent.config.session.budget.week` | `number \| null` | Required |  |
| `session.agent.config.session.claude_code` | `object \| null` | Required | Claude Code input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed. |
| `session.agent.config.session.claude_code.effort` | `string \| null` | Required | Allowed values: "low", "medium", "high", "xhigh", "max". |
| `session.agent.config.session.claude_code.fallback_model` | `string \| null` | Required |  |
| `session.agent.config.session.claude_code.max_turns` | `integer \| null` | Required | Greater than: 0. |
| `session.agent.config.session.claude_code.model` | `string \| null` | Required |  |
| `session.agent.config.session.claude_code.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session idle. |
| `session.agent.config.session.claude_code.settings` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.session.claude_code.settings.path` | `string` | Required |  |
| `session.agent.config.session.claude_code.settings.repository` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.session.claude_code.settings.repository.name` | `string` | Required |  |
| `session.agent.config.session.claude_code.settings.repository.owner` | `string \| null` | Required |  |
| `session.agent.config.session.claude_code.settings.repository.ref` | `string \| null` | Required |  |
| `session.agent.config.session.codex` | `object \| null` | Required | Codex input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed. |
| `session.agent.config.session.codex.effort` | `string \| null` | Required | Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max". |
| `session.agent.config.session.codex.model` | `string` | Required |  |
| `session.agent.config.session.codex.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session idle. |
| `session.agent.config.session.environment` | `string \| object` | Required | Matches at least one variant below. |
| `session.agent.config.session.environment.variant 1` | `string` |  |  |
| `session.agent.config.session.environment.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.compute` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.compute.cpu` | `integer \| null` | Required | Minimum: 2. Maximum: 32. |
| `session.agent.config.session.environment.variant 2.compute.memory` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.compute.memory.variant 1` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.compute.memory.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.compute.memory.variant 2.gb` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.compute.memory.variant 2.mb` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.compute.timeout` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 1` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 2.hours` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 2.minutes` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 2.seconds` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.hooks` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.hooks.after_checkout` | `object \| string \| null` | Required | Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared sandbox. Skipped when that prepared sandbox is reused. Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.hooks.after_checkout.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.hooks.after_checkout.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.agent.config.session.environment.variant 2.hooks.after_checkout.variant 2` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.hooks.before_start` | `object \| string \| null` | Required | Run before the agent starts or resumes a session, after the sandbox is ready. This hook is not cached and adds to session startup time. Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.hooks.before_start.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.hooks.before_start.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.agent.config.session.environment.variant 2.hooks.before_start.variant 2` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.hooks.build_base` | `object \| string \| null` | Required | Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs. Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 1.inputs` | `array<string> \| null` | Required | Exact files relative to /sandbox, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files. |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 1.inputs.[]` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 2` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.hooks.post_clone` | `string \| null` | Required | Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation. |
| `session.agent.config.session.environment.variant 2.hooks.post_start` | `string \| null` | Required | Legacy session startup script. Use before_start in new configurations. |
| `session.agent.config.session.environment.variant 2.mcp_servers` | `array<string \| object>` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[]` | `string \| object` |  | Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 1` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 2.name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.args` | `array<string>` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.args.[]` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.command` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.env` | `object` | Required | Additional properties are allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.env.[key]` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4.headers` | `object` | Required | Additional properties are allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4.headers.[key]` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4.name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4.url` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.repositories` | `array<object>` | Required |  |
| `session.agent.config.session.environment.variant 2.repositories.[]` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.repositories.[].name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.repositories.[].owner` | `string \| null` | Required |  |
| `session.agent.config.session.environment.variant 2.repositories.[].ref` | `string \| null` | Required |  |
| `session.agent.config.session.environment.variant 2.variables` | `array<object>` | Required |  |
| `session.agent.config.session.environment.variant 2.variables.[]` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.variables.[].name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.variables.[].value` | `string \| null` | Required |  |
| `session.agent.config.session.output` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.session.output.json_schema` | `object` | Required | Additional properties are allowed. |
| `session.agent.config.session.permissions` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.permissions.ellipsis` | `any JSON value \| object` | Required | Matches at least one variant below. |
| `session.agent.config.session.permissions.ellipsis.variant 1` | `any JSON value` |  | Allowed values: true, "all". |
| `session.agent.config.session.permissions.ellipsis.variant 2` | `object` |  | Additional properties are allowed. Allowed keys: "account", "alerts", "sessions", "files", "memories", "reviews", "configs", "defaults", "environments", "secrets", "templates", "integrations", "tokens", "webhooks", "user". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key]` | `string \| object \| array<string \| object>` |  | Matches at least one variant below. |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 1` | `string` |  | Allowed values: "read", "write", "delete". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 2.level` | `string` | Required | Allowed values: "read", "write", "delete". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 2.match` | `array<string> \| null` | Required |  |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 2.match.[]` | `string` |  |  |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3` | `array<string \| object>` |  |  |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[]` | `string \| object` |  | Matches at least one variant below. |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 1` | `string` |  | Allowed values: "read", "write", "delete". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.level` | `string` | Required | Allowed values: "read", "write", "delete". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.match` | `array<string> \| null` | Required |  |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.match.[]` | `string` |  |  |
| `session.agent.config.session.permissions.github` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.permissions.github.permissions` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.agent.config.session.permissions.github.permissions.variant 1` | `string` |  | Must be "read_only". |
| `session.agent.config.session.permissions.github.permissions.variant 2` | `object` |  | Additional properties are allowed. |
| `session.agent.config.session.permissions.github.permissions.variant 2.[key]` | `string` |  |  |
| `session.agent.config.session.permissions.github.repositories` | `array<string> \| null` | Required |  |
| `session.agent.config.session.permissions.github.repositories.[]` | `string` |  |  |
| `session.agent.config.session.skills` | `array<object>` | Required |  |
| `session.agent.config.session.skills.[]` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.skills.[].path` | `string` | Required |  |
| `session.agent.config.session.skills.[].repository` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.session.skills.[].repository.name` | `string` | Required |  |
| `session.agent.config.session.skills.[].repository.owner` | `string \| null` | Required |  |
| `session.agent.config.session.skills.[].repository.ref` | `string \| null` | Required |  |
| `session.agent.config.trigger` | `object \| null` | Required | Matches exactly one variant below. |
| `session.agent.config.trigger.type = "cron"` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "cron".type` | `string` | Required | Must be "cron". |
| `session.agent.config.trigger.type = "cron".schedule` | `string` | Required |  |
| `session.agent.config.trigger.type = "react"` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".type` | `string` | Required | Must be "react". |
| `session.agent.config.trigger.type = "react".issue` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.labels` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.labels.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.on.[]` | `string` |  | Allowed values: "opened", "closed", "commented". |
| `session.agent.config.trigger.type = "react".issue.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1` | `object` |  | The watch scope of a trigger, by repository name (owner defaults to the account). Include minus exclude: `include: []` (the default) covers every repository of the installation, so `exclude`-only means "all except these" and keeps covering repositories added to the org later. A bare list is shorthand for `include`. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".linear_issue.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".linear_issue.on.[]` | `string` |  | Allowed values: "opened". |
| `session.agent.config.trigger.type = "react".pull_request` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.base` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.base.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.draft` | `boolean \| null` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.head` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.head.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.labels` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.labels.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.on.[]` | `string` |  | Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented". |
| `session.agent.config.trigger.type = "react".pull_request.paths` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.paths.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1` | `object` |  | The watch scope of a trigger, by repository name (owner defaults to the account). Include minus exclude: `include: []` (the default) covers every repository of the installation, so `exclude`-only means "all except these" and keeps covering repositories added to the org later. A bare list is shorthand for `include`. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.paths` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.paths.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1` | `object` |  | The watch scope of a trigger, by repository name (owner defaults to the account). Include minus exclude: `include: []` (the default) covers every repository of the installation, so `exclude`-only means "all except these" and keeps covering repositories added to the org later. A bare list is shorthand for `include`. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".sentry` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".sentry.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".sentry.on.[]` | `string` |  | Allowed values: "issue_alert", "metric_alert". |
| `session.agent.config.trigger.type = "react".sentry.projects` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".sentry.projects.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".slack_channel` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.id` | `string \| null` | Required | Identifier of the saved agent this session's snapshot was taken from. Null for a routing-file agent, a code-review stage agent, or the built-in mention agent, which have no saved agent behind them. Points at the agent as it exists now, which may have changed since. |
| `session.attribution` | `object` | Required | The principal this session is attributed to. Additional properties are allowed. |
| `session.attribution.type` | `string \| null` | Required | Kind of principal the session is attributed to (e.g. a GitHub user or an API key). Allowed values: "github_user", "linear_user", "slack_user", "api_key". |
| `session.attribution.id` | `string \| null` | Required | Identifier of the principal the session is attributed to. |
| `session.attribution.user` | `object \| null` | Required | The GitHub user the session is attributed to, resolved at read time. Null when the attribution is not a GitHub user. Additional properties are allowed. |
| `session.attribution.user.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.attribution.user.avatar_url` | `string` | Required |  |
| `session.attribution.user.id` | `integer` | Required |  |
| `session.attribution.user.login` | `string` | Required |  |
| `session.budget` | `number` | Required | The spend budget enforced for this session, in US dollars, after resolving defaults and ceilings. |
| `session.claude_code` | `object \| null` | Required | Claude Code input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed. |
| `session.claude_code.effort` | `string \| null` | Required | Allowed values: "low", "medium", "high", "xhigh", "max". |
| `session.claude_code.fallback_model` | `string \| null` | Required |  |
| `session.claude_code.max_turns` | `integer \| null` | Required | Greater than: 0. |
| `session.claude_code.model` | `string \| null` | Required |  |
| `session.claude_code.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session idle. |
| `session.claude_code.settings` | `object \| null` | Required | Additional properties are not allowed. |
| `session.claude_code.settings.path` | `string` | Required |  |
| `session.claude_code.settings.repository` | `object \| null` | Required | Additional properties are not allowed. |
| `session.claude_code.settings.repository.name` | `string` | Required |  |
| `session.claude_code.settings.repository.owner` | `string \| null` | Required |  |
| `session.claude_code.settings.repository.ref` | `string \| null` | Required |  |
| `session.codex` | `object \| null` | Required | Codex input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed. |
| `session.codex.effort` | `string \| null` | Required | Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max". |
| `session.codex.model` | `string` | Required |  |
| `session.codex.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session idle. |
| `session.cost` | `object` | Required | What the session cost, in millicents, broken down by leg and carrying its own total. Additional properties are allowed. |
| `session.cost.cpu` | `integer` | Required | Sandbox CPU spend in millicents. |
| `session.cost.fee` | `integer` | Required | Platform fee in millicents. |
| `session.cost.llm` | `integer` | Required | LLM spend in millicents. |
| `session.cost.memory` | `integer` | Required | Sandbox memory spend in millicents. |
| `session.cost.total` | `integer` | Required | The grand total in millicents: llm + cpu + memory + fee. |
| `session.environment` | `object` | Required | The full environment configuration frozen when the session was created, with the saved environment's id and how it was chosen. Additional properties are not allowed. |
| `session.environment.source` | `string \| null` | Required | How the environment was chosen (request, agent, platform_default; repo_default and account_default on sessions from before those ladders were removed). An inline request uses request; an inline environment declared in session configuration has no source. Allowed values: "request", "agent", "repo_default", "account_default", "platform_default". |
| `session.environment.compute` | `object` | Required | Additional properties are not allowed. |
| `session.environment.compute.cpu` | `integer \| null` | Required | Minimum: 2. Maximum: 32. |
| `session.environment.compute.memory` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.environment.compute.memory.variant 1` | `string` |  |  |
| `session.environment.compute.memory.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.environment.compute.memory.variant 2.gb` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.compute.memory.variant 2.mb` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.compute.timeout` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.environment.compute.timeout.variant 1` | `string` |  |  |
| `session.environment.compute.timeout.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.environment.compute.timeout.variant 2.hours` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.compute.timeout.variant 2.minutes` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.compute.timeout.variant 2.seconds` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.hooks` | `object` | Required | Additional properties are not allowed. |
| `session.environment.hooks.after_checkout` | `object \| string \| null` | Required | Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared sandbox. Skipped when that prepared sandbox is reused. Matches at least one variant below. |
| `session.environment.hooks.after_checkout.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.environment.hooks.after_checkout.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.environment.hooks.after_checkout.variant 2` | `string` |  |  |
| `session.environment.hooks.before_start` | `object \| string \| null` | Required | Run before the agent starts or resumes a session, after the sandbox is ready. This hook is not cached and adds to session startup time. Matches at least one variant below. |
| `session.environment.hooks.before_start.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.environment.hooks.before_start.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.environment.hooks.before_start.variant 2` | `string` |  |  |
| `session.environment.hooks.build_base` | `object \| string \| null` | Required | Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs. Matches at least one variant below. |
| `session.environment.hooks.build_base.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.environment.hooks.build_base.variant 1.inputs` | `array<string> \| null` | Required | Exact files relative to /sandbox, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files. |
| `session.environment.hooks.build_base.variant 1.inputs.[]` | `string` |  |  |
| `session.environment.hooks.build_base.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.environment.hooks.build_base.variant 2` | `string` |  |  |
| `session.environment.hooks.post_clone` | `string \| null` | Required | Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation. |
| `session.environment.hooks.post_start` | `string \| null` | Required | Legacy session startup script. Use before_start in new configurations. |
| `session.environment.id` | `string \| null` | Required | Identifier of the saved environment the session's config resolved. Null for an inline environment block or the built-in basic sandbox. |
| `session.environment.mcp_servers` | `array<string \| object>` | Required |  |
| `session.environment.mcp_servers.[]` | `string \| object` |  | Matches at least one variant below. |
| `session.environment.mcp_servers.[].variant 1` | `string` |  |  |
| `session.environment.mcp_servers.[].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.environment.mcp_servers.[].variant 2.name` | `string` | Required |  |
| `session.environment.mcp_servers.[].variant 3` | `object` |  | Additional properties are not allowed. |
| `session.environment.mcp_servers.[].variant 3.args` | `array<string>` | Required |  |
| `session.environment.mcp_servers.[].variant 3.args.[]` | `string` |  |  |
| `session.environment.mcp_servers.[].variant 3.command` | `string` | Required |  |
| `session.environment.mcp_servers.[].variant 3.env` | `object` | Required | Additional properties are allowed. |
| `session.environment.mcp_servers.[].variant 3.env.[key]` | `string` |  |  |
| `session.environment.mcp_servers.[].variant 3.name` | `string` | Required |  |
| `session.environment.mcp_servers.[].variant 4` | `object` |  | Additional properties are not allowed. |
| `session.environment.mcp_servers.[].variant 4.headers` | `object` | Required | Additional properties are allowed. |
| `session.environment.mcp_servers.[].variant 4.headers.[key]` | `string` |  |  |
| `session.environment.mcp_servers.[].variant 4.name` | `string` | Required |  |
| `session.environment.mcp_servers.[].variant 4.url` | `string` | Required |  |
| `session.environment.repositories` | `array<object>` | Required |  |
| `session.environment.repositories.[]` | `object` |  | Additional properties are not allowed. |
| `session.environment.repositories.[].name` | `string` | Required |  |
| `session.environment.repositories.[].owner` | `string \| null` | Required |  |
| `session.environment.repositories.[].ref` | `string \| null` | Required |  |
| `session.environment.variables` | `array<object>` | Required |  |
| `session.environment.variables.[]` | `object` |  | Additional properties are not allowed. |
| `session.environment.variables.[].name` | `string` | Required |  |
| `session.environment.variables.[].value` | `string \| null` | Required |  |
| `session.event` | `object \| null` | Required | The typed external event that started the session; null for direct and scheduled starts. Matches exactly one variant below. |
| `session.event.type = "github.pull_request"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.pull_request".type` | `string` | Required | Must be "github.pull_request". |
| `session.event.type = "github.pull_request".action` | `string` | Required | Matches at least one variant below. |
| `session.event.type = "github.pull_request".action.variant 1` | `string` |  | Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented". |
| `session.event.type = "github.pull_request".action.variant 2` | `string` |  | Must be "review_commented". |
| `session.event.type = "github.pull_request".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.pull_request".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.pull_request".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.pull_request".actor.name` | `string` | Required |  |
| `session.event.type = "github.pull_request".branch` | `string` | Required |  |
| `session.event.type = "github.pull_request".number` | `integer` | Required |  |
| `session.event.type = "github.pull_request".repository` | `string` | Required |  |
| `session.event.type = "github.pull_request".title` | `string` | Required |  |
| `session.event.type = "github.pull_request".url` | `string` | Required |  |
| `session.event.type = "github.issue"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.issue".type` | `string` | Required | Must be "github.issue". |
| `session.event.type = "github.issue".action` | `string` | Required | Allowed values: "opened", "closed", "commented". |
| `session.event.type = "github.issue".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.issue".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.issue".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.issue".actor.name` | `string` | Required |  |
| `session.event.type = "github.issue".number` | `integer` | Required |  |
| `session.event.type = "github.issue".repository` | `string` | Required |  |
| `session.event.type = "github.issue".title` | `string` | Required |  |
| `session.event.type = "github.issue".url` | `string` | Required |  |
| `session.event.type = "github.push"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.push".type` | `string` | Required | Must be "github.push". |
| `session.event.type = "github.push".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.push".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.push".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.push".actor.name` | `string` | Required |  |
| `session.event.type = "github.push".after` | `string` | Required |  |
| `session.event.type = "github.push".before` | `string` | Required |  |
| `session.event.type = "github.push".branch` | `string` | Required |  |
| `session.event.type = "github.push".repository` | `string` | Required |  |
| `session.event.type = "github.push".url` | `string` | Required |  |
| `session.event.type = "linear.issue"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "linear.issue".type` | `string` | Required | Must be "linear.issue". |
| `session.event.type = "linear.issue".action` | `string` | Required | Matches at least one variant below. |
| `session.event.type = "linear.issue".action.variant 1` | `string` |  | Allowed values: "opened". |
| `session.event.type = "linear.issue".action.variant 2` | `string` |  | Must be "commented". |
| `session.event.type = "linear.issue".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "linear.issue".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "linear.issue".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "linear.issue".actor.name` | `string` | Required |  |
| `session.event.type = "linear.issue".identifier` | `string \| null` | Required |  |
| `session.event.type = "linear.issue".number` | `integer` | Required |  |
| `session.event.type = "linear.issue".title` | `string` | Required |  |
| `session.event.type = "linear.issue".url` | `string` | Required |  |
| `session.event.type = "slack.message"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "slack.message".type` | `string` | Required | Must be "slack.message". |
| `session.event.type = "slack.message".action` | `string` | Required | Allowed values: "message", "app_mention". |
| `session.event.type = "slack.message".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "slack.message".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "slack.message".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "slack.message".actor.name` | `string` | Required |  |
| `session.event.type = "slack.message".channel_id` | `string` | Required |  |
| `session.event.type = "slack.message".channel_name` | `string \| null` | Required |  |
| `session.event.type = "slack.message".message_ts` | `string` | Required |  |
| `session.event.type = "slack.message".thread_ts` | `string \| null` | Required |  |
| `session.event.type = "slack.message".url` | `string` | Required |  |
| `session.event.type = "slack.channel_created"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "slack.channel_created".type` | `string` | Required | Must be "slack.channel_created". |
| `session.event.type = "slack.channel_created".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "slack.channel_created".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "slack.channel_created".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "slack.channel_created".actor.name` | `string` | Required |  |
| `session.event.type = "slack.channel_created".channel_id` | `string` | Required |  |
| `session.event.type = "slack.channel_created".channel_name` | `string \| null` | Required |  |
| `session.event.type = "slack.channel_created".url` | `string` | Required |  |
| `session.event.type = "sentry.alert"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "sentry.alert".type` | `string` | Required | Must be "sentry.alert". |
| `session.event.type = "sentry.alert".action` | `string` | Required | Allowed values: "issue_alert", "metric_alert". |
| `session.event.type = "sentry.alert".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "sentry.alert".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "sentry.alert".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "sentry.alert".actor.name` | `string` | Required |  |
| `session.event.type = "sentry.alert".organization_slug` | `string` | Required |  |
| `session.event.type = "sentry.alert".project_slug` | `string \| null` | Required |  |
| `session.event.type = "sentry.alert".title` | `string \| null` | Required |  |
| `session.event.type = "sentry.alert".url` | `string \| null` | Required |  |
| `session.git` | `object \| null` | Required | What the session did to git, one entry per repository in its workspace: the commit and branch it sits on, per-file line counts for its uncommitted changes, and the pull requests it opened. Null if nothing was ever captured. Additional properties are allowed. |
| `session.git.repos` | `array<object>` | Required |  |
| `session.git.repos.[]` | `object` |  | Additional properties are allowed. |
| `session.git.repos.[].commits` | `array<object>` | Required |  |
| `session.git.repos.[].commits.[]` | `object` |  | Additional properties are allowed. |
| `session.git.repos.[].commits.[].committed_at` | `string` | Required | Format: date-time. |
| `session.git.repos.[].commits.[].pushed` | `boolean` | Required |  |
| `session.git.repos.[].commits.[].sha` | `string` | Required |  |
| `session.git.repos.[].commits.[].subject` | `string` | Required |  |
| `session.git.repos.[].commits_total` | `integer` | Required |  |
| `session.git.repos.[].full_name` | `string` | Required |  |
| `session.git.repos.[].local_commit` | `string \| null` | Required |  |
| `session.git.repos.[].local_uncommitted_files` | `array<object>` | Required |  |
| `session.git.repos.[].local_uncommitted_files.[]` | `object` |  | Additional properties are allowed. |
| `session.git.repos.[].local_uncommitted_files.[].additions` | `integer` | Required |  |
| `session.git.repos.[].local_uncommitted_files.[].deletions` | `integer` | Required |  |
| `session.git.repos.[].local_uncommitted_files.[].path` | `string` | Required |  |
| `session.git.repos.[].local_uncommitted_files.[].status` | `string` | Required |  |
| `session.git.repos.[].prs` | `array<object>` | Required |  |
| `session.git.repos.[].prs.[]` | `object` |  | Additional properties are allowed. |
| `session.git.repos.[].prs.[].gh_pr_id` | `integer \| null` | Required |  |
| `session.git.repos.[].prs.[].number` | `integer` | Required |  |
| `session.git.repos.[].prs.[].title` | `string \| null` | Required |  |
| `session.git.repos.[].prs.[].url` | `string` | Required |  |
| `session.git.repos.[].remote_branch` | `string \| null` | Required |  |
| `session.git.repos.[].remote_commit` | `string \| null` | Required |  |
| `session.handler` | `object \| null` | Required | The saved handler and its effective display name when this session started, frozen at creation. Null for built-in responders, legacy sessions, and sessions started without a handler. Additional properties are allowed. |
| `session.handler.agent_name` | `string` | Required | The handler's effective display name when the session started: ellipsis.name, or the service default (Slack, GitHub, Linear, or sentry). |
| `session.handler.id` | `string` | Required | Identifier of the saved handler. |
| `session.handler.service` | `string` | Required | The service the handler responds to. Allowed values: "slack", "github", "linear", "sentry". |
| `session.handler.sha` | `string` | Required | Content fingerprint of the validated handler configuration used when the session started. This is not the Git commit SHA. |
| `session.id` | `string` | Required | Unique identifier of the session. |
| `session.lifecycle` | `object` | Required | The session's activity, conversation state, messaging policy, outcomes, and timestamps. Additional properties are allowed. |
| `session.lifecycle.archived` | `object \| null` | Required | When and by whom the session was archived; null when unarchived. Archiving does not stop or close a session. Additional properties are allowed. |
| `session.lifecycle.archived.at` | `string` | Required | When the session was archived. Format: date-time. |
| `session.lifecycle.archived.by` | `object \| null` | Required | The GitHub user who archived the session; null if unknown or unavailable. Additional properties are allowed. |
| `session.lifecycle.archived.by.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.lifecycle.archived.by.avatar_url` | `string` | Required |  |
| `session.lifecycle.archived.by.id` | `integer` | Required |  |
| `session.lifecycle.archived.by.login` | `string` | Required |  |
| `session.lifecycle.conversation` | `string` | Required | Whether the conversation is open or permanently closed. Open does not imply direct messages are permitted. Allowed values: "open", "closed". |
| `session.lifecycle.detail` | `string \| null` | Required | Explanation of the current status, when applicable. |
| `session.lifecycle.interactive` | `boolean` | Required | Whether the session stays open after its first turn. |
| `session.lifecycle.last_execution_result` | `object \| null` | Required | The last finished execution's outcome, retained across resumes; null until an outcome has been recorded. Additional properties are allowed. |
| `session.lifecycle.last_execution_result.completion_reason` | `string` | Required | Why the last execution ended; completed also includes parking an open conversation. Allowed values: "completed", "budget_hit", "payment_required", "tool_call_failed", "lifecycle_hook_failed", "missing_repo_access", "missing_token_permissions", "missing_sandbox_variables", "blocked", "contact_email_required", "cancelled", "interrupted", "error", "stopped". |
| `session.lifecycle.last_execution_result.detail` | `string \| null` | Required | Human-readable explanation of that outcome. |
| `session.lifecycle.prompting` | `object` | Required | The session's policy for direct messages. Caller authorization and message validation are checked separately. Additional properties are allowed. |
| `session.lifecycle.prompting.blocked_reason` | `string \| null` | Required | Allowed values: "mention_surface", "ephemeral_trigger", "non_interactive", "harness_single_turn", "closed". |
| `session.lifecycle.prompting.detail` | `string \| null` | Required |  |
| `session.lifecycle.prompting.enabled` | `boolean` | Required |  |
| `session.lifecycle.prompting.surface_name` | `string \| null` | Required |  |
| `session.lifecycle.status` | `string` | Required | Canonical current activity. working means a turn is in progress; waiting means the worker is warm and awaiting input; idle means parked. A failed, stopped, or cancelled execution may leave an open conversation. Allowed values: "scheduled", "starting", "working", "waiting", "retrying", "idle", "closed", "failed", "stopped", "cancelled". |
| `session.lifecycle.stopped` | `object \| null` | Required | When and by whom a stop was requested; null when no stop is pending for this execution. Additional properties are allowed. |
| `session.lifecycle.stopped.at` | `string` | Required | When a stop was requested. Format: date-time. |
| `session.lifecycle.stopped.by` | `object \| null` | Required | The GitHub user who stopped the session, resolved at read time. Null if the user is unknown or unavailable. Additional properties are allowed. |
| `session.lifecycle.stopped.by.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.lifecycle.stopped.by.avatar_url` | `string` | Required |  |
| `session.lifecycle.stopped.by.id` | `integer` | Required |  |
| `session.lifecycle.stopped.by.login` | `string` | Required |  |
| `session.lifecycle.timestamps` | `object` | Required | Additional properties are allowed. |
| `session.lifecycle.timestamps.created_at` | `string` | Required | When the session was created. Format: date-time. |
| `session.lifecycle.timestamps.last_activity_at` | `string \| null` | Required | When the session last showed agent activity. Format: date-time. |
| `session.lifecycle.timestamps.last_message_at` | `string \| null` | Required | When the session last received a message. Format: date-time. |
| `session.lifecycle.timestamps.updated_at` | `string` | Required | When the session was last updated. Format: date-time. |
| `session.metadata` | `object` | Required | Caller-supplied metadata key-value pairs. Additional properties are allowed. |
| `session.metadata.[key]` | `string` |  |  |
| `session.output` | `object \| null` | Required | The structured-output exit contract for this session. Additional properties are not allowed. |
| `session.output.json_schema` | `object` | Required | Additional properties are allowed. |
| `session.parent` | `object \| null` | Required | The predecessor session this session continues; null when there is none. Additional properties are allowed. |
| `session.parent.session_id` | `string \| null` | Required | Identifier of the predecessor session this session continues, if any. |
| `session.permissions` | `object` | Required | What the session may touch, per minted credential. Additional properties are not allowed. |
| `session.permissions.ellipsis` | `any JSON value \| object` | Required | Matches at least one variant below. |
| `session.permissions.ellipsis.variant 1` | `any JSON value` |  | Allowed values: true, "all". |
| `session.permissions.ellipsis.variant 2` | `object` |  | Additional properties are allowed. Allowed keys: "account", "alerts", "sessions", "files", "memories", "reviews", "configs", "defaults", "environments", "secrets", "templates", "integrations", "tokens", "webhooks", "user". |
| `session.permissions.ellipsis.variant 2.[key]` | `string \| object \| array<string \| object>` |  | Matches at least one variant below. |
| `session.permissions.ellipsis.variant 2.[key].variant 1` | `string` |  | Allowed values: "read", "write", "delete". |
| `session.permissions.ellipsis.variant 2.[key].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.permissions.ellipsis.variant 2.[key].variant 2.level` | `string` | Required | Allowed values: "read", "write", "delete". |
| `session.permissions.ellipsis.variant 2.[key].variant 2.match` | `array<string> \| null` | Required |  |
| `session.permissions.ellipsis.variant 2.[key].variant 2.match.[]` | `string` |  |  |
| `session.permissions.ellipsis.variant 2.[key].variant 3` | `array<string \| object>` |  |  |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[]` | `string \| object` |  | Matches at least one variant below. |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 1` | `string` |  | Allowed values: "read", "write", "delete". |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.level` | `string` | Required | Allowed values: "read", "write", "delete". |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.match` | `array<string> \| null` | Required |  |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.match.[]` | `string` |  |  |
| `session.permissions.github` | `object` | Required | Additional properties are not allowed. |
| `session.permissions.github.permissions` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.permissions.github.permissions.variant 1` | `string` |  | Must be "read_only". |
| `session.permissions.github.permissions.variant 2` | `object` |  | Additional properties are allowed. |
| `session.permissions.github.permissions.variant 2.[key]` | `string` |  |  |
| `session.permissions.github.repositories` | `array<string> \| null` | Required |  |
| `session.permissions.github.repositories.[]` | `string` |  |  |
| `session.skills` | `array<object>` | Required | Skills installed for this session. |
| `session.skills.[]` | `object` |  | Additional properties are not allowed. |
| `session.skills.[].path` | `string` | Required |  |
| `session.skills.[].repository` | `object \| null` | Required | Additional properties are not allowed. |
| `session.skills.[].repository.name` | `string` | Required |  |
| `session.skills.[].repository.owner` | `string \| null` | Required |  |
| `session.skills.[].repository.ref` | `string \| null` | Required |  |
| `session.summary` | `object \| null` | Required | The latest live summary of the session's progress while it runs, and when it was generated. Additional properties are allowed. |
| `session.summary.created_at` | `string \| null` | Required | When this summary line was generated. Null on summaries written before generation time was tracked. Format: date-time. |
| `session.summary.description` | `string` | Required | One-line description of what the session is working on. |
| `session.tokens` | `object` | Required | The tokens the session spent and the model they went to. `total` includes the prompt-cache lanes. Additional properties are allowed. |
| `session.tokens.cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.tokens.cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.tokens.input` | `integer` | Required | Input tokens used. |
| `session.tokens.model` | `string` | Required | The model the token counts are attributed to. |
| `session.tokens.output` | `integer` | Required | Output tokens used. |
| `session.tokens.total` | `integer` | Required | Total tokens consumed, INCLUDING the prompt-cache reads and writes — the same basis the token cost is priced on. |

<a id="records_append"></a>

### records_append

Delivers a batch of retained or newly produced records in `feed_seq` order.

**Example JSON**

```json
{
  "type": "records_append",
  "records": [
    {
      "kind": "platform",
      "source": "lifecycle",
      "record_format": "ellipsis_lifecycle@1",
      "record_type": "turn_started",
      "id": "record_example",
      "session_id": "session_example",
      "session_execution_id": "execution_example",
      "turn_id": "turn_example",
      "session_message_id": null,
      "sandbox_id": "sandbox_example",
      "feed_seq": 12,
      "stream_seq": 8,
      "payload": {
        "turn_id": "turn_example",
        "turn_index": 0
      },
      "tools": null,
      "tokens_info": null,
      "cost": null,
      "duration": null,
      "model": null,
      "created_at": "2026-09-10T14:00:00Z"
    }
  ]
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `type` | `string` | Required | Must be "records_append". |
| `records` | `array<SessionRecord>` | Required | New session records, ordered by feed_seq. |
| `records.[]` | `SessionRecord` |  | See the record variants in [Platform](#platform), [Claude Code](#claude-code), [Codex](#codex), and [Historical formats](#historical-formats). |

<a id="session"></a>

### session

Replaces the current session object when its public fields change, including status, progress, and cost.

**Example JSON**

```json
{
  "type": "session",
  "session": {
    "id": "session_example",
    "source": "api",
    "event": null,
    "cost": {
      "llm": 0,
      "cpu": 0,
      "memory": 0,
      "fee": 0,
      "total": 0
    },
    "tokens": {
      "input": 0,
      "output": 0,
      "cache_read": 0,
      "cache_creation": 0,
      "total": 0,
      "model": "claude-sonnet-5"
    },
    "parent": null,
    "attribution": {
      "type": "api_key",
      "id": "key_example",
      "user": null
    },
    "budget": 3.0,
    "agent": null,
    "handler": null,
    "environment": {
      "id": null,
      "source": "platform_default",
      "repositories": [],
      "variables": [],
      "compute": {
        "cpu": null,
        "memory": null,
        "timeout": null
      },
      "hooks": {
        "post_start": null,
        "post_clone": null,
        "build_base": null,
        "after_checkout": null,
        "before_start": null
      },
      "mcp_servers": []
    },
    "metadata": {},
    "git": null,
    "summary": {
      "created_at": "2026-09-10T14:00:05+00:00",
      "description": "Running the test suite."
    },
    "permissions": {
      "ellipsis": true,
      "github": {
        "permissions": null,
        "repositories": null
      }
    },
    "skills": [],
    "output": null,
    "lifecycle": {
      "interactive": true,
      "status": "working",
      "detail": null,
      "conversation": "open",
      "prompting": {
        "enabled": true,
        "blocked_reason": null,
        "detail": null,
        "surface_name": null
      },
      "last_execution_result": null,
      "stopped": null,
      "archived": null,
      "timestamps": {
        "created_at": "2026-09-10T14:00:00+00:00",
        "updated_at": "2026-09-10T14:00:05+00:00",
        "last_activity_at": "2026-09-10T14:00:00+00:00",
        "last_message_at": "2026-09-10T14:00:00+00:00"
      }
    },
    "claude_code": {
      "model": "claude-sonnet-5",
      "effort": null,
      "fallback_model": null,
      "max_turns": null,
      "settings": null,
      "prompt": "Run the tests and report failures."
    },
    "codex": null
  }
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `type` | `string` | Required | Must be "session". |
| `session` | `object` | Required | The session's current state. Additional properties are not allowed. |
| `session.source` | `string` | Required | Where the session came from (e.g. react, web, api, cli, mention, cron). Allowed values: "react", "web", "api", "cli", "mention", "cron". |
| `session.agent` | `object \| null` | Required | The agent the session was started from, or null for a raw session started with POST /v1/sessions. Additional properties are allowed. |
| `session.agent.config` | `object` | Required | The agent definition the session was started from, frozen when the session was created. Additional properties are not allowed. |
| `session.agent.config.ellipsis` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.ellipsis.kind` | `string` | Required | Must be "agent". |
| `session.agent.config.ellipsis.description` | `string \| null` | Required |  |
| `session.agent.config.ellipsis.enabled` | `boolean` | Required |  |
| `session.agent.config.ellipsis.metadata` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.ellipsis.metadata.annotations` | `object` | Required | Additional properties are allowed. |
| `session.agent.config.ellipsis.metadata.annotations.[key]` | `string` |  |  |
| `session.agent.config.ellipsis.metadata.labels` | `array<string>` | Required |  |
| `session.agent.config.ellipsis.metadata.labels.[]` | `string` |  |  |
| `session.agent.config.ellipsis.name` | `string \| null` | Required |  |
| `session.agent.config.ellipsis.version` | `string` | Required |  |
| `session.agent.config.input` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.input.json_schema` | `object \| null` | Required | Additional properties are allowed. |
| `session.agent.config.input.message` | `string \| null` | Required |  |
| `session.agent.config.session` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.budget` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.budget.day` | `number \| null` | Required |  |
| `session.agent.config.session.budget.month` | `number \| null` | Required |  |
| `session.agent.config.session.budget.session` | `number \| null` | Required | Greater than: 0. |
| `session.agent.config.session.budget.week` | `number \| null` | Required |  |
| `session.agent.config.session.claude_code` | `object \| null` | Required | Claude Code input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed. |
| `session.agent.config.session.claude_code.effort` | `string \| null` | Required | Allowed values: "low", "medium", "high", "xhigh", "max". |
| `session.agent.config.session.claude_code.fallback_model` | `string \| null` | Required |  |
| `session.agent.config.session.claude_code.max_turns` | `integer \| null` | Required | Greater than: 0. |
| `session.agent.config.session.claude_code.model` | `string \| null` | Required |  |
| `session.agent.config.session.claude_code.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session idle. |
| `session.agent.config.session.claude_code.settings` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.session.claude_code.settings.path` | `string` | Required |  |
| `session.agent.config.session.claude_code.settings.repository` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.session.claude_code.settings.repository.name` | `string` | Required |  |
| `session.agent.config.session.claude_code.settings.repository.owner` | `string \| null` | Required |  |
| `session.agent.config.session.claude_code.settings.repository.ref` | `string \| null` | Required |  |
| `session.agent.config.session.codex` | `object \| null` | Required | Codex input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed. |
| `session.agent.config.session.codex.effort` | `string \| null` | Required | Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max". |
| `session.agent.config.session.codex.model` | `string` | Required |  |
| `session.agent.config.session.codex.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session idle. |
| `session.agent.config.session.environment` | `string \| object` | Required | Matches at least one variant below. |
| `session.agent.config.session.environment.variant 1` | `string` |  |  |
| `session.agent.config.session.environment.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.compute` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.compute.cpu` | `integer \| null` | Required | Minimum: 2. Maximum: 32. |
| `session.agent.config.session.environment.variant 2.compute.memory` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.compute.memory.variant 1` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.compute.memory.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.compute.memory.variant 2.gb` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.compute.memory.variant 2.mb` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.compute.timeout` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 1` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 2.hours` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 2.minutes` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.compute.timeout.variant 2.seconds` | `integer \| null` | Required | Minimum: 0. |
| `session.agent.config.session.environment.variant 2.hooks` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.hooks.after_checkout` | `object \| string \| null` | Required | Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared sandbox. Skipped when that prepared sandbox is reused. Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.hooks.after_checkout.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.hooks.after_checkout.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.agent.config.session.environment.variant 2.hooks.after_checkout.variant 2` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.hooks.before_start` | `object \| string \| null` | Required | Run before the agent starts or resumes a session, after the sandbox is ready. This hook is not cached and adds to session startup time. Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.hooks.before_start.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.hooks.before_start.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.agent.config.session.environment.variant 2.hooks.before_start.variant 2` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.hooks.build_base` | `object \| string \| null` | Required | Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs. Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 1.inputs` | `array<string> \| null` | Required | Exact files relative to /sandbox, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files. |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 1.inputs.[]` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.agent.config.session.environment.variant 2.hooks.build_base.variant 2` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.hooks.post_clone` | `string \| null` | Required | Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation. |
| `session.agent.config.session.environment.variant 2.hooks.post_start` | `string \| null` | Required | Legacy session startup script. Use before_start in new configurations. |
| `session.agent.config.session.environment.variant 2.mcp_servers` | `array<string \| object>` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[]` | `string \| object` |  | Matches at least one variant below. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 1` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 2.name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.args` | `array<string>` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.args.[]` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.command` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.env` | `object` | Required | Additional properties are allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.env.[key]` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 3.name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4.headers` | `object` | Required | Additional properties are allowed. |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4.headers.[key]` | `string` |  |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4.name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.mcp_servers.[].variant 4.url` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.repositories` | `array<object>` | Required |  |
| `session.agent.config.session.environment.variant 2.repositories.[]` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.repositories.[].name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.repositories.[].owner` | `string \| null` | Required |  |
| `session.agent.config.session.environment.variant 2.repositories.[].ref` | `string \| null` | Required |  |
| `session.agent.config.session.environment.variant 2.variables` | `array<object>` | Required |  |
| `session.agent.config.session.environment.variant 2.variables.[]` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.environment.variant 2.variables.[].name` | `string` | Required |  |
| `session.agent.config.session.environment.variant 2.variables.[].value` | `string \| null` | Required |  |
| `session.agent.config.session.output` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.session.output.json_schema` | `object` | Required | Additional properties are allowed. |
| `session.agent.config.session.permissions` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.permissions.ellipsis` | `any JSON value \| object` | Required | Matches at least one variant below. |
| `session.agent.config.session.permissions.ellipsis.variant 1` | `any JSON value` |  | Allowed values: true, "all". |
| `session.agent.config.session.permissions.ellipsis.variant 2` | `object` |  | Additional properties are allowed. Allowed keys: "account", "alerts", "sessions", "files", "memories", "reviews", "configs", "defaults", "environments", "secrets", "templates", "integrations", "tokens", "webhooks", "user". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key]` | `string \| object \| array<string \| object>` |  | Matches at least one variant below. |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 1` | `string` |  | Allowed values: "read", "write", "delete". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 2.level` | `string` | Required | Allowed values: "read", "write", "delete". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 2.match` | `array<string> \| null` | Required |  |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 2.match.[]` | `string` |  |  |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3` | `array<string \| object>` |  |  |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[]` | `string \| object` |  | Matches at least one variant below. |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 1` | `string` |  | Allowed values: "read", "write", "delete". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.level` | `string` | Required | Allowed values: "read", "write", "delete". |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.match` | `array<string> \| null` | Required |  |
| `session.agent.config.session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.match.[]` | `string` |  |  |
| `session.agent.config.session.permissions.github` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.permissions.github.permissions` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.agent.config.session.permissions.github.permissions.variant 1` | `string` |  | Must be "read_only". |
| `session.agent.config.session.permissions.github.permissions.variant 2` | `object` |  | Additional properties are allowed. |
| `session.agent.config.session.permissions.github.permissions.variant 2.[key]` | `string` |  |  |
| `session.agent.config.session.permissions.github.repositories` | `array<string> \| null` | Required |  |
| `session.agent.config.session.permissions.github.repositories.[]` | `string` |  |  |
| `session.agent.config.session.skills` | `array<object>` | Required |  |
| `session.agent.config.session.skills.[]` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.session.skills.[].path` | `string` | Required |  |
| `session.agent.config.session.skills.[].repository` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.session.skills.[].repository.name` | `string` | Required |  |
| `session.agent.config.session.skills.[].repository.owner` | `string \| null` | Required |  |
| `session.agent.config.session.skills.[].repository.ref` | `string \| null` | Required |  |
| `session.agent.config.trigger` | `object \| null` | Required | Matches exactly one variant below. |
| `session.agent.config.trigger.type = "cron"` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "cron".type` | `string` | Required | Must be "cron". |
| `session.agent.config.trigger.type = "cron".schedule` | `string` | Required |  |
| `session.agent.config.trigger.type = "react"` | `object` |  | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".type` | `string` | Required | Must be "react". |
| `session.agent.config.trigger.type = "react".issue` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.labels` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.labels.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.on.[]` | `string` |  | Allowed values: "opened", "closed", "commented". |
| `session.agent.config.trigger.type = "react".issue.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1` | `object` |  | The watch scope of a trigger, by repository name (owner defaults to the account). Include minus exclude: `include: []` (the default) covers every repository of the installation, so `exclude`-only means "all except these" and keeps covering repositories added to the org later. A bare list is shorthand for `include`. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".issue.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".linear_issue.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".linear_issue.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".linear_issue.on.[]` | `string` |  | Allowed values: "opened". |
| `session.agent.config.trigger.type = "react".pull_request` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.base` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.base.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.draft` | `boolean \| null` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.head` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.head.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.labels` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.labels.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.on.[]` | `string` |  | Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented". |
| `session.agent.config.trigger.type = "react".pull_request.paths` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.paths.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1` | `object` |  | The watch scope of a trigger, by repository name (owner defaults to the account). Include minus exclude: `include: []` (the default) covers every repository of the installation, so `exclude`-only means "all except these" and keeps covering repositories added to the org later. A bare list is shorthand for `include`. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".pull_request.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1` | `object` |  | One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.paths` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.paths.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1` | `object` |  | The watch scope of a trigger, by repository name (owner defaults to the account). Include minus exclude: `include: []` (the default) covers every repository of the installation, so `exclude`-only means "all except these" and keeps covering repositories added to the org later. A bare list is shorthand for `include`. Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".push.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".sentry` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".sentry.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".sentry.on.[]` | `string` |  | Allowed values: "issue_alert", "metric_alert". |
| `session.agent.config.trigger.type = "react".sentry.projects` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".sentry.projects.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".slack_channel` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.id` | `string \| null` | Required | Identifier of the saved agent this session's snapshot was taken from. Null for a routing-file agent, a code-review stage agent, or the built-in mention agent, which have no saved agent behind them. Points at the agent as it exists now, which may have changed since. |
| `session.attribution` | `object` | Required | The principal this session is attributed to. Additional properties are allowed. |
| `session.attribution.type` | `string \| null` | Required | Kind of principal the session is attributed to (e.g. a GitHub user or an API key). Allowed values: "github_user", "linear_user", "slack_user", "api_key". |
| `session.attribution.id` | `string \| null` | Required | Identifier of the principal the session is attributed to. |
| `session.attribution.user` | `object \| null` | Required | The GitHub user the session is attributed to, resolved at read time. Null when the attribution is not a GitHub user. Additional properties are allowed. |
| `session.attribution.user.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.attribution.user.avatar_url` | `string` | Required |  |
| `session.attribution.user.id` | `integer` | Required |  |
| `session.attribution.user.login` | `string` | Required |  |
| `session.budget` | `number` | Required | The spend budget enforced for this session, in US dollars, after resolving defaults and ceilings. |
| `session.claude_code` | `object \| null` | Required | Claude Code input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed. |
| `session.claude_code.effort` | `string \| null` | Required | Allowed values: "low", "medium", "high", "xhigh", "max". |
| `session.claude_code.fallback_model` | `string \| null` | Required |  |
| `session.claude_code.max_turns` | `integer \| null` | Required | Greater than: 0. |
| `session.claude_code.model` | `string \| null` | Required |  |
| `session.claude_code.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session idle. |
| `session.claude_code.settings` | `object \| null` | Required | Additional properties are not allowed. |
| `session.claude_code.settings.path` | `string` | Required |  |
| `session.claude_code.settings.repository` | `object \| null` | Required | Additional properties are not allowed. |
| `session.claude_code.settings.repository.name` | `string` | Required |  |
| `session.claude_code.settings.repository.owner` | `string \| null` | Required |  |
| `session.claude_code.settings.repository.ref` | `string \| null` | Required |  |
| `session.codex` | `object \| null` | Required | Codex input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed. |
| `session.codex.effort` | `string \| null` | Required | Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max". |
| `session.codex.model` | `string` | Required |  |
| `session.codex.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session idle. |
| `session.cost` | `object` | Required | What the session cost, in millicents, broken down by leg and carrying its own total. Additional properties are allowed. |
| `session.cost.cpu` | `integer` | Required | Sandbox CPU spend in millicents. |
| `session.cost.fee` | `integer` | Required | Platform fee in millicents. |
| `session.cost.llm` | `integer` | Required | LLM spend in millicents. |
| `session.cost.memory` | `integer` | Required | Sandbox memory spend in millicents. |
| `session.cost.total` | `integer` | Required | The grand total in millicents: llm + cpu + memory + fee. |
| `session.environment` | `object` | Required | The full environment configuration frozen when the session was created, with the saved environment's id and how it was chosen. Additional properties are not allowed. |
| `session.environment.source` | `string \| null` | Required | How the environment was chosen (request, agent, platform_default; repo_default and account_default on sessions from before those ladders were removed). An inline request uses request; an inline environment declared in session configuration has no source. Allowed values: "request", "agent", "repo_default", "account_default", "platform_default". |
| `session.environment.compute` | `object` | Required | Additional properties are not allowed. |
| `session.environment.compute.cpu` | `integer \| null` | Required | Minimum: 2. Maximum: 32. |
| `session.environment.compute.memory` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.environment.compute.memory.variant 1` | `string` |  |  |
| `session.environment.compute.memory.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.environment.compute.memory.variant 2.gb` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.compute.memory.variant 2.mb` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.compute.timeout` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.environment.compute.timeout.variant 1` | `string` |  |  |
| `session.environment.compute.timeout.variant 2` | `object` |  | Additional properties are not allowed. |
| `session.environment.compute.timeout.variant 2.hours` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.compute.timeout.variant 2.minutes` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.compute.timeout.variant 2.seconds` | `integer \| null` | Required | Minimum: 0. |
| `session.environment.hooks` | `object` | Required | Additional properties are not allowed. |
| `session.environment.hooks.after_checkout` | `object \| string \| null` | Required | Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared sandbox. Skipped when that prepared sandbox is reused. Matches at least one variant below. |
| `session.environment.hooks.after_checkout.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.environment.hooks.after_checkout.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.environment.hooks.after_checkout.variant 2` | `string` |  |  |
| `session.environment.hooks.before_start` | `object \| string \| null` | Required | Run before the agent starts or resumes a session, after the sandbox is ready. This hook is not cached and adds to session startup time. Matches at least one variant below. |
| `session.environment.hooks.before_start.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.environment.hooks.before_start.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.environment.hooks.before_start.variant 2` | `string` |  |  |
| `session.environment.hooks.build_base` | `object \| string \| null` | Required | Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs. Matches at least one variant below. |
| `session.environment.hooks.build_base.variant 1` | `object` |  | Additional properties are not allowed. |
| `session.environment.hooks.build_base.variant 1.inputs` | `array<string> \| null` | Required | Exact files relative to /sandbox, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files. |
| `session.environment.hooks.build_base.variant 1.inputs.[]` | `string` |  |  |
| `session.environment.hooks.build_base.variant 1.run` | `string` | Required | Shell script to run in /sandbox. |
| `session.environment.hooks.build_base.variant 2` | `string` |  |  |
| `session.environment.hooks.post_clone` | `string \| null` | Required | Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation. |
| `session.environment.hooks.post_start` | `string \| null` | Required | Legacy session startup script. Use before_start in new configurations. |
| `session.environment.id` | `string \| null` | Required | Identifier of the saved environment the session's config resolved. Null for an inline environment block or the built-in basic sandbox. |
| `session.environment.mcp_servers` | `array<string \| object>` | Required |  |
| `session.environment.mcp_servers.[]` | `string \| object` |  | Matches at least one variant below. |
| `session.environment.mcp_servers.[].variant 1` | `string` |  |  |
| `session.environment.mcp_servers.[].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.environment.mcp_servers.[].variant 2.name` | `string` | Required |  |
| `session.environment.mcp_servers.[].variant 3` | `object` |  | Additional properties are not allowed. |
| `session.environment.mcp_servers.[].variant 3.args` | `array<string>` | Required |  |
| `session.environment.mcp_servers.[].variant 3.args.[]` | `string` |  |  |
| `session.environment.mcp_servers.[].variant 3.command` | `string` | Required |  |
| `session.environment.mcp_servers.[].variant 3.env` | `object` | Required | Additional properties are allowed. |
| `session.environment.mcp_servers.[].variant 3.env.[key]` | `string` |  |  |
| `session.environment.mcp_servers.[].variant 3.name` | `string` | Required |  |
| `session.environment.mcp_servers.[].variant 4` | `object` |  | Additional properties are not allowed. |
| `session.environment.mcp_servers.[].variant 4.headers` | `object` | Required | Additional properties are allowed. |
| `session.environment.mcp_servers.[].variant 4.headers.[key]` | `string` |  |  |
| `session.environment.mcp_servers.[].variant 4.name` | `string` | Required |  |
| `session.environment.mcp_servers.[].variant 4.url` | `string` | Required |  |
| `session.environment.repositories` | `array<object>` | Required |  |
| `session.environment.repositories.[]` | `object` |  | Additional properties are not allowed. |
| `session.environment.repositories.[].name` | `string` | Required |  |
| `session.environment.repositories.[].owner` | `string \| null` | Required |  |
| `session.environment.repositories.[].ref` | `string \| null` | Required |  |
| `session.environment.variables` | `array<object>` | Required |  |
| `session.environment.variables.[]` | `object` |  | Additional properties are not allowed. |
| `session.environment.variables.[].name` | `string` | Required |  |
| `session.environment.variables.[].value` | `string \| null` | Required |  |
| `session.event` | `object \| null` | Required | The typed external event that started the session; null for direct and scheduled starts. Matches exactly one variant below. |
| `session.event.type = "github.pull_request"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.pull_request".type` | `string` | Required | Must be "github.pull_request". |
| `session.event.type = "github.pull_request".action` | `string` | Required | Matches at least one variant below. |
| `session.event.type = "github.pull_request".action.variant 1` | `string` |  | Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented". |
| `session.event.type = "github.pull_request".action.variant 2` | `string` |  | Must be "review_commented". |
| `session.event.type = "github.pull_request".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.pull_request".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.pull_request".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.pull_request".actor.name` | `string` | Required |  |
| `session.event.type = "github.pull_request".branch` | `string` | Required |  |
| `session.event.type = "github.pull_request".number` | `integer` | Required |  |
| `session.event.type = "github.pull_request".repository` | `string` | Required |  |
| `session.event.type = "github.pull_request".title` | `string` | Required |  |
| `session.event.type = "github.pull_request".url` | `string` | Required |  |
| `session.event.type = "github.issue"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.issue".type` | `string` | Required | Must be "github.issue". |
| `session.event.type = "github.issue".action` | `string` | Required | Allowed values: "opened", "closed", "commented". |
| `session.event.type = "github.issue".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.issue".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.issue".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.issue".actor.name` | `string` | Required |  |
| `session.event.type = "github.issue".number` | `integer` | Required |  |
| `session.event.type = "github.issue".repository` | `string` | Required |  |
| `session.event.type = "github.issue".title` | `string` | Required |  |
| `session.event.type = "github.issue".url` | `string` | Required |  |
| `session.event.type = "github.push"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.push".type` | `string` | Required | Must be "github.push". |
| `session.event.type = "github.push".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.push".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.push".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.push".actor.name` | `string` | Required |  |
| `session.event.type = "github.push".after` | `string` | Required |  |
| `session.event.type = "github.push".before` | `string` | Required |  |
| `session.event.type = "github.push".branch` | `string` | Required |  |
| `session.event.type = "github.push".repository` | `string` | Required |  |
| `session.event.type = "github.push".url` | `string` | Required |  |
| `session.event.type = "linear.issue"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "linear.issue".type` | `string` | Required | Must be "linear.issue". |
| `session.event.type = "linear.issue".action` | `string` | Required | Matches at least one variant below. |
| `session.event.type = "linear.issue".action.variant 1` | `string` |  | Allowed values: "opened". |
| `session.event.type = "linear.issue".action.variant 2` | `string` |  | Must be "commented". |
| `session.event.type = "linear.issue".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "linear.issue".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "linear.issue".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "linear.issue".actor.name` | `string` | Required |  |
| `session.event.type = "linear.issue".identifier` | `string \| null` | Required |  |
| `session.event.type = "linear.issue".number` | `integer` | Required |  |
| `session.event.type = "linear.issue".title` | `string` | Required |  |
| `session.event.type = "linear.issue".url` | `string` | Required |  |
| `session.event.type = "slack.message"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "slack.message".type` | `string` | Required | Must be "slack.message". |
| `session.event.type = "slack.message".action` | `string` | Required | Allowed values: "message", "app_mention". |
| `session.event.type = "slack.message".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "slack.message".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "slack.message".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "slack.message".actor.name` | `string` | Required |  |
| `session.event.type = "slack.message".channel_id` | `string` | Required |  |
| `session.event.type = "slack.message".channel_name` | `string \| null` | Required |  |
| `session.event.type = "slack.message".message_ts` | `string` | Required |  |
| `session.event.type = "slack.message".thread_ts` | `string \| null` | Required |  |
| `session.event.type = "slack.message".url` | `string` | Required |  |
| `session.event.type = "slack.channel_created"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "slack.channel_created".type` | `string` | Required | Must be "slack.channel_created". |
| `session.event.type = "slack.channel_created".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "slack.channel_created".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "slack.channel_created".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "slack.channel_created".actor.name` | `string` | Required |  |
| `session.event.type = "slack.channel_created".channel_id` | `string` | Required |  |
| `session.event.type = "slack.channel_created".channel_name` | `string \| null` | Required |  |
| `session.event.type = "slack.channel_created".url` | `string` | Required |  |
| `session.event.type = "sentry.alert"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "sentry.alert".type` | `string` | Required | Must be "sentry.alert". |
| `session.event.type = "sentry.alert".action` | `string` | Required | Allowed values: "issue_alert", "metric_alert". |
| `session.event.type = "sentry.alert".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "sentry.alert".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "sentry.alert".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "sentry.alert".actor.name` | `string` | Required |  |
| `session.event.type = "sentry.alert".organization_slug` | `string` | Required |  |
| `session.event.type = "sentry.alert".project_slug` | `string \| null` | Required |  |
| `session.event.type = "sentry.alert".title` | `string \| null` | Required |  |
| `session.event.type = "sentry.alert".url` | `string \| null` | Required |  |
| `session.git` | `object \| null` | Required | What the session did to git, one entry per repository in its workspace: the commit and branch it sits on, per-file line counts for its uncommitted changes, and the pull requests it opened. Null if nothing was ever captured. Additional properties are allowed. |
| `session.git.repos` | `array<object>` | Required |  |
| `session.git.repos.[]` | `object` |  | Additional properties are allowed. |
| `session.git.repos.[].commits` | `array<object>` | Required |  |
| `session.git.repos.[].commits.[]` | `object` |  | Additional properties are allowed. |
| `session.git.repos.[].commits.[].committed_at` | `string` | Required | Format: date-time. |
| `session.git.repos.[].commits.[].pushed` | `boolean` | Required |  |
| `session.git.repos.[].commits.[].sha` | `string` | Required |  |
| `session.git.repos.[].commits.[].subject` | `string` | Required |  |
| `session.git.repos.[].commits_total` | `integer` | Required |  |
| `session.git.repos.[].full_name` | `string` | Required |  |
| `session.git.repos.[].local_commit` | `string \| null` | Required |  |
| `session.git.repos.[].local_uncommitted_files` | `array<object>` | Required |  |
| `session.git.repos.[].local_uncommitted_files.[]` | `object` |  | Additional properties are allowed. |
| `session.git.repos.[].local_uncommitted_files.[].additions` | `integer` | Required |  |
| `session.git.repos.[].local_uncommitted_files.[].deletions` | `integer` | Required |  |
| `session.git.repos.[].local_uncommitted_files.[].path` | `string` | Required |  |
| `session.git.repos.[].local_uncommitted_files.[].status` | `string` | Required |  |
| `session.git.repos.[].prs` | `array<object>` | Required |  |
| `session.git.repos.[].prs.[]` | `object` |  | Additional properties are allowed. |
| `session.git.repos.[].prs.[].gh_pr_id` | `integer \| null` | Required |  |
| `session.git.repos.[].prs.[].number` | `integer` | Required |  |
| `session.git.repos.[].prs.[].title` | `string \| null` | Required |  |
| `session.git.repos.[].prs.[].url` | `string` | Required |  |
| `session.git.repos.[].remote_branch` | `string \| null` | Required |  |
| `session.git.repos.[].remote_commit` | `string \| null` | Required |  |
| `session.handler` | `object \| null` | Required | The saved handler and its effective display name when this session started, frozen at creation. Null for built-in responders, legacy sessions, and sessions started without a handler. Additional properties are allowed. |
| `session.handler.agent_name` | `string` | Required | The handler's effective display name when the session started: ellipsis.name, or the service default (Slack, GitHub, Linear, or sentry). |
| `session.handler.id` | `string` | Required | Identifier of the saved handler. |
| `session.handler.service` | `string` | Required | The service the handler responds to. Allowed values: "slack", "github", "linear", "sentry". |
| `session.handler.sha` | `string` | Required | Content fingerprint of the validated handler configuration used when the session started. This is not the Git commit SHA. |
| `session.id` | `string` | Required | Unique identifier of the session. |
| `session.lifecycle` | `object` | Required | The session's activity, conversation state, messaging policy, outcomes, and timestamps. Additional properties are allowed. |
| `session.lifecycle.archived` | `object \| null` | Required | When and by whom the session was archived; null when unarchived. Archiving does not stop or close a session. Additional properties are allowed. |
| `session.lifecycle.archived.at` | `string` | Required | When the session was archived. Format: date-time. |
| `session.lifecycle.archived.by` | `object \| null` | Required | The GitHub user who archived the session; null if unknown or unavailable. Additional properties are allowed. |
| `session.lifecycle.archived.by.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.lifecycle.archived.by.avatar_url` | `string` | Required |  |
| `session.lifecycle.archived.by.id` | `integer` | Required |  |
| `session.lifecycle.archived.by.login` | `string` | Required |  |
| `session.lifecycle.conversation` | `string` | Required | Whether the conversation is open or permanently closed. Open does not imply direct messages are permitted. Allowed values: "open", "closed". |
| `session.lifecycle.detail` | `string \| null` | Required | Explanation of the current status, when applicable. |
| `session.lifecycle.interactive` | `boolean` | Required | Whether the session stays open after its first turn. |
| `session.lifecycle.last_execution_result` | `object \| null` | Required | The last finished execution's outcome, retained across resumes; null until an outcome has been recorded. Additional properties are allowed. |
| `session.lifecycle.last_execution_result.completion_reason` | `string` | Required | Why the last execution ended; completed also includes parking an open conversation. Allowed values: "completed", "budget_hit", "payment_required", "tool_call_failed", "lifecycle_hook_failed", "missing_repo_access", "missing_token_permissions", "missing_sandbox_variables", "blocked", "contact_email_required", "cancelled", "interrupted", "error", "stopped". |
| `session.lifecycle.last_execution_result.detail` | `string \| null` | Required | Human-readable explanation of that outcome. |
| `session.lifecycle.prompting` | `object` | Required | The session's policy for direct messages. Caller authorization and message validation are checked separately. Additional properties are allowed. |
| `session.lifecycle.prompting.blocked_reason` | `string \| null` | Required | Allowed values: "mention_surface", "ephemeral_trigger", "non_interactive", "harness_single_turn", "closed". |
| `session.lifecycle.prompting.detail` | `string \| null` | Required |  |
| `session.lifecycle.prompting.enabled` | `boolean` | Required |  |
| `session.lifecycle.prompting.surface_name` | `string \| null` | Required |  |
| `session.lifecycle.status` | `string` | Required | Canonical current activity. working means a turn is in progress; waiting means the worker is warm and awaiting input; idle means parked. A failed, stopped, or cancelled execution may leave an open conversation. Allowed values: "scheduled", "starting", "working", "waiting", "retrying", "idle", "closed", "failed", "stopped", "cancelled". |
| `session.lifecycle.stopped` | `object \| null` | Required | When and by whom a stop was requested; null when no stop is pending for this execution. Additional properties are allowed. |
| `session.lifecycle.stopped.at` | `string` | Required | When a stop was requested. Format: date-time. |
| `session.lifecycle.stopped.by` | `object \| null` | Required | The GitHub user who stopped the session, resolved at read time. Null if the user is unknown or unavailable. Additional properties are allowed. |
| `session.lifecycle.stopped.by.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.lifecycle.stopped.by.avatar_url` | `string` | Required |  |
| `session.lifecycle.stopped.by.id` | `integer` | Required |  |
| `session.lifecycle.stopped.by.login` | `string` | Required |  |
| `session.lifecycle.timestamps` | `object` | Required | Additional properties are allowed. |
| `session.lifecycle.timestamps.created_at` | `string` | Required | When the session was created. Format: date-time. |
| `session.lifecycle.timestamps.last_activity_at` | `string \| null` | Required | When the session last showed agent activity. Format: date-time. |
| `session.lifecycle.timestamps.last_message_at` | `string \| null` | Required | When the session last received a message. Format: date-time. |
| `session.lifecycle.timestamps.updated_at` | `string` | Required | When the session was last updated. Format: date-time. |
| `session.metadata` | `object` | Required | Caller-supplied metadata key-value pairs. Additional properties are allowed. |
| `session.metadata.[key]` | `string` |  |  |
| `session.output` | `object \| null` | Required | The structured-output exit contract for this session. Additional properties are not allowed. |
| `session.output.json_schema` | `object` | Required | Additional properties are allowed. |
| `session.parent` | `object \| null` | Required | The predecessor session this session continues; null when there is none. Additional properties are allowed. |
| `session.parent.session_id` | `string \| null` | Required | Identifier of the predecessor session this session continues, if any. |
| `session.permissions` | `object` | Required | What the session may touch, per minted credential. Additional properties are not allowed. |
| `session.permissions.ellipsis` | `any JSON value \| object` | Required | Matches at least one variant below. |
| `session.permissions.ellipsis.variant 1` | `any JSON value` |  | Allowed values: true, "all". |
| `session.permissions.ellipsis.variant 2` | `object` |  | Additional properties are allowed. Allowed keys: "account", "alerts", "sessions", "files", "memories", "reviews", "configs", "defaults", "environments", "secrets", "templates", "integrations", "tokens", "webhooks", "user". |
| `session.permissions.ellipsis.variant 2.[key]` | `string \| object \| array<string \| object>` |  | Matches at least one variant below. |
| `session.permissions.ellipsis.variant 2.[key].variant 1` | `string` |  | Allowed values: "read", "write", "delete". |
| `session.permissions.ellipsis.variant 2.[key].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.permissions.ellipsis.variant 2.[key].variant 2.level` | `string` | Required | Allowed values: "read", "write", "delete". |
| `session.permissions.ellipsis.variant 2.[key].variant 2.match` | `array<string> \| null` | Required |  |
| `session.permissions.ellipsis.variant 2.[key].variant 2.match.[]` | `string` |  |  |
| `session.permissions.ellipsis.variant 2.[key].variant 3` | `array<string \| object>` |  |  |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[]` | `string \| object` |  | Matches at least one variant below. |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 1` | `string` |  | Allowed values: "read", "write", "delete". |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2` | `object` |  | Additional properties are not allowed. |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.level` | `string` | Required | Allowed values: "read", "write", "delete". |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.match` | `array<string> \| null` | Required |  |
| `session.permissions.ellipsis.variant 2.[key].variant 3.[].variant 2.match.[]` | `string` |  |  |
| `session.permissions.github` | `object` | Required | Additional properties are not allowed. |
| `session.permissions.github.permissions` | `string \| object \| null` | Required | Matches at least one variant below. |
| `session.permissions.github.permissions.variant 1` | `string` |  | Must be "read_only". |
| `session.permissions.github.permissions.variant 2` | `object` |  | Additional properties are allowed. |
| `session.permissions.github.permissions.variant 2.[key]` | `string` |  |  |
| `session.permissions.github.repositories` | `array<string> \| null` | Required |  |
| `session.permissions.github.repositories.[]` | `string` |  |  |
| `session.skills` | `array<object>` | Required | Skills installed for this session. |
| `session.skills.[]` | `object` |  | Additional properties are not allowed. |
| `session.skills.[].path` | `string` | Required |  |
| `session.skills.[].repository` | `object \| null` | Required | Additional properties are not allowed. |
| `session.skills.[].repository.name` | `string` | Required |  |
| `session.skills.[].repository.owner` | `string \| null` | Required |  |
| `session.skills.[].repository.ref` | `string \| null` | Required |  |
| `session.summary` | `object \| null` | Required | The latest live summary of the session's progress while it runs, and when it was generated. Additional properties are allowed. |
| `session.summary.created_at` | `string \| null` | Required | When this summary line was generated. Null on summaries written before generation time was tracked. Format: date-time. |
| `session.summary.description` | `string` | Required | One-line description of what the session is working on. |
| `session.tokens` | `object` | Required | The tokens the session spent and the model they went to. `total` includes the prompt-cache lanes. Additional properties are allowed. |
| `session.tokens.cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.tokens.cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.tokens.input` | `integer` | Required | Input tokens used. |
| `session.tokens.model` | `string` | Required | The model the token counts are attributed to. |
| `session.tokens.output` | `integer` | Required | Output tokens used. |
| `session.tokens.total` | `integer` | Required | Total tokens consumed, INCLUDING the prompt-cache reads and writes — the same basis the token cost is priced on. |

<a id="delta"></a>

### delta

Streams assistant text, a live reasoning-summary preview, or a response output-token count.

**Example JSON**

```json
{
  "type": "delta",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "kind": "text",
  "text": "All 12 tests",
  "output_tokens": 4
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `type` | `string` | Required | Must be "delta". |
| `kind` | `string` | Required | Known values: text (append assistant output), thinking (replace the readable reasoning-summary preview). Open vocabulary: ignore deltas with unknown kinds. |
| `output_tokens` | `integer \| null` | Required | Output tokens generated so far for the current response. |
| `session_execution_id` | `string \| null` | Required | Execution producing this live output. |
| `text` | `string \| null` | Required | For "text", an append-only fragment. For "thinking", the first-line prefix of the latest summary section (at most 512 characters); replace the preview, and clear it on an empty string. Null means no text update. |
| `turn_id` | `string \| null` | Required | Identifier of the turn the delta belongs to, if known. |

<a id="delta-thinking"></a>

### delta

Replaces the current readable reasoning-summary preview while the agent works (kind: thinking).

For a working subtitle, replace your current preview with each `thinking` update. This illustrative update contains a summary heading:

```json
{
  "type": "delta",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "kind": "thinking",
  "text": "**Inspecting the mock server**",
  "output_tokens": null
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `type` | `string` | Required | Must be "delta". |
| `kind` | `string` | Required | Known values: text (append assistant output), thinking (replace the readable reasoning-summary preview). Open vocabulary: ignore deltas with unknown kinds. |
| `output_tokens` | `integer \| null` | Required | Output tokens generated so far for the current response. |
| `session_execution_id` | `string \| null` | Required | Execution producing this live output. |
| `text` | `string \| null` | Required | For "text", an append-only fragment. For "thinking", the first-line prefix of the latest summary section (at most 512 characters); replace the preview, and clear it on an empty string. Null means no text update. |
| `turn_id` | `string \| null` | Required | Identifier of the turn the delta belongs to, if known. |

<a id="heartbeat"></a>

### heartbeat

Keeps an otherwise idle connection alive, normally after 20 seconds without other updates.

**Example JSON**

```json
{
  "type": "heartbeat",
  "ts": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `type` | `string` | Required | Must be "heartbeat". |
| `ts` | `string` | Required | Server time when the heartbeat was sent. Format: date-time. |

<a id="done"></a>

### done

Marks the end of the conversation after the final records and state updates, followed by a normal socket close.

**Example JSON**

```json
{
  "type": "done"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `type` | `string` | Required | Must be "done". |

<a id="error"></a>

### error

Reports a stream-server failure before the socket closes.

**Example JSON**

```json
{
  "type": "error",
  "message": "Something went wrong streaming this session."
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `type` | `string` | Required | Must be "error". |
| `message` | `string` | Required | A human-readable error message. |

For `delta.kind: "text"`, append `text` to the live assistant response. For `kind: "thinking"`, replace the summary preview with `text`; it contains at most 512 characters from the first line of the current readable summary section. An empty string clears the preview, and null leaves it unchanged. Thinking previews do not change the output-token counter. Clear the preview when the agent starts writing, the turn finishes or fails, or a reconnect supplies a new snapshot. Models that do not emit readable summaries keep the generic working indicator.

A text delta can carry only text or only an output-token count, with the other field null. Deltas have no resume cursor and can be missed across reconnects; render the completed record as the authority. Ignore unknown delta kinds.

A parked conversation can remain connected without a `done` frame. For durable conversations, `done` follows closure, not each completed turn or idle period. Older sessions without a conversation state finish streaming when their execution reaches a terminal status.

## Historical formats

Existing history keeps its original payload format. These examples cover compatibility when reading or replaying older sessions; new executions use the formats above.

### Claude SDK records

`kind: "claude_sdk"` and `record_format: "claude_sdk@1"` identify historical Claude projections. Their payload discriminator is `kind`, rather than native `type`.

<a id="claude-sdk-system"></a>

### system

Reports historical harness metadata through `subtype` and `data`.

**Example JSON**

```json
{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "system",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "system",
    "subtype": "init",
    "data": {
      "model": "claude-sonnet-5"
    },
    "session_id": "11111111-1111-4111-8111-111111111111"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_sdk". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_sdk@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.kind` | `string` | Required | Must be "system". |
| `payload.data` | `object` | Optional | Additional properties are allowed. |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.subtype` | `string` | Required |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-sdk-user"></a>

### user

Carries a historical user prompt or tool-result content.

**Example JSON**

```json
{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "user",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "user",
    "content": "Run the tests and report failures."
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_sdk". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_sdk@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.kind` | `string` | Required | Must be "user". |
| `payload.content` | `string \| array<object>` | Required | Matches at least one variant below. |
| `payload.content.variant 1` | `string` |  |  |
| `payload.content.variant 2` | `array<object>` |  |  |
| `payload.content.variant 2.[]` | `object` |  | Matches exactly one variant below. |
| `payload.content.variant 2.[].type = "text"` | `object` |  | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "text".type` | `string` | Required | Must be "text". |
| `payload.content.variant 2.[].type = "text".text` | `string` | Required |  |
| `payload.content.variant 2.[].type = "thinking"` | `object` |  | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "thinking".type` | `string` | Required | Must be "thinking". |
| `payload.content.variant 2.[].type = "thinking".signature` | `string` | Required |  |
| `payload.content.variant 2.[].type = "thinking".thinking` | `string` | Required |  |
| `payload.content.variant 2.[].type = "tool_use"` | `object` |  | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "tool_use".type` | `string` | Required | Must be "tool_use". |
| `payload.content.variant 2.[].type = "tool_use".id` | `string` | Required |  |
| `payload.content.variant 2.[].type = "tool_use".input` | `object` | Optional | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "tool_use".name` | `string` | Required |  |
| `payload.content.variant 2.[].type = "tool_result"` | `object` |  | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "tool_result".type` | `string` | Required | Must be "tool_result". |
| `payload.content.variant 2.[].type = "tool_result".content` | `string \| array<object> \| null` | Optional | Matches at least one variant below. |
| `payload.content.variant 2.[].type = "tool_result".content.variant 1` | `string` |  |  |
| `payload.content.variant 2.[].type = "tool_result".content.variant 2` | `array<object>` |  |  |
| `payload.content.variant 2.[].type = "tool_result".content.variant 2.[]` | `object` |  | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "tool_result".is_error` | `boolean \| null` | Optional |  |
| `payload.content.variant 2.[].type = "tool_result".tool_use_id` | `string` | Required |  |
| `payload.content.variant 2.[].type = "server_tool_use"` | `object` |  | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "server_tool_use".type` | `string` | Required | Must be "server_tool_use". |
| `payload.content.variant 2.[].type = "server_tool_use".id` | `string` | Required |  |
| `payload.content.variant 2.[].type = "server_tool_use".input` | `object` | Optional | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "server_tool_use".name` | `string` | Required |  |
| `payload.content.variant 2.[].type = "server_tool_result"` | `object` |  | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "server_tool_result".type` | `string` | Required | Must be "server_tool_result". |
| `payload.content.variant 2.[].type = "server_tool_result".content` | `object` | Optional | Additional properties are allowed. |
| `payload.content.variant 2.[].type = "server_tool_result".tool_use_id` | `string` | Required |  |
| `payload.parent_tool_use_id` | `string \| null` | Optional |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-sdk-assistant"></a>

### assistant

Carries historical assistant content with its model at the payload root.

**Example JSON**

```json
{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "assistant",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "assistant",
    "model": "claude-sonnet-5",
    "content": [
      {
        "type": "text",
        "text": "All 12 tests passed."
      }
    ]
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": "claude-sonnet-5",
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_sdk". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_sdk@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.kind` | `string` | Required | Must be "assistant". |
| `payload.cache_creation` | `object \| null` | Optional | Additional properties are not allowed. |
| `payload.cache_creation.ephemeral_1h_input_tokens` | `integer` | Optional |  |
| `payload.cache_creation.ephemeral_5m_input_tokens` | `integer` | Optional |  |
| `payload.content` | `array<object>` | Optional |  |
| `payload.content.[]` | `object` |  | Matches exactly one variant below. |
| `payload.content.[].type = "text"` | `object` |  | Additional properties are allowed. |
| `payload.content.[].type = "text".type` | `string` | Required | Must be "text". |
| `payload.content.[].type = "text".text` | `string` | Required |  |
| `payload.content.[].type = "thinking"` | `object` |  | Additional properties are allowed. |
| `payload.content.[].type = "thinking".type` | `string` | Required | Must be "thinking". |
| `payload.content.[].type = "thinking".signature` | `string` | Required |  |
| `payload.content.[].type = "thinking".thinking` | `string` | Required |  |
| `payload.content.[].type = "tool_use"` | `object` |  | Additional properties are allowed. |
| `payload.content.[].type = "tool_use".type` | `string` | Required | Must be "tool_use". |
| `payload.content.[].type = "tool_use".id` | `string` | Required |  |
| `payload.content.[].type = "tool_use".input` | `object` | Optional | Additional properties are allowed. |
| `payload.content.[].type = "tool_use".name` | `string` | Required |  |
| `payload.content.[].type = "tool_result"` | `object` |  | Additional properties are allowed. |
| `payload.content.[].type = "tool_result".type` | `string` | Required | Must be "tool_result". |
| `payload.content.[].type = "tool_result".content` | `string \| array<object> \| null` | Optional | Matches at least one variant below. |
| `payload.content.[].type = "tool_result".content.variant 1` | `string` |  |  |
| `payload.content.[].type = "tool_result".content.variant 2` | `array<object>` |  |  |
| `payload.content.[].type = "tool_result".content.variant 2.[]` | `object` |  | Additional properties are allowed. |
| `payload.content.[].type = "tool_result".is_error` | `boolean \| null` | Optional |  |
| `payload.content.[].type = "tool_result".tool_use_id` | `string` | Required |  |
| `payload.content.[].type = "server_tool_use"` | `object` |  | Additional properties are allowed. |
| `payload.content.[].type = "server_tool_use".type` | `string` | Required | Must be "server_tool_use". |
| `payload.content.[].type = "server_tool_use".id` | `string` | Required |  |
| `payload.content.[].type = "server_tool_use".input` | `object` | Optional | Additional properties are allowed. |
| `payload.content.[].type = "server_tool_use".name` | `string` | Required |  |
| `payload.content.[].type = "server_tool_result"` | `object` |  | Additional properties are allowed. |
| `payload.content.[].type = "server_tool_result".type` | `string` | Required | Must be "server_tool_result". |
| `payload.content.[].type = "server_tool_result".content` | `object` | Optional | Additional properties are allowed. |
| `payload.content.[].type = "server_tool_result".tool_use_id` | `string` | Required |  |
| `payload.error` | `string \| null` | Optional |  |
| `payload.message_id` | `string \| null` | Optional |  |
| `payload.model` | `string` | Required |  |
| `payload.parent_tool_use_id` | `string \| null` | Optional |  |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.stop_reason` | `string \| null` | Optional |  |
| `payload.usage` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.usage.cache_creation_input_tokens` | `integer` | Optional |  |
| `payload.usage.cache_read_input_tokens` | `integer` | Optional |  |
| `payload.usage.cost_usd` | `number` | Optional |  |
| `payload.usage.input_tokens` | `integer` | Optional |  |
| `payload.usage.num_turns` | `integer` | Optional |  |
| `payload.usage.output_tokens` | `integer` | Optional |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-sdk-result"></a>

### result

Reports a historical turn outcome with `cost_usd` rather than the native `total_cost_usd` field.

**Example JSON**

```json
{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "result",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "result",
    "subtype": "success",
    "is_error": false,
    "num_turns": 1,
    "duration_ms": 4200,
    "duration_api_ms": 3100,
    "result": "All 12 tests passed.",
    "cost_usd": 0.01
  },
  "tools": null,
  "tokens_info": null,
  "cost": 1000,
  "duration": 4200,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_sdk". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_sdk@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.kind` | `string` | Required | Must be "result". |
| `payload.api_error_status` | `integer \| null` | Optional |  |
| `payload.cost_usd` | `number \| null` | Optional |  |
| `payload.duration_api_ms` | `integer` | Required |  |
| `payload.duration_ms` | `integer` | Required |  |
| `payload.errors` | `array<string> \| null` | Optional |  |
| `payload.errors.[]` | `string` |  |  |
| `payload.is_error` | `boolean` | Required |  |
| `payload.model_usage` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.num_turns` | `integer` | Required |  |
| `payload.result` | `string \| null` | Optional |  |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.stop_reason` | `string \| null` | Optional |  |
| `payload.structured_output` | `any JSON value` | Optional |  |
| `payload.subtype` | `string` | Required |  |
| `payload.usage` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.usage.cache_creation_input_tokens` | `integer` | Optional |  |
| `payload.usage.cache_read_input_tokens` | `integer` | Optional |  |
| `payload.usage.cost_usd` | `number` | Optional |  |
| `payload.usage.input_tokens` | `integer` | Optional |  |
| `payload.usage.num_turns` | `integer` | Optional |  |
| `payload.usage.output_tokens` | `integer` | Optional |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="claude-sdk-rate_limit"></a>

### rate_limit

Reports historical rate-limit information with snake_case fields.

**Example JSON**

```json
{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "rate_limit",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "rate_limit",
    "status": "allowed",
    "rate_limit_type": "five_hour",
    "utilization": 0.25,
    "resets_at": 1789066800
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "claude_sdk". |
| `source` | `string` | Required | Must be "claude_code". |
| `record_format` | `string` | Required | Must be "claude_sdk@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.kind` | `string` | Required | Must be "rate_limit". |
| `payload.rate_limit_type` | `string \| null` | Optional |  |
| `payload.resets_at` | `integer \| null` | Optional |  |
| `payload.session_id` | `string \| null` | Optional |  |
| `payload.status` | `string` | Required |  |
| `payload.utilization` | `number \| null` | Optional |  |
| `payload.uuid` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

### Codex JSONL records

`kind: "codex"` and `record_format: "codex_jsonl@1"` identify historical Codex events. Their names use dots, and the payload discriminator is `type`.

<a id="codex-jsonl-thread-started"></a>

### thread.started

Announces the historical native thread identifier.

**Example JSON**

```json
{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "thread.started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "thread.started",
    "thread_id": "thread_example"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "thread.started". |
| `payload.thread_id` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-jsonl-turn-started"></a>

### turn.started

Announces a historical native turn beginning.

**Example JSON**

```json
{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "turn.started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "turn.started"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "turn.started". |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-jsonl-item-started"></a>

### item.started

Announces a historical conversation item beginning.

**Example JSON**

```json
{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "item.started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "item.started",
    "item": {
      "id": "command_example",
      "type": "command_execution",
      "command": "pytest -q",
      "status": "in_progress",
      "aggregated_output": ""
    }
  },
  "tools": ["Bash"],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "item.started". |
| `payload.item` | `object` | Required | Matches exactly one variant below. |
| `payload.item.type = "agent_message"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "agent_message".type` | `string` | Required | Must be "agent_message". |
| `payload.item.type = "agent_message".id` | `string \| null` | Optional |  |
| `payload.item.type = "agent_message".text` | `string` | Optional |  |
| `payload.item.type = "reasoning"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "reasoning".type` | `string` | Required | Must be "reasoning". |
| `payload.item.type = "reasoning".id` | `string \| null` | Optional |  |
| `payload.item.type = "reasoning".summary` | `string \| null` | Optional |  |
| `payload.item.type = "reasoning".text` | `string \| null` | Optional |  |
| `payload.item.type = "command_execution"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "command_execution".type` | `string` | Required | Must be "command_execution". |
| `payload.item.type = "command_execution".aggregated_output` | `string \| null` | Optional |  |
| `payload.item.type = "command_execution".command` | `string` | Optional |  |
| `payload.item.type = "command_execution".exit_code` | `integer \| null` | Optional |  |
| `payload.item.type = "command_execution".id` | `string \| null` | Optional |  |
| `payload.item.type = "command_execution".status` | `string \| null` | Optional |  |
| `payload.item.type = "file_change"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "file_change".type` | `string` | Required | Must be "file_change". |
| `payload.item.type = "file_change".changes` | `array<object> \| null` | Optional |  |
| `payload.item.type = "file_change".changes.[]` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "file_change".id` | `string \| null` | Optional |  |
| `payload.item.type = "file_change".status` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "mcp_tool_call".type` | `string` | Required | Must be "mcp_tool_call". |
| `payload.item.type = "mcp_tool_call".id` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call".server` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call".status` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call".tool` | `string \| null` | Optional |  |
| `payload.item.type = "web_search"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "web_search".type` | `string` | Required | Must be "web_search". |
| `payload.item.type = "web_search".id` | `string \| null` | Optional |  |
| `payload.item.type = "web_search".query` | `string \| null` | Optional |  |
| `payload.item.type = "todo_list"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "todo_list".type` | `string` | Required | Must be "todo_list". |
| `payload.item.type = "todo_list".id` | `string \| null` | Optional |  |
| `payload.item.type = "todo_list".items` | `array<object> \| null` | Optional |  |
| `payload.item.type = "todo_list".items.[]` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "error"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "error".type` | `string` | Required | Must be "error". |
| `payload.item.type = "error".id` | `string \| null` | Optional |  |
| `payload.item.type = "error".message` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-jsonl-item-updated"></a>

### item.updated

Supplies an update to an existing historical item.

**Example JSON**

```json
{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "item.updated",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "item.updated",
    "item": {
      "id": "command_example",
      "type": "command_execution",
      "command": "pytest -q",
      "status": "in_progress",
      "aggregated_output": "Running 12 tests..."
    }
  },
  "tools": ["Bash"],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "item.updated". |
| `payload.item` | `object` | Required | Matches exactly one variant below. |
| `payload.item.type = "agent_message"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "agent_message".type` | `string` | Required | Must be "agent_message". |
| `payload.item.type = "agent_message".id` | `string \| null` | Optional |  |
| `payload.item.type = "agent_message".text` | `string` | Optional |  |
| `payload.item.type = "reasoning"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "reasoning".type` | `string` | Required | Must be "reasoning". |
| `payload.item.type = "reasoning".id` | `string \| null` | Optional |  |
| `payload.item.type = "reasoning".summary` | `string \| null` | Optional |  |
| `payload.item.type = "reasoning".text` | `string \| null` | Optional |  |
| `payload.item.type = "command_execution"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "command_execution".type` | `string` | Required | Must be "command_execution". |
| `payload.item.type = "command_execution".aggregated_output` | `string \| null` | Optional |  |
| `payload.item.type = "command_execution".command` | `string` | Optional |  |
| `payload.item.type = "command_execution".exit_code` | `integer \| null` | Optional |  |
| `payload.item.type = "command_execution".id` | `string \| null` | Optional |  |
| `payload.item.type = "command_execution".status` | `string \| null` | Optional |  |
| `payload.item.type = "file_change"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "file_change".type` | `string` | Required | Must be "file_change". |
| `payload.item.type = "file_change".changes` | `array<object> \| null` | Optional |  |
| `payload.item.type = "file_change".changes.[]` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "file_change".id` | `string \| null` | Optional |  |
| `payload.item.type = "file_change".status` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "mcp_tool_call".type` | `string` | Required | Must be "mcp_tool_call". |
| `payload.item.type = "mcp_tool_call".id` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call".server` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call".status` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call".tool` | `string \| null` | Optional |  |
| `payload.item.type = "web_search"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "web_search".type` | `string` | Required | Must be "web_search". |
| `payload.item.type = "web_search".id` | `string \| null` | Optional |  |
| `payload.item.type = "web_search".query` | `string \| null` | Optional |  |
| `payload.item.type = "todo_list"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "todo_list".type` | `string` | Required | Must be "todo_list". |
| `payload.item.type = "todo_list".id` | `string \| null` | Optional |  |
| `payload.item.type = "todo_list".items` | `array<object> \| null` | Optional |  |
| `payload.item.type = "todo_list".items.[]` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "error"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "error".type` | `string` | Required | Must be "error". |
| `payload.item.type = "error".id` | `string \| null` | Optional |  |
| `payload.item.type = "error".message` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-jsonl-item-completed"></a>

### item.completed

Supplies a historical item's completed content or outcome.

**Example JSON**

```json
{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "item.completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "item.completed",
    "item": {
      "id": "command_example",
      "type": "command_execution",
      "command": "pytest -q",
      "status": "completed",
      "aggregated_output": "12 passed",
      "exit_code": 0
    }
  },
  "tools": ["Bash"],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "item.completed". |
| `payload.item` | `object` | Required | Matches exactly one variant below. |
| `payload.item.type = "agent_message"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "agent_message".type` | `string` | Required | Must be "agent_message". |
| `payload.item.type = "agent_message".id` | `string \| null` | Optional |  |
| `payload.item.type = "agent_message".text` | `string` | Optional |  |
| `payload.item.type = "reasoning"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "reasoning".type` | `string` | Required | Must be "reasoning". |
| `payload.item.type = "reasoning".id` | `string \| null` | Optional |  |
| `payload.item.type = "reasoning".summary` | `string \| null` | Optional |  |
| `payload.item.type = "reasoning".text` | `string \| null` | Optional |  |
| `payload.item.type = "command_execution"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "command_execution".type` | `string` | Required | Must be "command_execution". |
| `payload.item.type = "command_execution".aggregated_output` | `string \| null` | Optional |  |
| `payload.item.type = "command_execution".command` | `string` | Optional |  |
| `payload.item.type = "command_execution".exit_code` | `integer \| null` | Optional |  |
| `payload.item.type = "command_execution".id` | `string \| null` | Optional |  |
| `payload.item.type = "command_execution".status` | `string \| null` | Optional |  |
| `payload.item.type = "file_change"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "file_change".type` | `string` | Required | Must be "file_change". |
| `payload.item.type = "file_change".changes` | `array<object> \| null` | Optional |  |
| `payload.item.type = "file_change".changes.[]` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "file_change".id` | `string \| null` | Optional |  |
| `payload.item.type = "file_change".status` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "mcp_tool_call".type` | `string` | Required | Must be "mcp_tool_call". |
| `payload.item.type = "mcp_tool_call".id` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call".server` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call".status` | `string \| null` | Optional |  |
| `payload.item.type = "mcp_tool_call".tool` | `string \| null` | Optional |  |
| `payload.item.type = "web_search"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "web_search".type` | `string` | Required | Must be "web_search". |
| `payload.item.type = "web_search".id` | `string \| null` | Optional |  |
| `payload.item.type = "web_search".query` | `string \| null` | Optional |  |
| `payload.item.type = "todo_list"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "todo_list".type` | `string` | Required | Must be "todo_list". |
| `payload.item.type = "todo_list".id` | `string \| null` | Optional |  |
| `payload.item.type = "todo_list".items` | `array<object> \| null` | Optional |  |
| `payload.item.type = "todo_list".items.[]` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "error"` | `object` |  | Additional properties are allowed. |
| `payload.item.type = "error".type` | `string` | Required | Must be "error". |
| `payload.item.type = "error".id` | `string \| null` | Optional |  |
| `payload.item.type = "error".message` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-jsonl-turn-completed"></a>

### turn.completed

Reports successful historical turn completion and usage.

**Example JSON**

```json
{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "turn.completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "turn.completed",
    "usage": {
      "input_tokens": 1200,
      "output_tokens": 80,
      "cached_input_tokens": 0
    }
  },
  "tools": null,
  "tokens_info": {
    "input_tokens": 1200,
    "output_tokens": 80,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "num_turns": 0,
    "cost_usd": 0
  },
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "turn.completed". |
| `payload.usage` | `object \| null` | Optional | Additional properties are allowed. |
| `payload.usage.cache_write_input_tokens` | `integer` | Optional |  |
| `payload.usage.cached_input_tokens` | `integer` | Optional |  |
| `payload.usage.input_tokens` | `integer` | Optional |  |
| `payload.usage.output_tokens` | `integer` | Optional |  |
| `payload.usage.reasoning_output_tokens` | `integer` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-jsonl-turn-failed"></a>

### turn.failed

Reports a failed historical turn with its error.

**Example JSON**

```json
{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "turn.failed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "turn.failed",
    "error": {
      "message": "The model request timed out."
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "turn.failed". |
| `payload.error` | `object \| null` | Optional | Additional properties are allowed. |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

<a id="codex-jsonl-error"></a>

### error

Reports a historical native execution error.

**Example JSON**

```json
{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "error",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "error",
    "message": "The model request timed out."
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}
```

**Field specification**

| Field | Type | Presence | Details |
| --- | --- | --- | --- |
| `kind` | `string` | Required | Must be "codex". |
| `source` | `string` | Required | Must be "codex". |
| `record_format` | `string` | Required | Must be "codex_jsonl@1". |
| `record_type` | `string` | Required | Original record type within its format. |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.type` | `string` | Required | Must be "error". |
| `payload.message` | `string \| null` | Optional |  |
| `cost` | `integer \| null` | Required |  |
| `created_at` | `string` | Required | Format: date-time. |
| `duration` | `integer \| null` | Required |  |
| `feed_seq` | `integer` | Required | Position in the session feed and the stream's resume cursor. |
| `id` | `string` | Required | Unique identifier of the record. |
| `model` | `string \| null` | Required |  |
| `sandbox_id` | `string \| null` | Required | Sandbox that produced this record, when applicable. |
| `session_execution_id` | `string \| null` | Required | Execution that produced the record; null for session-scoped events. |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `stream_seq` | `integer` | Required | Position within the execution's stream. |
| `tokens_info` | `object \| null` | Required | Additional properties are not allowed. |
| `tokens_info.cache_creation_input_tokens` | `integer` | Optional |  |
| `tokens_info.cache_read_input_tokens` | `integer` | Optional |  |
| `tokens_info.cost_usd` | `number` | Optional |  |
| `tokens_info.input_tokens` | `integer` | Optional |  |
| `tokens_info.num_turns` | `integer` | Optional |  |
| `tokens_info.output_tokens` | `integer` | Optional |  |
| `tools` | `array<string> \| null` | Required |  |
| `tools.[]` | `string` |  |  |
| `turn_id` | `string \| null` | Required | Turn containing this record, when applicable. |

## Unknown records

A record with `kind: "unknown"` retains its original `source`, `record_format`, `record_type`, and JSON payload. This includes new native methods, new content variants, and payloads that the current typed schema cannot interpret. The additional Codex notifications above show this shape.

Keep unknown records in the ordered feed and advance your cursor past them even if your UI does not render them. Preserve unknown payload fields when storing or relaying events. Ignore unknown outer WebSocket frame types and unknown delta kinds.

For a consumer that renders tool activity, inspect the native message's content blocks or Codex item's type; an unrecognized block or item should not prevent reading the rest of the session.

---

# TypeScript SDK

> Start sessions, stream records, and invoke automations from TypeScript.

Source: https://www.ellipsis.dev/docs/api/typescript-sdk

## Install

```bash
npm install @ellipsis-dev/sdk
```

## Start a session

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const handle = await client.sessions.run({
  claude_code: { prompt: 'Run the tests and report failures.' },
  environment: 'api-environment',
  lifecycle: { interactive: false },
  budget: 3,
});
const session = await handle.wait({ timeoutMs: 900_000 });
console.log(session.lifecycle.status, session.lifecycle.last_execution_result?.completion_reason);
```

`run` returns a handle while work continues. `wait` polls until the session settles. A timeout leaves the session running.

Use `await client.sessions.handle(sessionId)` to attach to an existing session.

## Continue a conversation

Leave `lifecycle.interactive` enabled to accept messages:

```typescript
const conversation = await client.sessions.run({
  claude_code: { prompt: 'Investigate the failing validation test.' },
  environment: 'api-environment',
  budget: 5,
});
await conversation.wait();
await conversation.send('Add a regression test.', {
  idempotencyKey: 'add-test',
});
await conversation.wait();
await conversation.stop();
```

The same message key is accepted once per session. A message during an active turn waits for the next turn.

## Invoke an automation

```typescript
const { session } = await client.agents.run('test-repair', {
  prompt: 'Investigate the request validation tests.',
});
const run = await client.sessions.handle(session.id);
await run.wait();
```

For an automation with an input schema, pass `input` instead:

```typescript
await client.agents.run('classify-change', {
  input: { description: 'Reject expired reset tokens' },
});
```

## Stream a session

See [Session events](/docs/api/session-events) for every modeled event and complete JSON examples.

In Node.js, install `ws` and connect it to the stream adapter:

```typescript
import WebSocket from 'ws';
import { streamSession, type OpenSocket } from '@ellipsis-dev/sdk/stream';

const token = process.env.ELLIPSIS_API_TOKEN!;
const openSocket: OpenSocket = ({ sessionId, query }) => {
  const path = '/v1/sessions/' + encodeURIComponent(sessionId) + '/stream';
  const ws = new WebSocket('wss://api.ellipsis.dev' + path + '?' + query, {
    headers: { authorization: 'Bearer ' + token },
  });
  return {
    onOpen: (cb) => ws.on('open', cb),
    onMessage: (cb) => ws.on('message', (raw) => cb(raw.toString())),
    onClose: (cb) => ws.on('close', (code) => cb(code)),
    onError: (cb) => ws.on('error', (error) => cb(error)),
    close: () => ws.close(),
  };
};

const outcome = await streamSession({
  sessionId: handle.id,
  openSocket,
  onFrame: (frame) => console.log(frame.type),
});
console.log(outcome.type);
```

Pass the adapter's query unchanged. The SDK handles reconnects and resume cursors. Complete records persist; partial text deltas are live-only.

## Read records

```typescript
for await (const record of await client.sessions.records(handle.id)) {
  if (record.kind === 'platform') {
    console.log(record.record_type, record.payload);
  } else if (record.kind === 'claude_code') {
    console.log(record.payload);
  } else if (record.kind === 'codex' || record.kind === 'unknown') {
    console.log(record.record_format, record.payload);
  }
}
```

Native records preserve their original payloads. Handle unknown variants so new event types do not break your consumer.

## Pagination and errors

```typescript
import { APIError } from '@ellipsis-dev/sdk';

try {
  for await (const session of await client.sessions.list({ days: 7 })) {
    console.log(session.id, session.lifecycle.last_execution_result?.completion_reason);
  }
} catch (error) {
  if (!(error instanceof APIError)) throw error;
  console.error(error.status, error.code);
}
```

Manual pagination exposes `items`, `hasMore`, and `nextCursor`. API fields retain their wire names; SDK options use camelCase.

The client defaults to a 60-second request timeout and two retries for transport errors, `429`, `502`, `503`, and `504`. Configure `timeoutMs` and `maxRetries` when creating it.

---

# Budgets

> Budgets documentation.

Source: https://www.ellipsis.dev/docs/budgets

TODO

---

# Harnesses

Source: https://www.ellipsis.dev/docs/harnesses

- [Claude Code](/docs/harnesses/claude): From Anthropic
  - [Codex](/docs/harnesses/codex): From OpenAI

---

# Ellipsis

> Spawn, manage, and govern coding agents in the cloud

Source: https://www.ellipsis.dev/docs

## Platform
  - [Sessions](/docs/sessions): Start tasks and follow up with your agent
  - [Environments](/docs/environments): Reuse repositories, dependencies, and secrets across sessions
  - [Automations](/docs/automations): Run saved tasks manually, on schedules, or from events
  - [Models](/docs/models): Choose a model and connect provider credentials
  - [Webhooks](/docs/webhooks): Configure session event notifications
  - [Secrets](/docs/secrets): Manage secrets for your environments
  - [Permissions](/docs/permissions): Limit the operations a session can perform
  - [Budgets](/docs/budgets): Set spending limits for sessions

## Harnesses
  - [Claude Code](/docs/harnesses/claude): Claude Code harness documentation
  - [Codex](/docs/harnesses/codex): Codex harness documentation

## Use cases
  - [Code review](/docs/code-review): Review pull requests as commits arrive

## Integrations
  - [GitHub](/docs/integrations/github): Connect repositories and trigger agents from GitHub
  - [Slack](/docs/integrations/slack): Work with agents in Slack threads
  - [Linear](/docs/integrations/linear): Give agents issue context and tasks in Linear
  - [Sentry](/docs/integrations/sentry): Investigate alerts with agents (not generally released)

## Reference
  - [API](/docs/api): Manage sessions, environments, automations, and reviews
  - [Python](/docs/api/python-sdk): Start sessions and stream their output
  - [TypeScript](/docs/api/typescript-sdk): Start sessions and stream their output
  - [CLI](https://github.com/ellipsis-dev/cli#readme): Run agents from your terminal

---

# Lifecycle

Source: https://www.ellipsis.dev/docs/lifecycle

A session can work through several instructions while keeping the same conversation and workspace. Its activity tells you what is happening now; its conversation state tells you whether it is permanently closed.

- **Follow progress.** See when a session is queued, starting, or working.
- **Continue the task.** Send follow-ups while the conversation remains open and permits replies.
- **Check the outcome.** Distinguish finished work, failures, and a permanently closed session.

## Start

```python
import os
from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
handle = client.sessions.run(
    environment="cloud_agent_environment",
    claude_code={"prompt": "Run the tests in api-repo and report failures."},
)
print(handle.id, handle.session.lifecycle.status)
```

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const handle = await client.sessions.run({
  environment: 'cloud_agent_environment',
  claude_code: { prompt: 'Run the tests in api-repo and report failures.' },
});
console.log(handle.id, handle.session.lifecycle.status);
```

Set up the [Python](/docs/api/python-sdk) or [TypeScript](/docs/api/typescript-sdk) SDK and an [API token](/docs/api/authentication), then replace the environment and repository names. `scheduled` means the task is queued; `starting` means Ellipsis is preparing or resuming its workspace. [Environment hooks](/docs/environments#setup-and-hooks) prepare dependencies and services before the agent works. A prepared workspace can skip build steps, while `before_start` runs on each start or resume.

## Work

```python
session = handle.refresh()
print(session.lifecycle.status)
print(session.lifecycle.conversation)
```

```typescript
const session = await handle.refresh();
console.log(session.lifecycle.status);
console.log(session.lifecycle.conversation);
```

`working` means the agent is processing an instruction; `waiting` means it is ready for input before pausing. `idle` means work is paused, with the conversation and workspace retained for a later message. A [`turn_completed`](/docs/api/session-events#turn_completed) event marks the end of one turn, not necessarily the whole session. Closing your browser or disconnecting your client does not stop the agent.

## Continue

```python
session = handle.refresh()
if session.lifecycle.prompting.enabled:
    handle.send(
        "Fix the first failing test and run it again.",
        idempotency_key="fix-first-failure-1",
    )
else:
    print(session.lifecycle.prompting.detail)
```

```typescript
const session = await handle.refresh();
if (session.lifecycle.prompting.enabled) {
  await handle.send('Fix the first failing test and run it again.', {
    idempotencyKey: 'fix-first-failure-1',
  });
} else {
  console.log(session.lifecycle.prompting.detail);
}
```

A follow-up resumes an idle conversation with the same session ID and workspace changes; reuse its message key only when retrying that send. Check `prompting.enabled` for direct-message availability, and reply to mention-started sessions in their original GitHub, Slack, or Linear thread. Sessions keep their original provider account, so connecting another subscription affects new sessions; reconnect the original account if it becomes unavailable. Codex can refresh credentials for that same account, but replacing a Claude subscription token requires a new session.

## Finish or recover

```python
session = handle.wait(timeout=900)
state = session.lifecycle
print(state.status, state.conversation)
if state.last_execution_result is not None:
    print(state.last_execution_result.completion_reason)
    print(state.last_execution_result.detail)
print(state.prompting.enabled, state.prompting.detail)
```

```typescript
const session = await handle.wait({ timeoutMs: 900_000 });
const state = session.lifecycle;
console.log(state.status, state.conversation);
if (state.last_execution_result) {
  console.log(state.last_execution_result.completion_reason);
  console.log(state.last_execution_result.detail);
}
console.log(state.prompting.enabled, state.prompting.detail);
```

`wait()` returns when work becomes idle or stops, including after failure; its timeout stops waiting, not the agent. Read `last_execution_result` for the last recorded outcome, which remains visible across resumes. A `failed`, `stopped`, or `cancelled` status can leave a conversation open, while `conversation: "closed"` permanently prevents follow-ups, including after a [one-shot task](/docs/sessions#one-shot-tasks). Transient failures before the agent acts may trigger bounded retries, reported by [`session_retrying`](/docs/api/session-events#session_retrying); check current state before starting replacement work.

## Follow the stream

```python
from ellipsis.frames import StreamFrame

def on_frame(frame: StreamFrame):
    if frame.type in ("snapshot", "session"):
        print(frame.session.lifecycle.status)
    elif frame.type == "records_append":
        for record in frame.records:
            print(record.feed_seq, record.kind)
    elif frame.type == "error":
        print(frame.message)
    elif frame.type == "done":
        print("Conversation closed")
```

```typescript
import type { StreamFrame } from '@ellipsis-dev/sdk/stream';

function onFrame(frame: StreamFrame) {
  if (frame.type === 'snapshot' || frame.type === 'session') {
    console.log(frame.session.lifecycle.status);
  } else if (frame.type === 'records_append') {
    for (const record of frame.records) {
      console.log(record.feed_seq, record.kind);
    }
  } else if (frame.type === 'error') {
    console.error(frame.message);
  } else if (frame.type === 'done') {
    console.log('Conversation closed');
  }
}
```

Pass this callback to the stream connection shown in the [Python](/docs/api/python-sdk#stream-a-session) or [TypeScript](/docs/api/typescript-sdk#stream-a-session) guide. `snapshot` supplies initial state, `session` updates it, and `done` marks a closed conversation. Complete records arrive through `records_append`, ordered by `feed_seq`; the SDK uses that cursor when reconnecting, while temporary `delta` output is live-only. Events can repeat or interleave, so use the [Session events reference](/docs/api/session-events) to handle their payloads and ignore unfamiliar event types.

---

# Models

> Choose a model, set defaults, and connect provider credentials.

Source: https://www.ellipsis.dev/docs/models

A harness runs the agent. A model handles its reasoning and tool calls. Select exactly one `claude_code` or `codex` block, and set its `model`.

```json
{
  "claude_code": {
    "model": "claude-opus-5",
    "prompt": "Find and fix the failing test."
  }
}
```

## Current support

`GET /v1/account/models` lists available models, their harnesses, capabilities, and token prices.

See [Harnesses](/docs/harnesses) for feature support and [Pricing](/docs/pricing#model-pricing) for the model list and token prices.

A configuration field can exist before that capability is available. Unsupported combinations return `unsupported_session_combination` before work starts.

## Defaults

Claude Code uses the account's default model when the request omits `claude_code.model`. Codex defaults to `gpt-5.6-terra`.

Always send exactly one `claude_code` or `codex` block. The key selects the harness; no `type` field is needed.

## Provider credentials

Platform-managed routes are available for the listed models.

A connected Claude Code subscription funds Anthropic models, and a connected Codex subscription funds OpenAI models on eligible sessions. Manage both under **Models > Subscriptions**. Each provider has its own connection, so adding Codex preserves your Claude subscription.

Choose **Add subscription**, select the provider, and supply its credentials:

- **Claude Code:** Run `claude setup-token` and paste the token.
- **Codex:** Run `codex -c cli_auth_credentials_store="file" login`, sign in with ChatGPT, and paste the contents of `~/.codex/auth.json` into the credential field. Treat this file as a password. Ellipsis stores it on the server and refreshes the login when needed.

Save and verify the connection before using it. Subscription eligibility depends on the session's account and attribution. A failed subscription request does not fall back to paid Ellipsis inference.

Custom Anthropic API keys and Bedrock routes are currently unavailable for session starts. A configured custom provider can prevent a session from starting unless an eligible Claude subscription takes precedence.

---

# Account settings

> Configure model defaults, spend limits, and record retention.

Source: https://www.ellipsis.dev/docs/organization

Account settings apply across sessions and automations. Owners and organization administrators manage financial settings with their user credentials. API keys and sandbox credentials cannot change those settings.

## Model and session defaults

| Setting | Effect |
| --- | --- |
| Default model | Used when a Claude Code session omits `claude_code.model` |
| Session budget ceiling | Rejects requests that ask for a larger session budget |

Changing the default model affects new sessions. Codex uses its own default model. There is no default environment.

## Spend limits

Open **Billing > Limits** to set account limits and optional developer limits.

Limits track actual Ellipsis credit usage over trailing 1-, 7-, and 28-day windows. Developer attribution includes user activity and API keys.

An automation or handler can set additional limits in `session.budget`. All applicable limits must have room before another paid request starts.

A limit is a threshold for new paid requests. Outstanding requests and sandbox teardown can add usage after it is reached. Lowering a limit can stop paid requests in sessions already running.

## Platform allowances

Open **API > Limits** to see your account's API request limits, storage quotas, concurrency limits, and spending ceilings. Each row shows its scope and current allowance. Custom allowances are marked **Custom**.

Every API request counts toward the account total. An endpoint limit adds a cap for that endpoint; endpoints without a separate cap share the account total. Your own budgets can impose lower spending limits than the platform allowances.

To request an increase, open **Help**, create a shared Slack channel with the Ellipsis team, and ask there. If you already have a shared channel, use it. These allowances are assigned by Ellipsis; customer credentials cannot raise them through the settings API.

## Budget alerts

Configure thresholds under **Billing > Limits**. Alerts appear under **Settings > Alerts**, with notification delivery controlled by the account's settings.

Use `GET /v1/account/budget` to inspect current limits and remaining spend.

## Retention

See [Security](/docs/security#data-retention) for session retention limits and the data deletion SLA. Export records you need before their TTL expires.

## Shared configuration

A GitHub repository named `.ellipsis` holds organization-wide configuration. Its root is the configuration directory:

```text
.ellipsis/
  automations/nightly-tests.yaml
  environments/api-environment.yaml
  github.yaml
  slack.yaml
  linear.yaml
  sentry.yaml
  code_review.yaml
```

Here `.ellipsis` is the repository name. Ordinary repositories store configuration inside a directory named `.ellipsis/`.

Each integration file defines exactly one responder: its name and identity under `ellipsis`, its filters under `github`, `slack`, `linear`, or `sentry`, and its execution settings under `session`. Multiple integration files for the same platform are not supported. Handlers support the same per-session and trailing budgets as automations; automation output schemas are not supported. Automations and environments keep their own document formats.

## Credits and billing

See [Pricing](/docs/pricing) for credits, compute charges, and automatic recharge.

---

# Permissions

> Limit the GitHub and Ellipsis operations a session can perform.

Source: https://www.ellipsis.dev/docs/permissions

Session permissions constrain credentials issued to the sandbox. Repository selection and stored secrets are configured separately in the [environment](/docs/environments).

## Read-only GitHub access

```yaml fragment
session:
  claude_code: {}
  permissions:
    github:
      repositories: [api-repo]
      permissions: read_only
```

The agent can read `api-repo` but cannot push commits or write issue and pull request comments. Local edits inside the sandbox are still possible.

## Allow code and pull request changes

```yaml fragment
session:
  claude_code: {}
  permissions:
    github:
      repositories: [api-repo]
      permissions:
        contents: write
        pull_requests: write
        issues: read
```

Use this for tasks that push a branch and open a pull request. Permissions cannot exceed the GitHub App installation's access.

A GitHub repository list restricts credentials. `environment.repositories` controls what is cloned. Set both when you need both boundaries.

## Limit Ellipsis access

```yaml fragment
session:
  claude_code: {}
  permissions:
    ellipsis:
      sessions: read
      environments: read
      secrets: read
```

An explicit map denies unlisted resources. `read`, `write`, and `delete` are ordered levels; higher levels include lower ones. The sandbox credential's ceiling still applies.

Reading secrets returns names and metadata, never stored values.

## Secrets

A secret named in an environment is available to the process and its tools. GitHub permission restrictions do not restrict what that separate credential can access.

Keep secret values out of instructions, committed YAML, generated cached configuration, and script output. Session logs can contain what tools print.

## Code review

Code review uses its own [permissions](/docs/code-review/configuration#permissions). Ellipsis posts the final review; stage prompts should describe what to inspect.

---

# Pricing

> Understand credits, model usage, sandbox charges, and automatic recharge.

Source: https://www.ellipsis.dev/docs/pricing

Ellipsis uses prepaid credits. Model usage and sandbox compute draw from the account balance.

## What is charged

| Inference | Tokens (all accounts) | CPU + memory: personal | CPU + memory: organization |
| --- | --- | --- | --- |
| Ellipsis inference | Pay Ellipsis at the model's rate | Free | At cost |
| Claude subscription | Covered by your subscription; $0 to Ellipsis | Free | At cost |
| Codex subscription | Covered by your subscription; $0 to Ellipsis | Free | At cost |
| BYOK (Anthropic API key)* | Pay Anthropic; $0 to Ellipsis | Free | At cost |
| Amazon Bedrock* | Pay AWS; $0 to Ellipsis | Free | At cost |

*BYOK and Bedrock are currently unavailable for session starts.*

Personal accounts can use the owner's Claude Code or Codex subscription for matching models, including for automations. Organizations can use your subscription for web, CLI, user-authenticated API, and mention sessions linked to your GitHub user, but not cron, react, or organization API-key sessions.

Supported funding routes are listed on [Models](/docs/models).

Organization compute costs $0.141912 per CPU core-hour and $0.024192 per GiB-hour of memory, billed for allocated resources while the sandbox is running, including warm idle time.

## Model pricing

Ellipsis inference prices in USD per 1 million tokens, for both personal and organization accounts.

| Model | Input | Cached input | Output |
| --- | --- | --- | --- |
| Claude Fable 5.1 | $10.00 | $0.25 | $50.00 |
| Claude Fable 5 | $10.00 | $1.00 | $50.00 |
| Claude Opus 5 | $5.00 | $0.50 | $25.00 |
| Claude Opus 4.8 | $5.00 | $0.50 | $25.00 |
| Claude Opus 4.7 | $5.00 | $0.50 | $25.00 |
| Claude Opus 4.6 | $5.00 | $0.50 | $25.00 |
| Claude Sonnet 5 | $2.00 | $0.20 | $10.00 |
| Claude Sonnet 4.6 | $3.00 | $0.30 | $15.00 |
| Claude Haiku 4.5 | $1.00 | $0.10 | $5.00 |
| GPT-5.6 Sol | $2.00 | $0.20 | $10.00 |
| GPT-5.6 Terra | $2.00 | $0.20 | $12.00 |
| GPT-5.6 Luna | $0.20 | $0.02 | $1.20 |
| GLM-5.2 | $0.75 | $0.14 | $2.40 |
| MiniMax M3 | $0.28 | $0.056 | $1.10 |

Cache writes cost 1.25× input for Claude (5-minute) and GPT, or 2× input for Claude (1-hour). GLM and MiniMax cache writes use the input rate.

## Buy credits

Use **Billing > Credits** to purchase credits. A 10% platform fee applies to credit purchases before discounts, not to individual sessions.

Credits do not expire. Eligible new organizations receive $100 in signup credit; personal accounts receive none.

## Automatic recharge

Configure a balance threshold and recharge amount under **Billing > Credits**. A saved payment method alone does not enable automatic recharge.

Paid requests stop when the available balance or an applicable [spend limit](/docs/organization#spend-limits) is exhausted.

## Read usage

**Billing > Usage** separates model and compute usage. Each session also shows its own cost.

The usage API reports UTC calendar months. A rated value for subscription usage is an estimate of token value, not an Ellipsis credit charge.

---

# Quick start

> Run your first coding task in the cloud.

Source: https://www.ellipsis.dev/docs/quick-start

## Connect GitHub

[Install Ellipsis](https://app.ellipsis.dev/install), select the repositories agents may access, and complete setup.

## Run a task

On **Home**, click **Environment** or the current environment name below the prompt. Choose a saved environment, or use **Add repository...** to select your repository. See [Environments](/docs/environments) for dependency setup.

Describe your task, such as adding a test for an empty request body and running it.

Keep the selected model or click its name to choose another. Click **New session**. The agent keeps working if you close the page.

## Continue the conversation

Read the result. To request changes or a pull request, type in **Reply to the agent...** and click **Send**.

See [Sessions](/docs/sessions) for diffs, session controls, and API examples.

---

# Secrets

> Secrets documentation.

Source: https://www.ellipsis.dev/docs/secrets

TODO

---

# Security

> Data deletion SLAs, retention limits, and controls for repository and secret access.

Source: https://www.ellipsis.dev/docs/security

Ellipsis deletes data **within 4 hours after its time to live (TTL) expires**.

## Data retention

| Data | Retention limit |
| --- | --- |
| Session data | Customer-configured TTL from 0 hours to 1 year |
| Other retained operational data, including webhook payloads | Maximum TTL of 3 days |

A TTL of 0 hours adds no retention window. The 4-hour deletion SLA still applies.

For example, data that expires at 12:00 UTC must be deleted by 16:00 UTC. Export any records you need before their TTL expires.

## GitHub access

[Select which repositories the GitHub App can access](/docs/integrations/github#repository-access), then restrict the credentials issued to each session:

- [Read-only GitHub access](/docs/permissions#read-only-github-access) prevents pushes and issue or pull request comments. Local sandbox edits remain possible
- [Explicit GitHub permissions](/docs/permissions#allow-code-and-pull-request-changes) grant only the operations a task needs
- [Environment repositories](/docs/environments/schema#fields) select what is cloned. Credential permissions separately control repository access

Code review has its own [permission restrictions](/docs/code-review/configuration#permissions). Ellipsis posts the final review separately from the stage agents.

## Secrets

Store credentials as [secrets](/docs/environments/schema#stored-secrets) and reference only those a session needs. Stored values cannot be read back through the dashboard or API.

Processes and tools can read credentials injected into their environment. GitHub read-only permissions do not restrict those separate credentials. Keep secrets out of prompts, committed YAML, cached configuration, and tool output; session logs can contain what tools print.

## API access and webhooks

Keep [API keys](/docs/api/authentication) on your server. [Limit Ellipsis permissions](/docs/permissions#limit-ellipsis-access) on credentials issued to sessions.

Verify webhook signatures before accepting events. Check the signature against the raw request body and reject stale timestamps.

## Contact

For security questions or deletion requests, [contact Support](/docs/support#get-help). Do not include secret values.

---

# Sessions

> Run coding tasks in parallel, keep work going when you disconnect, and return to the same conversation and workspace.

Source: https://www.ellipsis.dev/docs/sessions

A session is a conversation with a coding agent in its own cloud workspace. Give it a task, follow its progress, and inspect the changes. Ellipsis runs [Claude Code and Codex](/docs/harnesses) with your repositories and tools.

- **Work in parallel.** Run tasks in separate cloud workspaces.
- **Reuse your setup.** Share [environments](/docs/environments) with repositories, dependencies, and secrets.
- **Leave work running.** Agents keep working when you disconnect.
- **Continue later.** Resume an open session with its conversation and changes intact.
- **Inspect the work.** Read tool calls, review diffs, and download session history.
- **Set limits.** Scope [permissions](/docs/permissions), cap spending, and track costs.

## Start a session

```python
import os
from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
handle = client.sessions.run(
    environment="cloud_agent_environment",
    budget=5,
    claude_code={
        "prompt": "Add an empty-body test in api-repo. Run it; do not commit."
    },
)
print(handle.id)
```

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const handle = await client.sessions.run({
  environment: 'cloud_agent_environment',
  budget: 5,
  claude_code: {
    prompt:
      'Add an empty-body test in api-repo. Run it; do not commit.',
  },
});
console.log(handle.id);
```

This starts a test-writing task with a $5 spending cap; keep the session ID to retrieve its progress and results. Set up the [Python](/docs/api/python-sdk) or [TypeScript](/docs/api/typescript-sdk) SDK and an [API token](/docs/api/authentication), then replace `cloud_agent_environment` and `api-repo` with your environment and repository. Omitting `environment` uses a basic sandbox, not an account default. In the web app, select **New session** and describe your task; see the [quick start](/docs/quick-start).

## Follow the work

```python
session = handle.wait(timeout=900)
print(session.lifecycle.status, session.lifecycle.last_execution_result)

for record in client.sessions.records(handle.id):
    print(record.kind, record.payload)
```

```typescript
const session = await handle.wait({ timeoutMs: 900_000 });
console.log(session.lifecycle.status, session.lifecycle.last_execution_result);

for await (const record of await client.sessions.records(handle.id)) {
  console.log(record.kind, record.payload);
}
```

`wait()` returns when the session becomes idle or stops, including after a failure. Check `last_execution_result` before treating the task as successful. A timeout stops your client from waiting; it does not stop the agent. For live messages and tool calls, use the web app or stream with [Python](/docs/api/python-sdk#stream-a-session) or [TypeScript](/docs/api/typescript-sdk#stream-a-session).

### Retrieve a session

```python
handle = client.sessions.handle("your-session-id")
print(handle.session.lifecycle.status)
```

```typescript
const handle = await client.sessions.handle('your-session-id');
console.log(handle.session.lifecycle.status);
```

Retrieve an existing session by ID after restarting your application or disconnecting. You do not need to keep the original handle alive.

## Conversations

```python
handle.send(
    "Add a test for an invalid content type too.",
    idempotency_key="request-validation-followup-1",
)
session = handle.wait(timeout=900)
print(session.lifecycle.last_execution_result)
```

```typescript
await handle.send('Add a test for an invalid content type too.', {
  idempotencyKey: 'request-validation-followup-1',
});
const session = await handle.wait({ timeoutMs: 900_000 });
console.log(session.lifecycle.last_execution_result);
```

Send another instruction to an open interactive session, keeping its conversation and workspace changes across pauses and resumes. Reuse the message key only when retrying the same send to avoid duplicate instructions. Sessions started by a mention take replies in their original GitHub, Slack, or Linear thread. A closed session cannot resume; see [Lifecycle](/docs/lifecycle).

## One-shot tasks

<span id="from-scripts" />

```python
task = client.sessions.run(
    environment="cloud_agent_environment",
    claude_code={
        "prompt": "Run request-validation tests in api-repo and report failures."
    },
    lifecycle={"interactive": False},
)
result = task.wait(timeout=900)
print(task.id, result.lifecycle.last_execution_result)
```

```typescript
const task = await client.sessions.run({
  environment: 'cloud_agent_environment',
  claude_code: {
    prompt:
      'Run request-validation tests in api-repo and report failures.',
  },
  lifecycle: { interactive: false },
});
const result = await task.wait({ timeoutMs: 900_000 });
console.log(task.id, result.lifecycle.last_execution_result);
```

Set `lifecycle.interactive` to `false` for a task that needs no follow-up. The session closes after its first turn and deletes its sandbox. Records and captured results remain available. Use [Automations](/docs/automations) to save tasks and run them manually, on a schedule, or from events.

## Inspect the result

```python
diff = client.sessions.diff(handle.id)
for file in diff.files:
    print(file.full_name, file.path, file.patch)
print("Omitted paths:", diff.omitted_paths)

git = client.sessions.git(handle.id)
for repo in git.repos:
    print(repo.full_name, repo.commits, repo.prs)
```

```typescript
const diff = await client.sessions.diff(handle.id);
for (const file of diff.files) {
  console.log(file.full_name, file.path, file.patch);
}
console.log('Omitted paths:', diff.omitted_paths);

const git = await client.sessions.git(handle.id);
for (const repo of git.repos) {
  console.log(repo.full_name, repo.commits, repo.prs);
}
```

Review captured [uncommitted diffs](/docs/api/sessions/get-sessions-session_id-diff), [commits, and pull requests](/docs/api/sessions/get-sessions-session_id-git) alongside the conversation and tool output. Check `omitted_paths` for files excluded from the captured diff. An empty diff can mean there were no uncommitted changes or that no capture was available.

### Find sessions by handler

```python
for session in client.sessions.list(handler="your-handler-id"):
    print(session.id, session.lifecycle.status)
```

```typescript
for await (const session of await client.sessions.list({
  handler: 'your-handler-id',
})) {
  console.log(session.id, session.lifecycle.status);
}
```

Find work started by a particular integration handler, such as your Slack responder. Replace `your-handler-id` with an ID from [List handlers](/docs/api/handlers/get-handlers).

### Cost and records

```python
session = handle.refresh()
print("Cost (USD):", session.cost.total / 100_000)
print("Budget (USD):", session.budget)
```

```typescript
const session = await handle.refresh();
console.log('Cost (USD):', session.cost.total / 100_000);
console.log('Budget (USD):', session.budget);
```

Track accumulated cost against the session's spending cap. Follow-up messages share that cap. Divide `cost.total` by 100,000 for US dollars; `budget` is already in dollars. See [Pricing](/docs/pricing) for charges, or [download the session history](/docs/api/sessions/get-sessions-session_id-download).

## When a session stops

```python
session = handle.stop()
print(session.lifecycle)
```

```typescript
const session = await handle.stop();
console.log(session.lifecycle);
```

Use **Stop** in the web app or call `stop()` to halt active work. Disconnecting does not stop the agent. Stopping work does not permanently close an interactive conversation. Check [lifecycle state](/docs/lifecycle) before sending a follow-up; a closed session requires a new session.

---

# Support

> Contact Ellipsis and check service status.

Source: https://www.ellipsis.dev/docs/support

- [Schedule a demo](https://cal.com/ellipsis/demo)
- Connect shared Slack:
  1. Log into [app.ellipsis.dev](https://app.ellipsis.dev).
  2. Choose a GitHub account.
  3. Click "Help" on the sidebar.
  4. Enter your email.
- Email us: [team@ellipsis.dev](mailto:team@ellipsis.dev)
- [Platform status](https://status.ellipsis.dev)

---

# Triggers

> Run automations on schedules or matching events.

Source: https://www.ellipsis.dev/docs/triggers

An automation accepts one trigger. Omit `trigger` to run it only through the dashboard or API.

## Schedules

```yaml fragment
trigger:
  type: cron
  schedule: "0 9 * * 1-5"
```

Runs at 09:00 UTC on weekdays. Schedules also accept EventBridge `rate(...)`, `cron(...)`, and `at(...)` expressions.

```yaml fragment
trigger:
  type: cron
  schedule: "rate(6 hours)"
```

Each scheduled run starts a new one-shot session.

## Pull requests

```yaml fragment
trigger:
  type: react
  pull_request:
    on: [pushed]
    repositories: [api-repo]
    base: [main]
    draft: false
    paths: ["src/**", "tests/**"]
```

Runs when a non-draft pull request targeting `main` advances and changes a matching path. `pushed` also includes the initial head when a pull request opens.

| Event | When it fires |
| --- | --- |
| `opened` | Opened, reopened, or marked ready for review |
| `pushed` | Any head advance, including opening |
| `merged` | Merged |
| `closed` | Closed without merging |
| `review_submitted` | A review is submitted |
| `commented` | A comment is added |

## Branch pushes

```yaml fragment
trigger:
  type: react
  push:
    repositories: [api-repo]
    branch: [default, "release/*"]
    paths: ["package.json", "package-lock.json"]
```

Runs on matching pushes to the default branch or a `release/` branch. A push trigger has no `on` field.

## Issues

```yaml fragment
trigger:
  type: react
  issue:
    on: [opened]
    repositories: [api-repo]
    labels: [bug]
```

Runs when a new issue has a matching label.

## Repositories and authors

```yaml fragment
trigger:
  type: react
  pull_request:
    on: [opened]
    repositories:
      include: [api-repo, web-repo]
      exclude: [archived-repo]
    for:
      users: true
      bots: false
```

Repository and author filters control which events match. They do not grant access or select sandbox repositories.

- Empty repository inclusion matches every installed repository
- Branch filters accept exact names, prefixes ending in `*`, and `default`
- Labels match when any configured label is present
- Paths are include-only globs; negated patterns are rejected
- Every matching automation starts independently

## Other integrations

The schema also has `linear_issue`, `sentry`, and `slack_channel` surfaces. Their availability follows the connected integration and [model capabilities](/docs/models). `slack_channel` handles channel creation, not messages.

`@ellipsis` mentions use integration routing files, separate from automation triggers. See [GitHub](/docs/integrations/github), [Slack](/docs/integrations/slack), and [Linear](/docs/integrations/linear).

---

# Webhooks

> Webhooks documentation.

Source: https://www.ellipsis.dev/docs/webhooks

TODO

---

# Automations

> Save a task and its session settings, then invoke it or add a trigger.

Source: https://www.ellipsis.dev/docs/automations

An automation saves a prompt, a harness, an environment, permissions, and a budget. Each invocation starts a new session. A trigger makes it run automatically.

## Define an automation

```yaml title=".ellipsis/agents/test-repair.yaml"
ellipsis:
  kind: agent
  name: test-repair

session:
  claude_code:
    prompt: |
      Run the tests in api-repo. Fix one failing test without
      weakening its assertions. Run the affected tests again
      and open a pull request with the change and test results.
    model: claude-sonnet-5
  environment:
    repositories:
      - name: api-repo
    hooks:
      after_checkout: |
        cd /sandbox/api-repo
        npm ci
  budget:
    session: 5
```

This automation attempts a test repair and opens a pull request when it has a fix. It has no trigger, so it runs only when invoked.

## Deploy from git

Commit a `.yaml` or `.yml` file anywhere under `.ellipsis/` on the default branch. Ellipsis syncs it and shows it on the dashboard's **Automations** page.

The organization can also keep shared definitions in a repository named `.ellipsis`. That repository's root is the configuration directory.

Invalid updates keep the last valid definition running. Inspect the automation's page for the validation error and source commit. Deleting its file disables the synced automation.

## Create through the API

`POST /v1/agents` creates an automation immediately, without a repository file. Send the definition under `agent`, including `ellipsis.kind: agent`.

Each automation is managed by git or the API. Edit git-managed definitions in their repository. Use `link` to open a pull request that moves an API-managed definition into git; use `unlink` to make a git-managed definition editable through the API.

## Run an automation

Choose **Run** on its dashboard page, or invoke it with a prompt:

```bash
curl https://api.ellipsis.dev/v1/agents/test-repair/sessions \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Investigate the request validation tests."
}'
```

An automation with an input schema requires `input` instead of `prompt`. The optional request `budget` can lower the saved session budget.

Invocation runs once and closes the session after its first turn. Saved automation invocation currently supports Claude Code.

## Add a trigger

```yaml fragment
trigger:
  type: cron
  schedule: '0 9 * * 1'
```

This runs every Monday at 09:00 UTC. An automation accepts at most one trigger.

Use [Triggers](/docs/triggers) for event filters and schedules, or [Automation schema reference](/docs/automations/schema) for complete examples.

## Handlers

Handlers configure responses to [Slack](/docs/integrations/slack), [GitHub](/docs/integrations/github), or [Linear](/docs/integrations/linear) mentions, and investigations of [Sentry](/docs/integrations/sentry) alerts. Each account has at most one handler per service, defined by `slack.yaml`, `github.yaml`, `linear.yaml`, or `sentry.yaml` at the root of its `.ellipsis` repository. Each file defines service filters and one `session` block with its harness, prompt, environment, permissions, skills, and budget.

Handlers support the same [budget fields](/docs/automations/schema#budgets) as automations: `session` caps one session, while `day`, `week`, and `month` cap spend across that handler's sessions.

Open **Handlers** in the dashboard sidebar to see all synced handlers in a table. Select a handler to browse its source file, sync status, documentation, session counts, cost, and sessions. The time range applies to both metrics and the session list.

```bash
curl https://api.ellipsis.dev/v1/handlers \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

The response's `handlers` array contains each synced handler's ID, service, parsed configuration, original YAML, source file, and sync status. Disabled handlers are included. A failed update returns the last valid definition with `last_sync_error`; a file with no successfully synced definition is omitted. Edit handlers in GitHub.

Use the handler ID to [find the sessions it started](/docs/sessions#find-sessions-by-handler).

Read a handler's metrics with `GET /v1/handlers/{handler_id}/metrics`. Optional `start` and `end` timestamps select sessions by creation time, including `start` and excluding `end`. The response includes counts by current session status and total cost in millicents. Older sessions without that saved handler ID are excluded.

---

# Automation schema reference

> Complete automation examples, typed inputs and outputs, and field reference.

Source: https://www.ellipsis.dev/docs/automations/schema

For an introduction and setup instructions, see [Automations](/docs/automations).

An automation has four top-level blocks: `ellipsis`, optional `trigger`, optional `input`, and `session`. Set `ellipsis.kind` to `agent`. Unknown fields fail validation.

## Scheduled test checks

```yaml title=".ellipsis/agents/nightly-tests.yaml"
ellipsis:
  kind: agent
  name: nightly-tests
  description: Check the API test suite every night

trigger:
  type: cron
  schedule: '0 2 * * *'

session:
  claude_code:
    prompt: |
      Run the tests in api-repo. Report failures with the test
      name and error. Do not modify code.
    model: claude-sonnet-5
  environment:
    repositories:
      - name: api-repo
    hooks:
      after_checkout: |
        cd /sandbox/api-repo
        npm ci
  permissions:
    github:
      permissions: read_only
  budget:
    session: 3
    day: 10
    week: 50
```

The session records test results each night at 02:00 UTC.

## React to a pull request

```yaml title=".ellipsis/agents/check-api-changes.yaml"
ellipsis:
  kind: agent
  name: check-api-changes

trigger:
  type: react
  pull_request:
    on: [pushed]
    repositories: [api-repo]
    paths: ['src/routes/**']
    draft: false

session:
  claude_code:
    prompt: |
      Check the changed API routes for missing test coverage.
      Add focused regression tests where needed, run them,
      and report the results.
  environment:
    repositories:
      - name: api-repo
    hooks:
      after_checkout: |
        cd /sandbox/api-repo
        npm ci
  budget:
    session: 5
```

A matching head update starts a session. Repository filters decide which events match; the environment decides which repositories are available.

## Typed input and output

```yaml title=".ellipsis/agents/classify-change.yaml"
ellipsis:
  kind: agent
  name: classify-change

input:
  json_schema:
    type: object
    properties:
      description:
        type: string
    required: [description]
    additionalProperties: false
  message: 'Classify this change: {{description}}'

session:
  claude_code:
    prompt: |
      Classify the requested change as bugfix, feature, or maintenance.
      Explain the classification in one sentence.
    model: claude-opus-5
  output:
    json_schema:
      type: object
      properties:
        category:
          type: string
          enum: [bugfix, feature, maintenance]
        reason:
          type: string
      required: [category, reason]
      additionalProperties: false
  budget:
    session: 1
```

Invoke with `{"input":{"description":"Reject expired reset tokens"}}`. Read the validated result from `GET /v1/sessions/{session_id}/output`.

Structured output is available with every supported Claude and OpenAI model. Use the model's matching harness (`claude_code` or `codex`); `GET /v1/account/models` lists each model's capabilities. An invocation cannot provide both `input` and `prompt`.

## Workflow prompt

Put the task in the selected harness's `prompt` string:

```yaml title=".ellipsis/agents/backend-task.yaml"
ellipsis:
  kind: agent
  name: backend-task

session:
  claude_code:
    prompt: |
      Read docs/engineering.md in api-repo and follow its conventions.
      Run the relevant tests before finishing.
  environment:
    repositories:
      - name: api-repo
  budget:
    session: 5
```

The prompt becomes user input. On an invocation with structured input or a triggering event, the initial message also includes that context.

## Codex skills

Declare a directory containing `SKILL.md` to give Codex a reusable procedure and its supporting files:

```yaml fragment
session:
  codex:
    prompt: Use the release-checks skill to review the release.
    model: gpt-5.6-terra
  skills:
    - path: skills/release-checks
      repository:
        name: api-repo
```

Codex receives the skill and can read its references or run its scripts. `SKILL.md` needs YAML frontmatter with a nonempty `description`; `name` defaults to the directory name and must fit 64 characters.

A skill uses the repository's checkout revision when that repository is in the session. Otherwise, `repository.ref` selects a revision, or the repository's default branch is used. A bare `path` uses the automation's source repository, falling back to the first session repository for inline configurations. Use an explicit repository for sessions without either.

Skills are resolved again when a session resumes. Missing files, inaccessible repositories, invalid metadata, and size-limit violations fail the session. Each skill allows up to 50 UTF-8 files, 64 KiB per file, and 512 KiB total. A session can declare up to 10 skills.

## Identity and triggers

| Field                  | Meaning                                                |
| ---------------------- | ------------------------------------------------------ |
| `ellipsis.name`        | Automation name, unique within the account             |
| `ellipsis.description` | Description shown in the dashboard                     |
| `ellipsis.enabled`     | Whether the definition is active                       |
| `ellipsis.metadata`    | `labels` and `annotations` for your own metadata       |
| `trigger`              | One cron or react trigger; omit for on-demand work     |
| `input.json_schema`    | Schema required of the invocation's `input`            |
| `input.message`        | Initial-message template; omit to render input as JSON |

In a template, `{{field}}` reads the caller's input. Triggered work can reference event fields with `{{field}}`. References must exist in the declared input or trigger schema.

## Session settings

| Field                                                  | Meaning                                               |
| ------------------------------------------------------ | ----------------------------------------------------- |
| `session.claude_code` or `session.codex` | Exactly one harness block |
| `session.claude_code.model`                                | Model ID; Claude Code inherits the account default    |
| `session.claude_code.prompt` or `session.codex.prompt` | The task, as a string |
| `session.environment`                                  | Saved environment name or inline environment          |
| `session.permissions`                                  | GitHub and Ellipsis access grants                     |
| `session.budget`                                       | Per-session and trailing automation spend limits      |
| `session.output.json_schema`                           | Schema for the final JSON result                      |
| `session.skills`                                       | Repository skill references for Codex                 |
| `session.claude_code.settings`, `effort`, `fallback_model`, `max_turns` | Supported Claude Code options |

See [Models](/docs/models), [Environment schema reference](/docs/environments/schema), and [Permissions](/docs/permissions).

## Budgets

```yaml fragment
session:
  claude_code: {}
  budget:
    session: 5
    day: 20
    week: 100
    month: 300
```

Values are US dollars. `day`, `week`, and `month` cover trailing 1-, 7-, and 28-day windows. They measure this automation's spend.

Handlers use the same `session.budget` fields in `slack.yaml`, `github.yaml`, `linear.yaml`, and `sentry.yaml`. A handler's trailing limits measure spend across all its sessions, including sessions started from earlier revisions of that handler. Each handler has its own limits. An omitted trailing limit inherits the same platform ceiling as an automation.

Account and developer limits also apply. Limits stop new paid requests; in-flight requests and sandbox teardown can add usage after a threshold is reached.

---

# Environments

> Prepare repositories, dependencies, and secrets once, then reuse them across sessions.

Source: https://www.ellipsis.dev/docs/environments

An environment config defines a VM's repositories, installed dependencies, environment variables, hooks, and compute.

The **Environments** page has four tabs:

- **Env configs** lists the definitions you select when starting sessions.
- **VMs** lists each machine once, including machines reused across session resumes. Open a VM to see its last recorded state, resources, repositories, and session.
- **VM images** lists reusable snapshots of prepared environments, including their repository revisions and expiration dates. Images save build work when a new VM starts.
- **Secrets** manages the variables available to your environments.

Use `GET /v1/vms` and `GET /v1/vms/{vm_id}` to inspect machines, or `GET /v1/vm-images` and `GET /v1/vm-images/{image_id}` to inspect image metadata. Both lists accept `limit` and `offset` and return `next_offset` when another page exists.

## Define an environment

Commit this file on the repository's default branch:

```yaml title=".ellipsis/environments/api-environment.yaml"
ellipsis:
  kind: environment
  name: api-environment

repositories:
  - name: api-repo

hooks:
  build_base:
    inputs:
      - api-repo/package.json
      - api-repo/package-lock.json
    run: |
      cd /sandbox/api-repo
      npm ci
  after_checkout: |
    cd /sandbox/api-repo
    npm run build --if-present

compute:
  cpu: 2
  memory: 8GB
  timeout: 30m
```

Sessions using `api-environment` start with `api-repo` checked out and its npm dependencies installed.

You can also create an environment in the dashboard or with `POST /v1/environments`. The API accepts the same definition as JSON under `environment`.

## Use an environment

Select it in **New session**, or name it in a session request:

```json
{
  "environment": "api-environment",
  "claude_code": {
    "prompt": "Run the tests and fix one failure."
  }
}
```

An automation references it in `session.environment`:

```yaml fragment
session:
  claude_code: {}
  environment: api-environment
```

A missing environment name fails at start. Omitting an environment uses the basic sandbox; there is no account default environment.

## Setup and hooks

| Setting                | Runs                                                                                 | Use for                                       |
| ---------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------- |
| `hooks.build_base`     | When the reusable base is missing or its inputs change                               | Installing dependencies and system tools      |
| `hooks.after_checkout` | After Ellipsis checks out the requested revision, before saving the prepared sandbox | Compiling, generating code, starting services |
| `hooks.before_start`   | Before a session starts or resumes                                                   | Session-specific initialization               |

Scripts run as the sandbox user in `/sandbox`. Each script can be a string or an object with `run`. A nonzero exit fails the session. Each build script has a 10-minute limit; `before_start` has a 5-minute limit.

## Reuse cached dependencies

`build_base.inputs` lists exact files relative to `/sandbox`, including the repository name. Only those files are available during the base build. Their contents and file modes determine reuse, together with the script, toolchain, compute, and build configuration. Include every file the install reads, such as `.npmrc`, workspace package manifests, and installation scripts. Missing files and symlinks fail the build. Glob patterns are not supported.

Omitting `inputs` makes all source available and rebuilds the base when any source revision changes. An explicit `inputs: []` builds without repository files.

With the Node example above:

- Editing a TypeScript file restores the newest compatible prepared snapshot, updates its checkout to the new revision, and runs `after_checkout` before saving a new snapshot. If no compatible prepared snapshot exists, Ellipsis uses the dependency base.
- Changing the lockfile builds a new dependency base, then runs `after_checkout`.
- Starting another session on a prepared revision skips both build scripts. Only `before_start`, if configured, runs again.

Prepared snapshots are compatible when their repositories, build configuration, and dependency inputs match. Older snapshots are checked against the dependency inputs at their original revision. Ellipsis transfers only the Git objects needed to update an existing checkout and skips transferring repositories already at the requested revision. Without `build_base`, Ellipsis can reuse the newest prepared snapshot for the same repositories and configuration. Write `after_checkout` so it can run repeatedly with existing generated files and services: refresh outputs and restart or reconcile services as needed.

`before_start` runs when a session starts or resumes, not on every message or every Git checkout the agent performs. Its work adds to startup latency. Shell exports do not carry between scripts; declare shared values under `variables`.

A resumed session keeps its existing workspace, including uncommitted changes. Changes to build configuration apply when a new sandbox is prepared, or when you explicitly rebuild the session's sandbox.

To test a clean build, send `"force_rebuild": true` when starting a session. Inspect the environment log in the session.

Build snapshots retain files and running services. Start services in the background with their output redirected to files, or use `docker compose up -d --wait`, and verify readiness before the build script exits. Build output is private to your account; keep secrets out of generated files and logs.

Use `hooks.build_base` for system tools and dependencies, `hooks.after_checkout` for source preparation, and `hooks.before_start` for session initialization. The `image` block is no longer accepted in new YAML or API requests. Existing stored environments are converted to hooks when read; update repository-managed YAML before syncing it again.

See [Environment schema reference](/docs/environments/schema) for multi-repository, secret, toolchain, and compute examples.

---

# Environment schema reference

> Complete environment examples and field reference.

Source: https://www.ellipsis.dev/docs/environments/schema

For an introduction and setup instructions, see [Environments](/docs/environments).

Environment files live under `.ellipsis/` on the default branch. Set `ellipsis.kind: environment` and give the environment a unique name.

## Node.js project

```yaml title=".ellipsis/environments/web-environment.yaml"
ellipsis:
  kind: environment
  name: web-environment

repositories:
  - name: web-repo

hooks:
  build_base:
    inputs:
      - web-repo/package.json
      - web-repo/package-lock.json
    run: |
      cd /sandbox/web-repo
      npm ci
  after_checkout: |
    cd /sandbox/web-repo
    npm run build --if-present
  before_start: |
    cd /sandbox/web-repo
    test -d node_modules

compute:
  memory: 8GB
```

Dependencies are cached independently of TypeScript source. Compilation is cached for the requested source revision. Each session checks that the dependency directory exists before the agent starts or resumes.

## Python project

```yaml title=".ellipsis/environments/python-environment.yaml"
ellipsis:
  kind: environment
  name: python-environment

repositories:
  - name: api-repo

hooks:
  build_base:
    inputs: [api-repo/requirements.txt]
    run: |
      cd /sandbox/api-repo
      python -m venv .venv
      .venv/bin/pip install -r requirements.txt

variables:
  - name: PYTHONUNBUFFERED
    value: '1'

compute:
  cpu: 2
  memory: 8GB
  timeout: 45m
```

The agent can run `/sandbox/api-repo/.venv/bin/python` with the project's dependencies.

## Multiple repositories

```yaml title=".ellipsis/environments/full-stack-environment.yaml"
ellipsis:
  kind: environment
  name: full-stack-environment

repositories:
  - name: web-repo
    ref: main
  - name: api-repo
    ref: main

hooks:
  build_base:
    inputs:
      - web-repo/package.json
      - web-repo/package-lock.json
      - api-repo/requirements.txt
    run: |
      (cd /sandbox/web-repo && npm ci)
      (cd /sandbox/api-repo && python -m venv .venv)
      /sandbox/api-repo/.venv/bin/pip install -r /sandbox/api-repo/requirements.txt

compute:
  cpu: 4
  memory: 16GB
```

Both repositories are available under `/sandbox/`. A repository's `owner` defaults to the account; set it explicitly when needed.

## Stored secrets

Store `NPM_TOKEN` through **Environments > Secrets** or `PUT /v1/secrets`. Reference its name without putting the value in git.

```yaml title=".ellipsis/environments/private-packages.yaml"
ellipsis:
  kind: environment
  name: private-packages

repositories:
  - name: web-repo

variables:
  - name: NPM_TOKEN
  - name: NODE_ENV
    value: test

hooks:
  build_base:
    inputs: [web-repo/package.json, web-repo/package-lock.json, web-repo/.npmrc]
    run: |
      cd /sandbox/web-repo
      npm ci
```

This assumes the repository's npm configuration reads `NPM_TOKEN` from the environment. The secret is available to setup and the session. Do not write its value into a cached file.

A missing stored secret fails the session. Stored values cannot be read back through the dashboard or API.

## System tools

```yaml title=".ellipsis/environments/system-tools.yaml"
ellipsis:
  kind: environment
  name: system-tools

repositories:
  - name: api-repo

hooks:
  build_base:
    inputs: [api-repo/package.json, api-repo/package-lock.json]
    run: |
      sudo apt-get update
      sudo apt-get install -y jq
      cd /sandbox/api-repo
      npm ci
```

Install system tools in `build_base` using `sudo`. Ellipsis supplies the managed toolchain.

## MCP tools for Codex

Codex sessions can use connected Slack and Linear integrations, custom stdio servers, and remote streamable HTTP servers. Built-in integrations follow their inclusion settings; listing a name opts into an integration configured for explicit inclusion.

```yaml fragment
session:
  codex:
    model: gpt-5.6-terra
  environment:
    mcp_servers:
      - linear
      - name: internal-tools
        url: https://tools.example.com/mcp
        headers:
          Authorization: Bearer ${TOOLS_TOKEN}
```

The session receives Linear tools when the integration is connected and tools from your HTTP server. Replace the example URL with your server and store `TOOLS_TOKEN` in your account's secrets. `${NAME}` references resolve at session start; a missing secret fails the session.

For a server that runs inside the sandbox, replace `url` and `headers` with `command`, optional `args`, and optional `env`. Install its executable through `build_base`. An MCP server that cannot initialize fails the Codex turn.

## Fields

| Field                     | Values and behavior                                                                |
| ------------------------- | ---------------------------------------------------------------------------------- |
| `ellipsis.kind`           | Required `environment`                                                             |
| `ellipsis.name`           | Unique environment name                                                            |
| `repositories`            | List of `name`, optional `owner`, and optional `ref`                               |
| `variables`               | List of `name` and optional plaintext `value`; omit `value` to use a stored secret |
| `hooks.build_base`        | Script or `{run, inputs}`; builds the reusable dependency base                     |
| `hooks.build_base.inputs` | Exact repository-qualified files; omit for all source, or use `[]` for no source   |
| `hooks.after_checkout`    | Script or `{run}`; prepares the requested revision before saving its sandbox       |
| `hooks.before_start`      | Script or `{run}`; runs before a session starts or resumes                         |
| `compute.cpu`             | 2 to 32 vCPUs; default 2                                                           |
| `compute.memory`          | 4096MB to 64GB; default 4096MB                                                     |
| `compute.timeout`         | 60 seconds to 1 hour; default 1 hour                                               |
| `mcp_servers`             | Built-in names or custom stdio/HTTP servers for Codex                              |

See [Setup and hooks](/docs/environments#setup-and-hooks) for cache behavior, script limits, and migrating legacy hooks.

Memory accepts `MB` or `GB`. Timeout accepts `s`, `m`, and `h`, including combinations such as `1h30m`; the total must stay within the allowed range.

## Inline environments

Use the same fields directly in an automation's `session.environment`. Omit the environment's `ellipsis` block:

```yaml fragment
session:
  claude_code: {}
  environment:
    repositories:
      - name: api-repo
    hooks:
      build_base:
        inputs: [api-repo/package.json, api-repo/package-lock.json]
        run: |
          cd /sandbox/api-repo
          npm ci
    compute:
      memory: 8GB
```

---

# Claude

> Claude harness documentation.

Source: https://www.ellipsis.dev/docs/harnesses/claude

TODO

---

# Codex

> Codex harness documentation.

Source: https://www.ellipsis.dev/docs/harnesses/codex

TODO

---

# Budgets

> Allocate spend across review stages and limit repeated runs.

Source: https://www.ellipsis.dev/docs/code-review/budgets

Each review has a run budget, shared through stage allocations. Pipeline limits separately control trailing spend.

## Set a run budget

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: bounded-review

budget:
  run: 10
  day: 50
  week: 200
```

Values are US dollars. `run` applies to one review iteration. A later push starts a new iteration with a new allocation.

`day` and `week` measure this pipeline's trailing spend over one and seven days. They are checked before another review starts.

## Reserve a stage allocation

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: allocated-review

description: []

review:
  - name: correctness
    claude_code:
      prompt: |
        Find concrete bugs in the changed code and verify them.
      model: claude-opus-5
    budget: 6

filter:
  name: verification
  claude_code:
    prompt: |
      Keep only findings supported by a reproducible failure.
    model: claude-opus-5
  budget: 4

budget:
  run: 10
```

The reviewer receives $6 and the gatekeeper $4. Without an explicit stage budget, agents divide the remaining allocation.

Keep explicit stage allocations within the run budget and leave room for any stages that inherit an allocation.

## When limits are reached

A stage can stop before finishing. Ellipsis may post findings already produced with an incomplete-review warning. A posted review can advance coverage, so inspect that warning and rerun the full range when needed.

A trailing pipeline limit prevents another run until spend falls below the limit. Account and developer spend limits also apply.

Budget values constrain new paid requests. In-flight requests and compute charges can exceed the configured amount.

## Inspect cost

Open the review in the dashboard for total cost and per-stage usage. Review usage draws from the same credit balance as other sessions.

---

# Configuration YAML

> Configure review stages, environments, and permissions.

Source: https://www.ellipsis.dev/docs/code-review/configuration

Use `ellipsis.kind: code_review` in `code_review.yaml`. The file customizes a pipeline; the dashboard toggle enables reviews.

## Minimal configuration

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: repository-review
```

This uses the built-in description agent and bug reviewer.

## Stage behavior

| Field         | Shape                         | Default                        |
| ------------- | ----------------------------- | ------------------------------ |
| `pre_review`  | List of agents                | Empty                          |
| `description` | One agent or `[]`             | Pull request description agent |
| `review`      | List of agents, at most eight | One bug reviewer               |
| `filter`      | One agent or `[]`             | Empty                          |
| `post_review` | List of agents                | Empty                          |

Pre-review runs first. Description and review work follow. The gatekeeper filters findings before posting; post-review work follows the review.

An omitted stage inherits its default. A configured stage replaces the whole stage. An empty list disables it.

```yaml fragment code_review
description: []
filter: []
```

This leaves review enabled and disables description updates and filtering.

## Pull request descriptions

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: concise-descriptions

description:
  name: summarize-change
  claude_code:
    prompt: |
      Summarize the behavior changed by this pull request.
      Include the affected modules and tests run.
      Preserve human-written context outside the summary.
    model: claude-haiku-4-5-20251001
  budget: 2
```

The description stage updates Ellipsis's summary in the pull request body. Disabling it stops future updates without removing an existing summary.

## Pre-review filtering

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: relevance-check

pre_review:
  - name: generated-only
    claude_code:
      prompt: |
        Check whether every changed file is generated output.
        Cancel review only when all changes are generated.
        Continue if any source code, test, or configuration changed.
    budget: 1
```

A deliberate pre-review cancellation marks the range covered. Prefer path filters when a static rule is sufficient.

## Environment

```yaml fragment code_review
environment:
  variables:
    - name: NODE_ENV
      value: test
  hooks:
    after_checkout: |
      cd /sandbox/api-repo
      npm ci
  compute:
    cpu: 2
    memory: 8GB
```

Every stage receives the pipeline environment. A stage can override individual environment fields. The pull request repository is always cloned; add repositories only when the review needs more context.

Use [Environment schema reference](/docs/environments/schema) for the shared field definitions.

## Permissions

```yaml fragment code_review
permissions:
  github:
    permissions: read_only
```

Stage GitHub credentials are read-only for review work. Ellipsis posts comments and description updates separately. Reviews do not approve, request changes, merge pull requests, or push commits.

Pipeline permissions merge with stage permissions, subject to the review credential restrictions.

## Fields

| Field                                                          | Meaning                                                    |
| -------------------------------------------------------------- | ---------------------------------------------------------- |
| `ellipsis.kind`                                                | Required `code_review`                                     |
| `ellipsis.name`                                                | Name shown for the configuration                           |
| `ellipsis.enabled`                                             | Whether this file participates in configuration selection  |
| `pull_requests`                                                | Repository, branch, path, label, draft, and author filters |
| `environment`                                                  | Shared inline environment                                  |
| `permissions`                                                  | Shared GitHub and Ellipsis permissions                     |
| `pre_review`, `description`, `review`, `filter`, `post_review` | Stage agents                                               |
| `budget`                                                       | Run allocation and trailing pipeline limits                |

An agent accepts `name`, exactly one of `claude_code` or `codex`, and optional `environment`, `permissions`, and `budget`. Review-stage agents may add `pull_requests` filters.

`skills` is part of the schema but is currently unavailable for session starts. Review agents do not declare automation triggers or custom output schemas.

`environment`, `permissions`, and `budget` merge field by field with defaults. A repository's file does not merge with the organization's file.

See [Review scope](/docs/code-review/which-prs-get-reviewed), [Custom reviewers](/docs/code-review/custom-reviewers), and [Budgets](/docs/code-review/budgets).

---

# Custom reviewers

> Add focused reviewers, scope specialists, and filter findings.

Source: https://www.ellipsis.dev/docs/code-review/custom-reviewers

Each reviewer has a name and a harness block containing its prompt. Declaring `review` replaces the default reviewer, so include every reviewer you want to run.

## General review and a specialist

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: backend-review

description: []

review:
  - name: correctness
    claude_code:
      prompt: |
        Find reproducible defects in the changed code. Check callers,
        error handling, and tests. Report the failing input or state.
        Skip style and formatting.
      model: claude-opus-5

  - name: authorization
    claude_code:
      prompt: |
        Check authorization on changed request handlers. Trace the
        authenticated principal to each resource lookup. Report
        cases where one account can read or modify another's data.
      model: claude-opus-5

budget:
  run: 12
```

Both reviewers run against the same commit range. Their findings appear together in the posted review. Up to eight reviewers may run in parallel.

## Scope a specialist

```yaml fragment code_review
review:
  - name: migrations
    claude_code:
      prompt: |
        Check migration ordering, compatibility with the previous
        application version, and whether rollback preserves data.
        Report concrete failure cases.
      model: claude-opus-5
    pull_requests:
      paths: ['migrations/**']
```

This replaces the review stage with one migration specialist. It runs only when the pull request changes a matching path.

Reviewer filters accept `paths`, `base`, and `head`. A skipped reviewer uses no budget allocation.

## Add a gatekeeper

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: verified-findings

filter:
  name: verify-findings
  claude_code:
    prompt: |
      Verify each proposed finding against the code. Keep concrete
      defects with a reproducible failure. Reject style opinions
      and unsupported assumptions. Combine duplicate findings.
    model: claude-opus-5

budget:
  run: 12
```

This keeps the built-in reviewer and adds a pass before posting. The dashboard retains rejected findings and the gatekeeper's reason.

The gatekeeper needs its own instructions. `filter: []` disables it.

## Run project checks

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: tested-review

environment:
  hooks:
    after_checkout: |
      cd /sandbox/api-repo
      npm ci

review:
  - name: test-regressions
    claude_code:
      prompt: |
        Review the changed code for regressions. Run the relevant
        tests in api-repo. When reporting a failure, include the
        command and observed error.
      model: claude-opus-5

budget:
  run: 10
```

The pull request repository is cloned automatically. Environment setup installs dependencies before review starts.

## Write reviewer instructions

Name the defects to look for, the evidence required, and what to omit. Ellipsis supplies the commit range and handles posting. Do not ask stage agents to submit GitHub reviews themselves.

---

# Code Review

> Review new commits on pull requests with configurable coding agents.

Source: https://www.ellipsis.dev/docs/code-review

Ellipsis reviews pull requests as they change. Agents inspect the code and can run tests; Ellipsis posts the findings as a GitHub review.

## Enable reviews

1. Open **Reviews > Settings** in the dashboard
2. Enable code review
3. Open or push to a pull request in an installed repository

No YAML is required. The default pipeline runs one bug reviewer and a pull request description agent. It excludes Dependabot and Renovate by default.

Open the review in the dashboard to see its findings, covered commits, stage results, and cost.

## Review new commits

The first review covers the pull request's changes. Later reviews cover commits since the last covering review.

```text
base ── A ── B ── C
        ↑         ↑
      review    next review

First review: base...A
Next review:  A...C
```

A review that fails before posting leaves its changes pending for a later review. Details: [Review scope](/docs/code-review/which-prs-get-reviewed).

## Customize the pipeline

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: api-review

description: []

budget:
  run: 8
```

This keeps the default reviewer, disables description updates, and sets the per-run budget allocation to $8.

- [Review scope](/docs/code-review/which-prs-get-reviewed): repositories, branches, paths, and authors
- [Custom reviewers](/docs/code-review/custom-reviewers): specialist reviewers and a gatekeeper
- [Configuration YAML](/docs/code-review/configuration): stages, environments, and permissions
- [Budgets](/docs/code-review/budgets): stage allocation and trailing limits

## Run through the API

```json
{
  "owner": "your-org",
  "repo": "api-repo",
  "pull_request_number": 42,
  "post": false
}
```

Send to `POST /v1/reviews` to inspect findings without posting to GitHub. The same repository configuration applies.

---

# Review scope

> Choose repositories, branches, authors, and changed paths.

Source: https://www.ellipsis.dev/docs/code-review/which-prs-get-reviewed

The file's location determines which repositories it governs.

## Configuration precedence

| File | Scope |
| --- | --- |
| `.ellipsis/code_review.yaml` in an ordinary repository | That repository |
| `code_review.yaml` at the root of the organization's `.ellipsis` repository | Repositories without their own active configuration |
| No active configuration | Built-in defaults |

A repository's file replaces the organization file. Its settings then overlay the built-in defaults.

Files become live from the default branch. An invalid or disabled file falls through to the next configuration; it does not disable reviews. Use filters to exclude work.

## Select repositories

Use `repositories` only in the organization-wide file:

```yaml title="code_review.yaml"
ellipsis:
  kind: code_review
  name: organization-review

pull_requests:
  repositories:
    include: [api-repo, web-repo]
  draft: false
```

Only matching non-draft pull requests in those repositories are reviewed, unless a repository defines its own pipeline.

An exclusion-only filter watches every repository except those listed:

```yaml fragment code_review
pull_requests:
  repositories:
    exclude: [archived-repo]
```

A repository-local file cannot declare `pull_requests.repositories`.

## Filter branches and paths

```yaml title=".ellipsis/code_review.yaml"
ellipsis:
  kind: code_review
  name: api-changes

pull_requests:
  base: [main, "release/*"]
  paths: ["src/**", "migrations/**"]
  draft: false
```

This reviews non-draft pull requests targeting `main` or a `release/` branch when the change touches a listed path.

Branch filters accept exact names, trailing `*` prefixes, and `default`. Path filters are include-only globs over changed paths. Empty lists impose no restriction.

## Filter authors

```yaml fragment code_review
pull_requests:
  for:
    users: true
    bots:
      include: true
      exclude: ["dependabot[bot]", "renovate[bot]"]
```

Use GitHub logins, including `[bot]` when present. Set `bots: false` to exclude all bot-authored pull requests.

`labels` matches any listed label. A reviewer's own filters can further limit that stage; see [Custom reviewers](/docs/code-review/custom-reviewers#scope-a-specialist).

## Incremental coverage

The first review starts at the pull request base. Later reviews start at the last covered commit, called `watermark` in the API.

- A posted review advances coverage, including one with no findings
- A configured pre-review stage can deliberately skip a range and mark it covered
- A failed post leaves the range uncovered
- A posted incomplete review can advance coverage; inspect its warning before treating it as a complete check

Filtered or budget-blocked pushes remain uncovered until a later review runs.

## Request a full review

```json
{
  "owner": "your-org",
  "repo": "api-repo",
  "pull_request_number": 42,
  "scope": {"kind": "full"}
}
```

Send to `POST /v1/reviews`. Without `scope`, the request uses the current incremental range.

---

# GitHub

> Connect repositories and configure the responder for GitHub mentions.

Source: https://www.ellipsis.dev/docs/integrations/github

Install the Ellipsis GitHub App and select the repositories it may access. Change repository access through GitHub's installed-app settings.

## Repository access

An environment selects repositories to clone. Session permissions can further restrict its GitHub token.

- [Environment schema reference](/docs/environments/schema) configures checkouts
- [Permissions](/docs/permissions) controls reads and writes
- [Triggers](/docs/triggers) configures repository events
- [Code Review](/docs/code-review) configures automatic reviews

## Mentions

Mention `@ellipsis` on an issue or pull request to start or continue a conversation. With no routing file, the built-in responder handles the mention.

Put `github.yaml` at the root of the organization's `.ellipsis` repository:

```yaml title="github.yaml"
ellipsis:
  version: v1
  kind: github
  name: github-helper

github:
  repositories: [api-repo, web-repo]

session:
  claude_code:
    prompt: |
      Read the relevant code before answering. When asked for a
      fix, add a regression test and run it.
  budget:
    session: 5
```

Mentions in `api-repo` and `web-repo` use this responder. Other repositories use the built-in responder. Set `github.repositories: ["*"]` to use your responder in every repository; do not combine the wildcard with repository names.

The file defines exactly one responder. `ellipsis.name` names it, `github` selects the repositories it answers in, and `session` holds its harness, prompt, environment, permissions, skills, and budget. An environment can be a saved environment name or an inline definition. These settings use the same structure as [automation schema reference](/docs/automations/schema).

The default-branch version is live. Invalid edits retain the last successfully synced configuration. With `ellipsis.enabled: false`, mentions use the built-in responder. A copy in an ordinary repository does not configure organization mention routing.

## Who can mention Ellipsis

Add `github.mentions` to configure which authors can summon Ellipsis and whether a leading `...` or `…` counts as a mention:

```yaml title="github.yaml"
ellipsis:
  version: v1
  kind: github
  name: github-helper

github:
  repositories: ['*']
  mentions:
    for:
      public: { users: true, bots: false }
      private: { users: true, bots: false }
    allow_leading_ellipsis: true
    require_leading_mention: false

session:
  claude_code:
    prompt: Answer questions using the relevant code.
```

This configuration lets people summon Ellipsis in public and private repositories, ignores bot authors such as Dependabot and Renovate, and accepts a leading `...` or `…`. Each author and visibility combination is independent.

| Field under `github.mentions` | Default | Effect |
| --- | --- | --- |
| `for.public.users` | `true` | Human authors can summon Ellipsis in public repositories. |
| `for.private.users` | `true` | Human authors can summon Ellipsis in private repositories. |
| `for.public.bots` | `false` | Bot authors can summon Ellipsis in public repositories when enabled. |
| `for.private.bots` | `false` | Bot authors can summon Ellipsis in private repositories when enabled. |
| `allow_leading_ellipsis` | `true` | A comment starting with `...` or `…` can summon Ellipsis, subject to the author filters. |
| `require_leading_mention` | `false` | Require the mention at the start of the comment when enabled. |

The mention policy applies throughout the organization, including repositories answered by the built-in responder and when `ellipsis.enabled` is `false`. The repository filter selects your custom responder; it does not limit where the mention policy applies.

Omitted fields use the defaults above. Those defaults also apply when `github.mentions` or the entire file is absent. Edit mention settings in `github.yaml`; the dashboard shows the effective policy. Invalid YAML keeps the last successfully synced policy.

---

# Integrations

> Connect your tools.

Source: https://www.ellipsis.dev/docs/integrations

- [GitHub](/docs/integrations/github): Repositories and pull requests
  - [Slack](/docs/integrations/slack): Conversations and mentions
  - [Linear](/docs/integrations/linear): Issues and tasks
  - [Sentry](/docs/integrations/sentry): Alert investigations (limited availability)

---

# Linear

> Connect Linear and control access to issue context.

Source: https://www.ellipsis.dev/docs/integrations/linear

Connect a workspace from **Integrations > Linear** in the dashboard.

## Agent access

Agent sessions using Linear tools require a Codex model with MCP support. See [Models](/docs/models) and [MCP configuration](/docs/environments/schema#mcp-tools-for-codex).

The integration exposes connected teams and settings for configuration.

## Mention routing

Linear mentions use `linear.yaml` at the root of the organization's `.ellipsis` repository. The file defines one responder and selects the teams and projects it answers in.

```yaml title="linear.yaml"
ellipsis:
  version: v1
  kind: linear
  name: linear-helper

linear:
  teams: [ENG]
  projects: [Website]

session:
  codex:
    prompt: |
      Read the issue and relevant code before answering. When asked
      for a fix, implement it, run the tests, and open a pull request.
  environment:
    repositories:
      - name: api-repo
      - name: web-repo
  budget:
    session: 5
```

This responder answers mentions on issues belonging to the `ENG` team or the `Website` project. Other issues use the built-in responder.

| Field | Behavior |
| --- | --- |
| `linear.teams` | Team keys or names, such as `ENG` or `Engineering`. `['*']` matches every issue. |
| `linear.projects` | Project names. Wildcards are not supported here; use `linear.teams: ['*']` for every issue. |
| `session` | The responder's harness, prompt, environment, permissions, skills, and budget, in the same structure as [automation schema reference](/docs/automations/schema). |

Set at least one of `linear.teams` or `linear.projects`. Names match without regard to case. A team wildcard cannot be mixed with team names.

Linear issues have no GitHub repository of their own. `session.environment` must name the repositories the responder needs, or reference a saved environment containing those repositories.

The default-branch version is live. Invalid edits retain the last successfully synced configuration. Missing or disabled files and issues outside the configured filters use the built-in responder. A copy outside the organization's `.ellipsis` repository does not configure Linear.

## Issue events

The automation schema includes `trigger.linear_issue` for newly created issues. This is separate from mention routing and follows the same capability restrictions.

---

# Sentry

> Configure one investigator for Sentry alerts with sentry.yaml.

Source: https://www.ellipsis.dev/docs/integrations/sentry

Sentry can start an investigator when an issue alert fires or a metric alert enters critical status. Connecting Sentry, configuring its alert rules, and choosing an investigator are separate steps.

The Sentry integration is not generally released yet. If it is enabled for your organization, use the setup below. Contact [Support](/docs/support) for access.

## Connect and configure alerts

1. Connect Sentry from the Ellipsis integrations settings and complete the installation in your Sentry organization.
2. In Sentry, configure each project's issue or metric alert rule to notify the Ellipsis integration. Installing the integration alone does not send alerts.
3. Merge `sentry.yaml` at the root of your organization's `.ellipsis` repository. Ellipsis syncs it from the default branch.
4. Trigger a test alert from Sentry, then check that an Ellipsis session starts and delivers the requested report.

The installation and token credentials stay in the integration settings. `sentry.yaml` controls routing and investigator behavior; it does not install Sentry SDKs, create Sentry alert rules, or store credentials. Slack reports also require a connected Slack workspace and channel access.

## Route alerts

This example investigates every project in one Sentry organization and sends one short Slack report per alert. Each report identifies its project.

```yaml
ellipsis:
  version: v1
  kind: sentry
  name: Production error reports

sentry:
  organizations: [my-sentry-org]
  projects: ['*']
  on: [issue_alert, metric_alert]

session:
  codex:
    prompt: |
      Investigate the alert and send one report to #eng-ops, at most
      three short lines and 70 words. Include the project, Sentry link,
      impact, and next step. Link the causing PR only when supported by
      evidence. Tag its author only after verifying their Slack identity.
      If attribution is uncertain, say so. Do not open a fix PR.
    model: gpt-5.6-terra
  environment:
    repositories:
      - name: api-repo
    mcp_servers:
      - name: slack
  permissions:
    github:
      permissions: read_only
  budget:
    session: 2
```

The routing file supports these fields:

| Field | Behavior |
| --- | --- |
| `ellipsis.enabled` | Defaults to `true`. Set `false` to stop Sentry investigators. |
| `ellipsis.name` | The investigator's name. |
| `sentry.organizations` | Sentry organization slugs; defaults to `['*']`. |
| `sentry.projects` | Required, nonempty project slugs, or `['*']` for every project. |
| `sentry.on` | `issue_alert`, `metric_alert`, or both (the default). |
| `session.claude_code` or `session.codex`, `session.skills` | The investigator's model, instructions, and skills. |
| `session.environment`, `session.permissions` | The investigator's environment and credential permissions. An environment can be inline or reference a saved environment. |
| `session.budget.session` | Optional positive session budget in dollars. |
| `session.budget.day`, `week`, `month` | Spend limits across this handler's sessions over trailing 1-, 7-, and 28-day windows, in dollars. |

The file defines exactly one investigator. An alert must match its organization, project, and alert type. List several organizations or projects to use the same investigator for all of them. Do not mix `'*'` with names in the same list. An alert with an unknown project can only match a project wildcard. Unmatched alerts do not start a session.

A project called `backend` in one Sentry organization does not match a filter scoped to another organization. Session settings follow the same structure as [automation schema reference](/docs/automations/schema).

Skills and Claude Code settings without an explicit `repository` resolve from the `.ellipsis` repository. Qualify a reference with `repository` to read it from an application repository instead.

## Delivery and existing automations

When a live `sentry.yaml` exists, it controls all Sentry dispatch, including when disabled or when no route matches. Sentry-triggered automations (`trigger.sentry`) do not also run. Organizations without the file keep their existing automation behavior. Deleting the file restores that automation dispatch; use `ellipsis.enabled: false` when you want to stop investigations.

Invalid edits preserve the last successfully synced configuration and record a sync error. The file is only active at `sentry.yaml` in the `.ellipsis` repository; copies in application repositories are inert.

Issue alerts have a six-hour cooldown after an investigation starts. Metric alerts only start investigations on entry into `critical`, not on `warning` or `resolved`. Repeated deliveries are deduplicated. A live test alert is required to verify delivery across Sentry, Ellipsis, and Slack; a successful installation callback alone does not verify that path.

---

# Slack

> Connect Slack and configure workspace access.

Source: https://www.ellipsis.dev/docs/integrations/slack

Connect a workspace from **Integrations > Slack** in the dashboard. Invite Ellipsis to private channels it needs to access.

## Agent access

Agent sessions using Slack tools require a Codex model with MCP support. See [Models](/docs/models) and [MCP configuration](/docs/environments/schema#mcp-tools-for-codex).

The connection also supplies workspace channels and members for configuration. Choose the operations channel from the integration's dashboard settings.

## Mention routing

Slack mentions use `slack.yaml` at the root of the organization's `.ellipsis` repository. The file defines one responder and selects the channels and direct messages it answers.

```yaml title="slack.yaml"
ellipsis:
  version: v1
  kind: slack
  name: slack-helper

slack:
  channels: ['#engineering', '#support']
  direct_messages: ['*']

session:
  codex:
    prompt: |
      Read the code before answering. Cite the relevant files and
      functions, and keep replies short.
  environment:
    repositories:
      - name: api-repo
  permissions:
    github:
      permissions: read_only
  budget:
    session: 2
```

This responder answers mentions in `#engineering` and `#support`, plus all direct messages. Other channels use the built-in responder.

| Field | Behavior |
| --- | --- |
| `slack.channels` | Channel names, with or without `#`. `['*']` matches all channels. |
| `slack.direct_messages` | Linked GitHub logins, such as `['priya-shah']`. `['*']` matches all DM authors, including people without a linked GitHub account. |
| `session` | The responder's harness, prompt, environment, permissions, skills, and budget, in the same structure as [automation schema reference](/docs/automations/schema). An environment can also be a saved environment name. |

Set at least one of `slack.channels` or `slack.direct_messages`. Wildcards apply separately to channels and DMs and cannot be mixed with names in the same list. Channel names and GitHub logins match without regard to case.

The default-branch version is live. Invalid edits retain the last successfully synced configuration. Missing or disabled files and conversations outside the configured filters use the built-in responder. A copy outside the organization's `.ellipsis` repository does not configure Slack.

This routing is separate from a `slack_channel` automation trigger, which responds to channel creation rather than messages.

## Access changes

Removing the connection prevents future Slack access. Review the integration's agent access setting before granting tools broadly to sessions.

---

# Get budget

> Read account and developer spend limits and current usage.

Source: https://www.ellipsis.dev/docs/api/account/get-account-budget

## GET /v1/account/budget

Read account and developer spend limits and current usage.

Required permissions: read:account.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "alerts": {
    "absolute_thresholds": {
      "usd_1d": float,
      "usd_28d": float,
      "usd_7d": float
    },
    "percent_thresholds": [
      int
    ]
  },
  "as_of": str,
  "credit_balance_usd": float,
  "credit_exhausted": bool,
  "developer_limits": {
    "defaults": [
      {
        "limit_usd": float,
        "platform_max_usd": float,
        "window_days": int
      }
    ],
    "developers": [
      {
        "attribution_id": str,
        "attribution_type": str,
        "avatar_url": str,
        "developer_key": str,
        "login": str,
        "name": str,
        "windows": [
          {
            "exhausted": bool,
            "limit_usd": float,
            "override_usd": float,
            "remaining_usd": float,
            "spent_usd": float,
            "window_days": int
          }
        ]
      }
    ],
    "enabled": bool
  },
  "per_run": {
    "budget_usd": float,
    "ceiling_usd": float,
    "platform_max_usd": float
  },
  "policy": {
    "account": {
      "usd_1d": float,
      "usd_28d": float,
      "usd_7d": float
    },
    "default_session_usd": float,
    "developer_defaults": {
      "usd_1d": float,
      "usd_28d": float,
      "usd_7d": float
    },
    "developer_overrides": {
      "[str]": {
        "usd_1d": float,
        "usd_28d": float,
        "usd_7d": float
      }
    }
  },
  "windows": [
    {
      "exhausted": bool,
      "fraction_used": float,
      "limit_usd": float,
      "platform_max_usd": float,
      "remaining_usd": float,
      "spent_usd": float,
      "window_days": int
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.account.budget()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.account.budget();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/account/budget" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "alerts": {
      "additionalProperties": false,
      "properties": {
        "absolute_thresholds": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "usd_1d": {
                  "anyOf": [
                    {
                      "minimum": 1,
                      "multipleOf": 0.01,
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "usd_28d": {
                  "anyOf": [
                    {
                      "minimum": 1,
                      "multipleOf": 0.01,
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "usd_7d": {
                  "anyOf": [
                    {
                      "minimum": 1,
                      "multipleOf": 0.01,
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "percent_thresholds": {
          "items": {
            "maximum": 100,
            "minimum": 1,
            "type": "integer"
          },
          "maxItems": 100,
          "minItems": 1,
          "type": "array"
        }
      },
      "required": [
        "percent_thresholds",
        "absolute_thresholds"
      ],
      "type": "object"
    },
    "as_of": {
      "format": "date-time",
      "type": "string"
    },
    "credit_balance_usd": {
      "type": "number"
    },
    "credit_exhausted": {
      "type": "boolean"
    },
    "developer_limits": {
      "properties": {
        "defaults": {
          "items": {
            "properties": {
              "limit_usd": {
                "type": "number"
              },
              "platform_max_usd": {
                "type": "number"
              },
              "window_days": {
                "type": "integer"
              }
            },
            "required": [
              "window_days",
              "limit_usd",
              "platform_max_usd"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "developers": {
          "items": {
            "properties": {
              "attribution_id": {
                "type": "string"
              },
              "attribution_type": {
                "enum": [
                  "github_user",
                  "linear_user",
                  "slack_user",
                  "api_key"
                ],
                "type": "string"
              },
              "avatar_url": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "developer_key": {
                "type": "string"
              },
              "login": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "windows": {
                "items": {
                  "properties": {
                    "exhausted": {
                      "type": "boolean"
                    },
                    "limit_usd": {
                      "type": "object"
                    },
                    "override_usd": {
                      "type": "object"
                    },
                    "remaining_usd": {
                      "type": "object"
                    },
                    "spent_usd": {
                      "type": "number"
                    },
                    "window_days": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "window_days",
                    "spent_usd",
                    "limit_usd",
                    "override_usd",
                    "remaining_usd",
                    "exhausted"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "developer_key",
              "attribution_type",
              "attribution_id",
              "login",
              "avatar_url",
              "name",
              "windows"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "enabled": {
          "type": "boolean"
        }
      },
      "required": [
        "enabled",
        "defaults",
        "developers"
      ],
      "type": "object"
    },
    "per_run": {
      "properties": {
        "budget_usd": {
          "type": "number"
        },
        "ceiling_usd": {
          "type": "number"
        },
        "platform_max_usd": {
          "type": "number"
        }
      },
      "required": [
        "budget_usd",
        "platform_max_usd",
        "ceiling_usd"
      ],
      "type": "object"
    },
    "policy": {
      "additionalProperties": false,
      "properties": {
        "account": {
          "additionalProperties": false,
          "properties": {
            "usd_1d": {
              "minimum": 1,
              "multipleOf": 0.01,
              "type": "number"
            },
            "usd_28d": {
              "minimum": 1,
              "multipleOf": 0.01,
              "type": "number"
            },
            "usd_7d": {
              "minimum": 1,
              "multipleOf": 0.01,
              "type": "number"
            }
          },
          "required": [
            "usd_1d",
            "usd_7d",
            "usd_28d"
          ],
          "type": "object"
        },
        "default_session_usd": {
          "minimum": 1,
          "multipleOf": 0.01,
          "type": "number"
        },
        "developer_defaults": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "usd_1d": {
                  "minimum": 1,
                  "multipleOf": 0.01,
                  "type": "number"
                },
                "usd_28d": {
                  "minimum": 1,
                  "multipleOf": 0.01,
                  "type": "number"
                },
                "usd_7d": {
                  "minimum": 1,
                  "multipleOf": 0.01,
                  "type": "number"
                }
              },
              "required": [
                "usd_1d",
                "usd_7d",
                "usd_28d"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "developer_overrides": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "usd_1d": {
                "anyOf": [
                  {
                    "minimum": 1,
                    "multipleOf": 0.01,
                    "type": "number"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "usd_28d": {
                "anyOf": [
                  {
                    "minimum": 1,
                    "multipleOf": 0.01,
                    "type": "number"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "usd_7d": {
                "anyOf": [
                  {
                    "minimum": 1,
                    "multipleOf": 0.01,
                    "type": "number"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "type": "object"
          },
          "type": "object"
        }
      },
      "required": [
        "default_session_usd",
        "account",
        "developer_defaults",
        "developer_overrides"
      ],
      "type": "object"
    },
    "windows": {
      "items": {
        "properties": {
          "exhausted": {
            "type": "boolean"
          },
          "fraction_used": {
            "type": "number"
          },
          "limit_usd": {
            "type": "number"
          },
          "platform_max_usd": {
            "type": "number"
          },
          "remaining_usd": {
            "type": "number"
          },
          "spent_usd": {
            "type": "number"
          },
          "window_days": {
            "type": "integer"
          }
        },
        "required": [
          "window_days",
          "spent_usd",
          "limit_usd",
          "remaining_usd",
          "fraction_used",
          "exhausted",
          "platform_max_usd"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "as_of",
    "credit_balance_usd",
    "credit_exhausted",
    "policy",
    "alerts",
    "per_run",
    "windows",
    "developer_limits"
  ],
  "type": "object"
}
```

---

# List models

> List supported models, harnesses, capabilities, and token prices.

Source: https://www.ellipsis.dev/docs/api/account/get-account-models

## GET /v1/account/models

List supported models, harnesses, capabilities, and token prices.

Required permissions: read:templates.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "models": [
    {
      "capabilities": [
        str
      ],
      "default_reasoning_effort": str, # str | null
      "display_name": str,
      "harness": str,
      "id": str,
      "is_default_agent_model": bool,
      "manufacturer": str,
      "rate_card": {
        "cache_read_millicents_per_1m_tokens": int,
        "cache_write_1h_millicents_per_1m_tokens": int,
        "cache_write_5m_millicents_per_1m_tokens": int,
        "input_millicents_per_1m_tokens": int,
        "output_millicents_per_1m_tokens": int
      },
      "reasoning_efforts": [ # list[str]
        str
      ]
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.account.models.list()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.account.models.list();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/account/models" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "models": {
      "items": {
        "properties": {
          "capabilities": {
            "items": {
              "enum": [
                "coding",
                "interactive",
                "agent",
                "structured_input",
                "structured_output",
                "system_files",
                "images",
                "mcp",
                "skills",
                "settings",
                "fallback_model",
                "effort"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "default_reasoning_effort": {
            "anyOf": [
              {
                "enum": [
                  "low",
                  "medium",
                  "high",
                  "xhigh",
                  "max"
                ],
                "type": "string"
              },
              {
                "enum": [
                  "none",
                  "low",
                  "medium",
                  "high",
                  "xhigh",
                  "max"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "display_name": {
            "type": "string"
          },
          "harness": {
            "enum": [
              "claude_code",
              "codex"
            ],
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "is_default_agent_model": {
            "type": "boolean"
          },
          "manufacturer": {
            "enum": [
              "anthropic",
              "openai",
              "zai",
              "minimax",
              "moonshot"
            ],
            "type": "string"
          },
          "rate_card": {
            "properties": {
              "cache_read_millicents_per_1m_tokens": {
                "type": "integer"
              },
              "cache_write_1h_millicents_per_1m_tokens": {
                "type": "integer"
              },
              "cache_write_5m_millicents_per_1m_tokens": {
                "type": "integer"
              },
              "input_millicents_per_1m_tokens": {
                "type": "integer"
              },
              "output_millicents_per_1m_tokens": {
                "type": "integer"
              }
            },
            "required": [
              "input_millicents_per_1m_tokens",
              "cache_write_5m_millicents_per_1m_tokens",
              "cache_write_1h_millicents_per_1m_tokens",
              "cache_read_millicents_per_1m_tokens",
              "output_millicents_per_1m_tokens"
            ],
            "type": "object"
          },
          "reasoning_efforts": {
            "items": {
              "anyOf": [
                {
                  "enum": [
                    "low",
                    "medium",
                    "high",
                    "xhigh",
                    "max"
                  ],
                  "type": "string"
                },
                {
                  "enum": [
                    "none",
                    "low",
                    "medium",
                    "high",
                    "xhigh",
                    "max"
                  ],
                  "type": "string"
                }
              ]
            },
            "type": "array"
          }
        },
        "required": [
          "id",
          "display_name",
          "harness",
          "capabilities",
          "manufacturer",
          "is_default_agent_model",
          "rate_card"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "models"
  ],
  "type": "object"
}
```

---

# Get usage

> Read usage for a UTC calendar month. Rated subscription usage is separate from actual Ellipsis credit charges.

Source: https://www.ellipsis.dev/docs/api/account/get-account-usage

## GET /v1/account/usage

Read usage for a UTC calendar month. Rated subscription usage is separate from actual Ellipsis credit charges.

Required permissions: read:account.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "agent_by_model": [
    {
      "cost_fee_millicents": int,
      "cost_sandbox_cpu_millicents": int,
      "cost_sandbox_memory_millicents": int,
      "cost_tokens_millicents": int,
      "model_id": str,
      "tokens": int
    }
  ],
  "billing_periods": [
    {
      "is_current": bool,
      "period_end": str,
      "period_start": str
    }
  ],
  "by_funding_source": [
    {
      "charged_millicents": int,
      "funding_source": str,
      "pending_requests": int,
      "rated_token_cost_millicents": int,
      "requests": int,
      "token_charged_millicents": int,
      "tokens": int,
      "unresolved_requests": int
    }
  ],
  "by_model": [
    {
      "cost_fee_millicents": int,
      "cost_sandbox_cpu_millicents": int,
      "cost_sandbox_memory_millicents": int,
      "cost_tokens_millicents": int,
      "model_id": str,
      "tokens": int
    }
  ],
  "daily": [
    {
      "cost_fee_millicents": int,
      "cost_sandbox_cpu_millicents": int,
      "cost_sandbox_memory_millicents": int,
      "cost_tokens_millicents": int,
      "date": str,
      "tokens": int,
      "tokens_cache_creation": int,
      "tokens_cache_read": int,
      "tokens_input": int,
      "tokens_output": int
    }
  ],
  "developer_spend": [
    {
      "attribution_id": str,
      "attribution_login": str,
      "attribution_type": str,
      "cost_fee_millicents": int,
      "cost_sandbox_cpu_millicents": int,
      "cost_sandbox_memory_millicents": int,
      "cost_tokens_millicents": int,
      "runs": int,
      "tokens": int
    }
  ],
  "period_end": str,
  "period_start": str,
  "prior_total_cost_millicents": int,
  "prior_total_tokens": int,
  "total_cost_millicents": int,
  "total_tokens": int
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.account.usage()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.account.usage();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/account/usage" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "agent_by_model": {
      "items": {
        "properties": {
          "cost_fee_millicents": {
            "type": "integer"
          },
          "cost_sandbox_cpu_millicents": {
            "type": "integer"
          },
          "cost_sandbox_memory_millicents": {
            "type": "integer"
          },
          "cost_tokens_millicents": {
            "type": "integer"
          },
          "model_id": {
            "type": "string"
          },
          "tokens": {
            "type": "integer"
          }
        },
        "required": [
          "model_id",
          "tokens",
          "cost_tokens_millicents",
          "cost_sandbox_cpu_millicents",
          "cost_sandbox_memory_millicents",
          "cost_fee_millicents"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "billing_periods": {
      "items": {
        "properties": {
          "is_current": {
            "type": "boolean"
          },
          "period_end": {
            "type": "string"
          },
          "period_start": {
            "type": "string"
          }
        },
        "required": [
          "period_start",
          "period_end",
          "is_current"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "by_funding_source": {
      "items": {
        "properties": {
          "charged_millicents": {
            "default": 0,
            "type": "integer"
          },
          "funding_source": {
            "enum": [
              "ellipsis",
              "byok",
              "bedrock",
              "claude_subscription",
              "codex_subscription",
              "unknown"
            ],
            "type": "string"
          },
          "pending_requests": {
            "default": 0,
            "type": "integer"
          },
          "rated_token_cost_millicents": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "requests": {
            "default": 0,
            "type": "integer"
          },
          "token_charged_millicents": {
            "default": 0,
            "type": "integer"
          },
          "tokens": {
            "default": 0,
            "type": "integer"
          },
          "unresolved_requests": {
            "default": 0,
            "type": "integer"
          }
        },
        "required": [
          "funding_source"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "by_model": {
      "items": {
        "properties": {
          "cost_fee_millicents": {
            "type": "integer"
          },
          "cost_sandbox_cpu_millicents": {
            "type": "integer"
          },
          "cost_sandbox_memory_millicents": {
            "type": "integer"
          },
          "cost_tokens_millicents": {
            "type": "integer"
          },
          "model_id": {
            "type": "string"
          },
          "tokens": {
            "type": "integer"
          }
        },
        "required": [
          "model_id",
          "tokens",
          "cost_tokens_millicents",
          "cost_sandbox_cpu_millicents",
          "cost_sandbox_memory_millicents",
          "cost_fee_millicents"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "daily": {
      "items": {
        "properties": {
          "cost_fee_millicents": {
            "type": "integer"
          },
          "cost_sandbox_cpu_millicents": {
            "type": "integer"
          },
          "cost_sandbox_memory_millicents": {
            "type": "integer"
          },
          "cost_tokens_millicents": {
            "type": "integer"
          },
          "date": {
            "type": "string"
          },
          "tokens": {
            "type": "integer"
          },
          "tokens_cache_creation": {
            "type": "integer"
          },
          "tokens_cache_read": {
            "type": "integer"
          },
          "tokens_input": {
            "type": "integer"
          },
          "tokens_output": {
            "type": "integer"
          }
        },
        "required": [
          "date",
          "tokens",
          "tokens_input",
          "tokens_output",
          "tokens_cache_read",
          "tokens_cache_creation",
          "cost_tokens_millicents",
          "cost_sandbox_cpu_millicents",
          "cost_sandbox_memory_millicents",
          "cost_fee_millicents"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "developer_spend": {
      "items": {
        "properties": {
          "attribution_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "attribution_login": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "attribution_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "cost_fee_millicents": {
            "type": "integer"
          },
          "cost_sandbox_cpu_millicents": {
            "type": "integer"
          },
          "cost_sandbox_memory_millicents": {
            "type": "integer"
          },
          "cost_tokens_millicents": {
            "type": "integer"
          },
          "runs": {
            "type": "integer"
          },
          "tokens": {
            "type": "integer"
          }
        },
        "required": [
          "attribution_type",
          "attribution_id",
          "attribution_login",
          "tokens",
          "cost_tokens_millicents",
          "cost_sandbox_cpu_millicents",
          "cost_sandbox_memory_millicents",
          "cost_fee_millicents",
          "runs"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "period_end": {
      "type": "string"
    },
    "period_start": {
      "type": "string"
    },
    "prior_total_cost_millicents": {
      "type": "integer"
    },
    "prior_total_tokens": {
      "type": "integer"
    },
    "total_cost_millicents": {
      "type": "integer"
    },
    "total_tokens": {
      "type": "integer"
    }
  },
  "required": [
    "billing_periods",
    "period_start",
    "period_end",
    "total_tokens",
    "total_cost_millicents",
    "prior_total_tokens",
    "prior_total_cost_millicents",
    "daily",
    "by_model",
    "agent_by_model",
    "developer_spend"
  ],
  "type": "object"
}
```

---

# Account

> Account endpoints describe the resources available to your agents. Check budgets, inspect usage, and list available models.

Source: https://www.ellipsis.dev/docs/api/account

- [`GET /v1/account/budget`](https://www.ellipsis.dev/docs/api/account/get-account-budget): Get budget
- [`GET /v1/account/models`](https://www.ellipsis.dev/docs/api/account/get-account-models): List models
- [`GET /v1/account/usage`](https://www.ellipsis.dev/docs/api/account/get-account-usage): Get usage

---

# Delete an agent

> Delete an API-managed agent. Existing session history remains available.

Source: https://www.ellipsis.dev/docs/api/agents/delete-agents-agent_id

## DELETE /v1/agents/{agent_id}

Delete an API-managed agent. Existing session history remains available.

Required permissions: write:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.agents.delete("check-tests")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.agents.delete("check-tests");
console.log(result);
```

### cURL

```bash
curl -X DELETE "https://api.ellipsis.dev/v1/agents/{agent_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

---

# Get agent usage

> Read usage and spend windows for an agent.

Source: https://www.ellipsis.dev/docs/api/agents/get-agents-agent_id-metrics

## GET /v1/agents/{agent_id}/metrics

Read usage and spend windows for an agent.

Required permissions: read:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "samples": [
    {
      "cost": int,
      "duration_seconds": float,
      "tokens_total": int
    }
  ],
  "spend_windows": [
    {
      "limit_usd": float,
      "platform_max_usd": float,
      "spent_usd": float,
      "window_days": int
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.agents.metrics("check-tests")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.agents.metrics("check-tests");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/agents/{agent_id}/metrics" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "samples": {
      "items": {
        "properties": {
          "cost": {
            "type": "integer"
          },
          "duration_seconds": {
            "type": "number"
          },
          "tokens_total": {
            "type": "integer"
          }
        },
        "required": [
          "duration_seconds",
          "cost",
          "tokens_total"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "spend_windows": {
      "items": {
        "properties": {
          "limit_usd": {
            "type": "number"
          },
          "platform_max_usd": {
            "type": "number"
          },
          "spent_usd": {
            "type": "number"
          },
          "window_days": {
            "type": "integer"
          }
        },
        "required": [
          "window_days",
          "spent_usd",
          "limit_usd",
          "platform_max_usd"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "samples",
    "spend_windows"
  ],
  "type": "object"
}
```

---

# Get an agent

> Read a saved agent and its configuration source.

Source: https://www.ellipsis.dev/docs/api/agents/get-agents-agent_id

## GET /v1/agents/{agent_id}

Read a saved agent and its configuration source.

Required permissions: read:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "agent": {
    "config": {
      "ellipsis": {
        "description": str,
        "enabled": bool,
        "kind": "agent",
        "metadata": {
          "annotations": {
            "[str]": str
          },
          "labels": [
            str
          ]
        },
        "name": str,
        "version": str
      },
      "input": {
        "json_schema": {
          "[str]": any
        },
        "message": str
      },
      "session": {
        "budget": {
          "day": float,
          "month": float,
          "session": float,
          "week": float
        },
        "claude_code": {
          "effort": str,
          "fallback_model": str,
          "max_turns": int,
          "model": str,
          "prompt": str,
          "settings": {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        },
        "codex": {
          "effort": str,
          "model": str,
          "prompt": str
        },
        "environment": { # str
          "compute": {
            "cpu": int,
            "memory": { # str | null
              "gb": int,
              "mb": int
            },
            "timeout": { # str | null
              "hours": int,
              "minutes": int,
              "seconds": int
            }
          },
          "hooks": {
            "after_checkout": { # str | null
              "run": str
            },
            "before_start": { # str | null
              "run": str
            },
            "build_base": { # str | null
              "inputs": [
                str
              ],
              "run": str
            },
            "post_clone": str,
            "post_start": str
          },
          "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
          # McpRemoteServer]
            {
              "args": [
                str
              ],
              "command": str,
              "env": {
                "[str]": str
              },
              "name": str
            }
          ],
          "repositories": [
            {
              "name": str,
              "owner": str,
              "ref": str
            }
          ],
          "variables": [
            {
              "name": str,
              "value": str
            }
          ]
        },
        "output": {
          "json_schema": {
            "[str]": any
          }
        },
        "permissions": {
          "ellipsis": { # bool | str
            "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
              {
                "level": str,
                "match": [
                  str
                ]
              }
            ]
          },
          "github": {
            "permissions": { # "read_only" | null
              "[str]": str
            },
            "repositories": [
              str
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "linear_issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ]
        },
        "pull_request": {
          "base": [
            str
          ],
          "draft": bool,
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "head": [
            str
          ],
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "push": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "type": "react"
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "id": str,
    "last_session_created_at": str,
    "last_session_id": str,
    "last_sync_error": str,
    "last_synced_commit_sha": str,
    "managed_by": str,
    "name": str,
    "pending_pull_request_url": str,
    "sha": str,
    "source_details": {
      "branch": str,
      "path": str,
      "repo_id": int
    },
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.agents.get("check-tests")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.agents.get("check-tests");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/agents/{agent_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "agent": {
      "properties": {
        "config": {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "additionalProperties": false,
              "properties": {
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "enabled": {
                  "default": true,
                  "type": "boolean"
                },
                "kind": {
                  "const": "agent",
                  "type": "string"
                },
                "metadata": {
                  "additionalProperties": false,
                  "properties": {
                    "annotations": {
                      "items": {
                        "type": "string"
                      },
                      "default": {},
                      "type": "object"
                    },
                    "labels": {
                      "default": [],
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "annotations",
                    "labels"
                  ],
                  "type": "object"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "version": {
                  "default": "v1",
                  "type": "string"
                }
              },
              "required": [
                "description",
                "enabled",
                "kind",
                "metadata",
                "name",
                "version"
              ],
              "type": "object"
            },
            "input": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "json_schema": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "message": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "json_schema",
                    "message"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "session": {
              "additionalProperties": false,
              "allOf": [
                {
                  "oneOf": [
                    {
                      "properties": {
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "null"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    },
                    {
                      "properties": {
                        "claude_code": {
                          "type": "null"
                        },
                        "codex": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    }
                  ]
                }
              ],
              "properties": {
                "budget": {
                  "additionalProperties": false,
                  "properties": {
                    "day": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "month": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "session": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "week": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "day",
                    "month",
                    "session",
                    "week"
                  ],
                  "type": "object"
                },
                "claude_code": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "fallback_model": {
                          "type": "object"
                        },
                        "max_turns": {
                          "type": "object"
                        },
                        "model": {
                          "type": "object"
                        },
                        "prompt": {
                          "type": "object"
                        },
                        "settings": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "fallback_model",
                        "max_turns",
                        "model",
                        "prompt",
                        "settings"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "codex": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "model": {
                          "type": "string"
                        },
                        "prompt": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "model",
                        "prompt"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "environment": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "compute": {
                          "type": "object"
                        },
                        "hooks": {
                          "type": "object"
                        },
                        "mcp_servers": {
                          "type": "array"
                        },
                        "repositories": {
                          "type": "array"
                        },
                        "variables": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "compute",
                        "hooks",
                        "mcp_servers",
                        "repositories",
                        "variables"
                      ],
                      "type": "object"
                    }
                  ],
                  "default": {
                    "compute": {},
                    "hooks": {},
                    "mcp_servers": [],
                    "repositories": [],
                    "variables": []
                  }
                },
                "output": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "json_schema": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "json_schema"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "permissions": {
                  "additionalProperties": false,
                  "properties": {
                    "ellipsis": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "object"
                        }
                      ],
                      "default": true
                    },
                    "github": {
                      "additionalProperties": false,
                      "properties": {
                        "permissions": {
                          "type": "object"
                        },
                        "repositories": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "permissions",
                        "repositories"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "ellipsis",
                    "github"
                  ],
                  "type": "object"
                },
                "skills": {
                  "default": [],
                  "items": {
                    "additionalProperties": false,
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "repository": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "path",
                      "repository"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "budget",
                "claude_code",
                "codex",
                "environment",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "sentry",
                        "slack_channel",
                        "type"
                      ],
                      "type": "object"
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "ellipsis",
            "input",
            "session",
            "trigger"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "edited_by": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "last_session_created_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_session_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_sync_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_synced_commit_sha": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "managed_by": {
          "enum": [
            "github",
            "api"
          ],
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "pending_pull_request_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "sha": {
          "type": "string"
        },
        "source_details": {
          "anyOf": [
            {
              "properties": {
                "branch": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "repo_id": {
                  "type": "integer"
                }
              },
              "required": [
                "repo_id",
                "path",
                "branch"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "id",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config"
      ],
      "type": "object"
    }
  },
  "required": [
    "agent"
  ],
  "type": "object"
}
```

---

# List agents

> List saved agents.

Source: https://www.ellipsis.dev/docs/api/agents/get-agents

## GET /v1/agents

List saved agents.

Required permissions: read:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "agents": [
    {
      "config": {
        "ellipsis": {
          "description": str,
          "enabled": bool,
          "kind": "agent",
          "metadata": {
            "annotations": {
              "[str]": str
            },
            "labels": [
              str
            ]
          },
          "name": str,
          "version": str
        },
        "input": {
          "json_schema": {
            "[str]": any
          },
          "message": str
        },
        "session": {
          "budget": {
            "day": float,
            "month": float,
            "session": float,
            "week": float
          },
          "claude_code": {
            "effort": str,
            "fallback_model": str,
            "max_turns": int,
            "model": str,
            "prompt": str,
            "settings": {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          },
          "codex": {
            "effort": str,
            "model": str,
            "prompt": str
          },
          "environment": { # str
            "compute": {
              "cpu": int,
              "memory": { # str | null
                "gb": int,
                "mb": int
              },
              "timeout": { # str | null
                "hours": int,
                "minutes": int,
                "seconds": int
              }
            },
            "hooks": {
              "after_checkout": { # str | null
                "run": str
              },
              "before_start": { # str | null
                "run": str
              },
              "build_base": { # str | null
                "inputs": [
                  str
                ],
                "run": str
              },
              "post_clone": str,
              "post_start": str
            },
            "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
            # McpRemoteServer]
              {
                "args": [
                  str
                ],
                "command": str,
                "env": {
                  "[str]": str
                },
                "name": str
              }
            ],
            "repositories": [
              {
                "name": str,
                "owner": str,
                "ref": str
              }
            ],
            "variables": [
              {
                "name": str,
                "value": str
              }
            ]
          },
          "output": {
            "json_schema": {
              "[str]": any
            }
          },
          "permissions": {
            "ellipsis": { # bool | str
              "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                {
                  "level": str,
                  "match": [
                    str
                  ]
                }
              ]
            },
            "github": {
              "permissions": { # "read_only" | null
                "[str]": str
              },
              "repositories": [
                str
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "linear_issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ]
          },
          "pull_request": {
            "base": [
              str
            ],
            "draft": bool,
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "head": [
              str
            ],
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "push": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "type": "react"
        }
      },
      "created_at": str,
      "display_name": str,
      "edited_by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "type": str
      },
      "id": str,
      "last_session_created_at": str,
      "last_session_id": str,
      "last_sync_error": str,
      "last_synced_commit_sha": str,
      "managed_by": str,
      "name": str,
      "pending_pull_request_url": str,
      "sha": str,
      "source_details": {
        "branch": str,
        "path": str,
        "repo_id": int
      },
      "updated_at": str
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.agents.list()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.agents.list();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/agents" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "agents": {
      "items": {
        "properties": {
          "config": {
            "additionalProperties": false,
            "properties": {
              "ellipsis": {
                "additionalProperties": false,
                "properties": {
                  "description": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "enabled": {
                    "default": true,
                    "type": "boolean"
                  },
                  "kind": {
                    "const": "agent",
                    "type": "string"
                  },
                  "metadata": {
                    "additionalProperties": false,
                    "properties": {
                      "annotations": {
                        "type": "object"
                      },
                      "labels": {
                        "type": "array"
                      }
                    },
                    "required": [
                      "annotations",
                      "labels"
                    ],
                    "type": "object"
                  },
                  "name": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "version": {
                    "default": "v1",
                    "type": "string"
                  }
                },
                "required": [
                  "description",
                  "enabled",
                  "kind",
                  "metadata",
                  "name",
                  "version"
                ],
                "type": "object"
              },
              "input": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "json_schema": {
                        "type": "object"
                      },
                      "message": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "json_schema",
                      "message"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session": {
                "additionalProperties": false,
                "allOf": [
                  {
                    "oneOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "object"
                      }
                    ]
                  }
                ],
                "properties": {
                  "budget": {
                    "additionalProperties": false,
                    "properties": {
                      "day": {
                        "type": "object"
                      },
                      "month": {
                        "type": "object"
                      },
                      "session": {
                        "type": "object"
                      },
                      "week": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "day",
                      "month",
                      "session",
                      "week"
                    ],
                    "type": "object"
                  },
                  "claude_code": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "codex": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "environment": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      }
                    ],
                    "default": {
                      "compute": {},
                      "hooks": {},
                      "mcp_servers": [],
                      "repositories": [],
                      "variables": []
                    }
                  },
                  "output": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "permissions": {
                    "additionalProperties": false,
                    "properties": {
                      "ellipsis": {
                        "type": "object"
                      },
                      "github": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "ellipsis",
                      "github"
                    ],
                    "type": "object"
                  },
                  "skills": {
                    "default": [],
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "budget",
                  "claude_code",
                  "codex",
                  "environment",
                  "output",
                  "permissions",
                  "skills"
                ],
                "type": "object"
              },
              "trigger": {
                "anyOf": [
                  {
                    "oneOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "object"
                      }
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "ellipsis",
              "input",
              "session",
              "trigger"
            ],
            "type": "object"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "display_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "edited_by": {
            "anyOf": [
              {
                "properties": {
                  "avatar_url": {
                    "type": "string"
                  },
                  "id": {
                    "type": "integer"
                  },
                  "login": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "User",
                      "Organization",
                      "Bot",
                      "Mannequin"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "avatar_url",
                  "id",
                  "login",
                  "type"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string"
          },
          "last_session_created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "last_session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "last_sync_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "last_synced_commit_sha": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "managed_by": {
            "enum": [
              "github",
              "api"
            ],
            "type": "string"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "pending_pull_request_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "sha": {
            "type": "string"
          },
          "source_details": {
            "anyOf": [
              {
                "properties": {
                  "branch": {
                    "type": "string"
                  },
                  "path": {
                    "type": "string"
                  },
                  "repo_id": {
                    "type": "integer"
                  }
                },
                "required": [
                  "repo_id",
                  "path",
                  "branch"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "sha",
          "created_at",
          "updated_at",
          "managed_by",
          "config"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "agents"
  ],
  "type": "object"
}
```

---

# Agents

> Agents define repeatable agent work. Create and update configurations, connect them to GitHub, start sessions, and inspect usage.

Source: https://www.ellipsis.dev/docs/api/agents

- [`POST /v1/agents`](https://www.ellipsis.dev/docs/api/agents/post-agents): Create an agent
- [`GET /v1/agents`](https://www.ellipsis.dev/docs/api/agents/get-agents): List agents
- [`GET /v1/agents/{agent_id}`](https://www.ellipsis.dev/docs/api/agents/get-agents-agent_id): Get an agent
- [`PUT /v1/agents/{agent_id}`](https://www.ellipsis.dev/docs/api/agents/put-agents-agent_id): Update an agent
- [`DELETE /v1/agents/{agent_id}`](https://www.ellipsis.dev/docs/api/agents/delete-agents-agent_id): Delete an agent
- [`POST /v1/agents/{agent_id}/link`](https://www.ellipsis.dev/docs/api/agents/post-agents-agent_id-link): Link to GitHub
- [`GET /v1/agents/{agent_id}/metrics`](https://www.ellipsis.dev/docs/api/agents/get-agents-agent_id-metrics): Get agent usage
- [`POST /v1/agents/{agent_id}/sessions`](https://www.ellipsis.dev/docs/api/agents/post-agents-agent_id-sessions): Run an agent
- [`POST /v1/agents/{agent_id}/unlink`](https://www.ellipsis.dev/docs/api/agents/post-agents-agent_id-unlink): Unlink from GitHub

---

# Link to GitHub

> Open a pull request containing the definition. Git takes ownership when that pull request merges and syncs.

Source: https://www.ellipsis.dev/docs/api/agents/post-agents-agent_id-link

## POST /v1/agents/{agent_id}/link

Open a pull request containing the definition. Git takes ownership when that pull request merges and syncs.

Required permissions: write:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Request

```text
{
  "path": str,
  "repository": str
}
```

### Response

```text
{
  "agent": {
    "config": {
      "ellipsis": {
        "description": str,
        "enabled": bool,
        "kind": "agent",
        "metadata": {
          "annotations": {
            "[str]": str
          },
          "labels": [
            str
          ]
        },
        "name": str,
        "version": str
      },
      "input": {
        "json_schema": {
          "[str]": any
        },
        "message": str
      },
      "session": {
        "budget": {
          "day": float,
          "month": float,
          "session": float,
          "week": float
        },
        "claude_code": {
          "effort": str,
          "fallback_model": str,
          "max_turns": int,
          "model": str,
          "prompt": str,
          "settings": {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        },
        "codex": {
          "effort": str,
          "model": str,
          "prompt": str
        },
        "environment": { # str
          "compute": {
            "cpu": int,
            "memory": { # str | null
              "gb": int,
              "mb": int
            },
            "timeout": { # str | null
              "hours": int,
              "minutes": int,
              "seconds": int
            }
          },
          "hooks": {
            "after_checkout": { # str | null
              "run": str
            },
            "before_start": { # str | null
              "run": str
            },
            "build_base": { # str | null
              "inputs": [
                str
              ],
              "run": str
            },
            "post_clone": str,
            "post_start": str
          },
          "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
          # McpRemoteServer]
            {
              "args": [
                str
              ],
              "command": str,
              "env": {
                "[str]": str
              },
              "name": str
            }
          ],
          "repositories": [
            {
              "name": str,
              "owner": str,
              "ref": str
            }
          ],
          "variables": [
            {
              "name": str,
              "value": str
            }
          ]
        },
        "output": {
          "json_schema": {
            "[str]": any
          }
        },
        "permissions": {
          "ellipsis": { # bool | str
            "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
              {
                "level": str,
                "match": [
                  str
                ]
              }
            ]
          },
          "github": {
            "permissions": { # "read_only" | null
              "[str]": str
            },
            "repositories": [
              str
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "linear_issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ]
        },
        "pull_request": {
          "base": [
            str
          ],
          "draft": bool,
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "head": [
            str
          ],
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "push": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "type": "react"
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "id": str,
    "last_session_created_at": str,
    "last_session_id": str,
    "last_sync_error": str,
    "last_synced_commit_sha": str,
    "managed_by": str,
    "name": str,
    "pending_pull_request_url": str,
    "sha": str,
    "source_details": {
      "branch": str,
      "path": str,
      "repo_id": int
    },
    "updated_at": str
  },
  "path": str,
  "pull_request_url": str
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.LinkAgentRequest.model_validate(
    {
      "repository": "api-repo"
    }
)

result = client.agents.link("check-tests", request.repository)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.agents.link>[1] = {
  "repository": "api-repo"
};

const result = await client.agents.link("check-tests", request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/agents/{agent_id}/link" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "repository": "api-repo"
}'
```

### Request schema

```json
{
  "properties": {
    "path": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "repository": {
      "type": "string"
    }
  },
  "required": [
    "repository"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "agent": {
      "properties": {
        "config": {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "additionalProperties": false,
              "properties": {
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "enabled": {
                  "default": true,
                  "type": "boolean"
                },
                "kind": {
                  "const": "agent",
                  "type": "string"
                },
                "metadata": {
                  "additionalProperties": false,
                  "properties": {
                    "annotations": {
                      "items": {
                        "type": "string"
                      },
                      "default": {},
                      "type": "object"
                    },
                    "labels": {
                      "default": [],
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "annotations",
                    "labels"
                  ],
                  "type": "object"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "version": {
                  "default": "v1",
                  "type": "string"
                }
              },
              "required": [
                "description",
                "enabled",
                "kind",
                "metadata",
                "name",
                "version"
              ],
              "type": "object"
            },
            "input": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "json_schema": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "message": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "json_schema",
                    "message"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "session": {
              "additionalProperties": false,
              "allOf": [
                {
                  "oneOf": [
                    {
                      "properties": {
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "null"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    },
                    {
                      "properties": {
                        "claude_code": {
                          "type": "null"
                        },
                        "codex": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    }
                  ]
                }
              ],
              "properties": {
                "budget": {
                  "additionalProperties": false,
                  "properties": {
                    "day": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "month": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "session": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "week": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "day",
                    "month",
                    "session",
                    "week"
                  ],
                  "type": "object"
                },
                "claude_code": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "fallback_model": {
                          "type": "object"
                        },
                        "max_turns": {
                          "type": "object"
                        },
                        "model": {
                          "type": "object"
                        },
                        "prompt": {
                          "type": "object"
                        },
                        "settings": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "fallback_model",
                        "max_turns",
                        "model",
                        "prompt",
                        "settings"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "codex": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "model": {
                          "type": "string"
                        },
                        "prompt": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "model",
                        "prompt"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "environment": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "compute": {
                          "type": "object"
                        },
                        "hooks": {
                          "type": "object"
                        },
                        "mcp_servers": {
                          "type": "array"
                        },
                        "repositories": {
                          "type": "array"
                        },
                        "variables": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "compute",
                        "hooks",
                        "mcp_servers",
                        "repositories",
                        "variables"
                      ],
                      "type": "object"
                    }
                  ],
                  "default": {
                    "compute": {},
                    "hooks": {},
                    "mcp_servers": [],
                    "repositories": [],
                    "variables": []
                  }
                },
                "output": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "json_schema": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "json_schema"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "permissions": {
                  "additionalProperties": false,
                  "properties": {
                    "ellipsis": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "object"
                        }
                      ],
                      "default": true
                    },
                    "github": {
                      "additionalProperties": false,
                      "properties": {
                        "permissions": {
                          "type": "object"
                        },
                        "repositories": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "permissions",
                        "repositories"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "ellipsis",
                    "github"
                  ],
                  "type": "object"
                },
                "skills": {
                  "default": [],
                  "items": {
                    "additionalProperties": false,
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "repository": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "path",
                      "repository"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "budget",
                "claude_code",
                "codex",
                "environment",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "sentry",
                        "slack_channel",
                        "type"
                      ],
                      "type": "object"
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "ellipsis",
            "input",
            "session",
            "trigger"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "edited_by": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "last_session_created_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_session_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_sync_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_synced_commit_sha": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "managed_by": {
          "enum": [
            "github",
            "api"
          ],
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "pending_pull_request_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "sha": {
          "type": "string"
        },
        "source_details": {
          "anyOf": [
            {
              "properties": {
                "branch": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "repo_id": {
                  "type": "integer"
                }
              },
              "required": [
                "repo_id",
                "path",
                "branch"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "id",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config"
      ],
      "type": "object"
    },
    "path": {
      "type": "string"
    },
    "pull_request_url": {
      "type": "string"
    }
  },
  "required": [
    "agent",
    "path",
    "pull_request_url"
  ],
  "type": "object"
}
```

---

# Run an agent

> Start a one-shot session from a saved Claude Code agent. Supply input when it declares an input schema; otherwise supply prompt. Send exactly one.

Source: https://www.ellipsis.dev/docs/api/agents/post-agents-agent_id-sessions

## POST /v1/agents/{agent_id}/sessions

Start a one-shot session from a saved Claude Code agent. Supply input when it declares an input schema; otherwise supply prompt. Send exactly one.

Required permissions: write:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Request

```text
{
  "budget": float,
  "input": {
    "[str]": any
  },
  "metadata": {
    "[str]": str
  },
  "prompt": str
}
```

### Response

```text
{
  "session": {
    "agent": {
      "config": {
        "ellipsis": {
          "description": str,
          "enabled": bool,
          "kind": "agent",
          "metadata": {
            "annotations": {
              "[str]": str
            },
            "labels": [
              str
            ]
          },
          "name": str,
          "version": str
        },
        "input": {
          "json_schema": {
            "[str]": any
          },
          "message": str
        },
        "session": {
          "budget": {
            "day": float,
            "month": float,
            "session": float,
            "week": float
          },
          "claude_code": {
            "effort": str,
            "fallback_model": str,
            "max_turns": int,
            "model": str,
            "prompt": str,
            "settings": {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          },
          "codex": {
            "effort": str,
            "model": str,
            "prompt": str
          },
          "environment": { # str
            "compute": {
              "cpu": int,
              "memory": { # str | null
                "gb": int,
                "mb": int
              },
              "timeout": { # str | null
                "hours": int,
                "minutes": int,
                "seconds": int
              }
            },
            "hooks": {
              "after_checkout": { # str | null
                "run": str
              },
              "before_start": { # str | null
                "run": str
              },
              "build_base": { # str | null
                "inputs": [
                  str
                ],
                "run": str
              },
              "post_clone": str,
              "post_start": str
            },
            "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
            # McpRemoteServer]
              {
                "args": [
                  str
                ],
                "command": str,
                "env": {
                  "[str]": str
                },
                "name": str
              }
            ],
            "repositories": [
              {
                "name": str,
                "owner": str,
                "ref": str
              }
            ],
            "variables": [
              {
                "name": str,
                "value": str
              }
            ]
          },
          "output": {
            "json_schema": {
              "[str]": any
            }
          },
          "permissions": {
            "ellipsis": { # bool | str
              "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                {
                  "level": str,
                  "match": [
                    str
                  ]
                }
              ]
            },
            "github": {
              "permissions": { # "read_only" | null
                "[str]": str
              },
              "repositories": [
                str
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "linear_issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ]
          },
          "pull_request": {
            "base": [
              str
            ],
            "draft": bool,
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "head": [
              str
            ],
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "push": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "type": "react"
        }
      },
      "id": str
    },
    "attribution": {
      "id": str,
      "type": str,
      "user": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "type": str
      }
    },
    "budget": float,
    "claude_code": {
      "effort": str,
      "fallback_model": str,
      "max_turns": int,
      "model": str,
      "prompt": str,
      "settings": {
        "path": str,
        "repository": {
          "name": str,
          "owner": str,
          "ref": str
        }
      }
    },
    "codex": {
      "effort": str,
      "model": str,
      "prompt": str
    },
    "cost": {
      "cpu": int,
      "fee": int,
      "llm": int,
      "memory": int,
      "total": int
    },
    "environment": {
      "compute": {
        "cpu": int,
        "memory": { # str | null
          "gb": int,
          "mb": int
        },
        "timeout": { # str | null
          "hours": int,
          "minutes": int,
          "seconds": int
        }
      },
      "hooks": {
        "after_checkout": { # str | null
          "run": str
        },
        "before_start": { # str | null
          "run": str
        },
        "build_base": { # str | null
          "inputs": [
            str
          ],
          "run": str
        },
        "post_clone": str,
        "post_start": str
      },
      "id": str,
      "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
      # McpRemoteServer]
        {
          "args": [
            str
          ],
          "command": str,
          "env": {
            "[str]": str
          },
          "name": str
        }
      ],
      "repositories": [
        {
          "name": str,
          "owner": str,
          "ref": str
        }
      ],
      "source": str,
      "variables": [
        {
          "name": str,
          "value": str
        }
      ]
    },
    "event": { # null | GithubPullRequestEvent | GithubIssueEvent |
    # GithubPushEvent | LinearIssueEvent | SlackMessageEvent |
    # SlackChannelCreatedEvent | SentryAlertEvent
      "action": str, # "review_commented"
      "actor": {
        "avatar_url": str,
        "is_bot": bool,
        "name": str
      },
      "branch": str,
      "number": int,
      "repository": str,
      "title": str,
      "type": "github.pull_request",
      "url": str
    },
    "git": {
      "repos": [
        {
          "commits": [
            {
              "committed_at": str,
              "pushed": bool,
              "sha": str,
              "subject": str
            }
          ],
          "commits_total": int,
          "full_name": str,
          "local_commit": str,
          "local_uncommitted_files": [
            {
              "additions": int,
              "deletions": int,
              "path": str,
              "status": str
            }
          ],
          "prs": [
            {
              "gh_pr_id": int,
              "number": int,
              "title": str,
              "url": str
            }
          ],
          "remote_branch": str,
          "remote_commit": str
        }
      ]
    },
    "handler": {
      "agent_name": str,
      "id": str,
      "service": str,
      "sha": str
    },
    "id": str,
    "lifecycle": {
      "archived": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        }
      },
      "conversation": str,
      "detail": str,
      "interactive": bool,
      "last_execution_result": {
        "completion_reason": str,
        "detail": str
      },
      "prompting": {
        "blocked_reason": str,
        "detail": str,
        "enabled": bool,
        "surface_name": str
      },
      "status": str,
      "stopped": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        }
      },
      "timestamps": {
        "created_at": str,
        "last_activity_at": str,
        "last_message_at": str,
        "updated_at": str
      }
    },
    "metadata": {
      "[str]": str
    },
    "output": {
      "json_schema": {
        "[str]": any
      }
    },
    "parent": {
      "session_id": str
    },
    "permissions": {
      "ellipsis": { # bool | str
        "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
          {
            "level": str,
            "match": [
              str
            ]
          }
        ]
      },
      "github": {
        "permissions": { # "read_only" | null
          "[str]": str
        },
        "repositories": [
          str
        ]
      }
    },
    "skills": [
      {
        "path": str,
        "repository": {
          "name": str,
          "owner": str,
          "ref": str
        }
      }
    ],
    "source": str,
    "summary": {
      "created_at": str,
      "description": str
    },
    "tokens": {
      "cache_creation": int,
      "cache_read": int,
      "input": int,
      "model": str,
      "output": int,
      "total": int
    }
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.StartAgentSessionRequest.model_validate(
    {
      "prompt": "Run the tests."
    }
)

result = client.agents.run("check-tests", prompt=request.prompt)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.agents.run>[1] = {
  "prompt": "Run the tests."
};

const result = await client.agents.run("check-tests", request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/agents/{agent_id}/sessions" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Run the tests."
}'
```

### Request schema

```json
{
  "additionalProperties": false,
  "examples": [
    {
      "input": {
        "issue": "ENG-42"
      }
    },
    {
      "prompt": "Please research and implement ENG-123."
    }
  ],
  "properties": {
    "budget": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "input": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "items": {
        "type": "string"
      },
      "default": {},
      "type": "object"
    },
    "prompt": {
      "anyOf": [
        {
          "minLength": 1,
          "pattern": "\\S",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "examples": [
        "Please research and implement ENG-123."
      ]
    }
  },
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "session": {
      "additionalProperties": false,
      "allOf": [
        {
          "oneOf": [
            {
              "properties": {
                "claude_code": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "codex": {
                  "type": "null"
                }
              },
              "required": [
                "claude_code",
                "codex"
              ]
            },
            {
              "properties": {
                "claude_code": {
                  "type": "null"
                },
                "codex": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "required": [
                "claude_code",
                "codex"
              ]
            }
          ]
        }
      ],
      "properties": {
        "agent": {
          "anyOf": [
            {
              "properties": {
                "config": {
                  "additionalProperties": false,
                  "properties": {
                    "ellipsis": {
                      "additionalProperties": false,
                      "properties": {
                        "description": {
                          "type": "object"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "kind": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "name": {
                          "type": "object"
                        },
                        "version": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "description",
                        "enabled",
                        "kind",
                        "metadata",
                        "name",
                        "version"
                      ],
                      "type": "object"
                    },
                    "input": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "session": {
                      "additionalProperties": false,
                      "allOf": [
                        {
                          "type": "object"
                        }
                      ],
                      "properties": {
                        "budget": {
                          "type": "object"
                        },
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "budget",
                        "claude_code",
                        "codex",
                        "environment",
                        "output",
                        "permissions",
                        "skills"
                      ],
                      "type": "object"
                    },
                    "trigger": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "ellipsis",
                    "input",
                    "session",
                    "trigger"
                  ],
                  "type": "object"
                },
                "id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "config",
                "id"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "attribution": {
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "type": {
              "anyOf": [
                {
                  "enum": [
                    "github_user",
                    "linear_user",
                    "slack_user",
                    "api_key"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "user": {
              "anyOf": [
                {
                  "properties": {
                    "avatar_url": {
                      "type": "string"
                    },
                    "id": {
                      "type": "integer"
                    },
                    "login": {
                      "type": "string"
                    },
                    "type": {
                      "enum": [
                        "User",
                        "Organization",
                        "Bot",
                        "Mannequin"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "avatar_url",
                    "id",
                    "login",
                    "type"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "type",
            "user"
          ],
          "type": "object"
        },
        "budget": {
          "default": 0,
          "type": "number"
        },
        "claude_code": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "effort": {
                  "anyOf": [
                    {
                      "enum": [
                        "low",
                        "medium",
                        "high",
                        "xhigh",
                        "max"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "fallback_model": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "max_turns": {
                  "anyOf": [
                    {
                      "exclusiveMinimum": 0,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "model": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "settings": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "path": {
                          "type": "string"
                        },
                        "repository": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "path",
                        "repository"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "fallback_model",
                "max_turns",
                "model",
                "prompt",
                "settings"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "codex": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "effort": {
                  "anyOf": [
                    {
                      "enum": [
                        "none",
                        "low",
                        "medium",
                        "high",
                        "xhigh",
                        "max"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "model": {
                  "default": "gpt-5.6-terra",
                  "type": "string"
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "model",
                "prompt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "cost": {
          "properties": {
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "default": 0,
              "type": "integer"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "environment": {
          "additionalProperties": false,
          "properties": {
            "compute": {
              "additionalProperties": false,
              "properties": {
                "cpu": {
                  "anyOf": [
                    {
                      "maximum": 32,
                      "minimum": 2,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "memory": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "gb": {
                          "type": "object"
                        },
                        "mb": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "gb",
                        "mb"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "timeout": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "hours": {
                          "type": "object"
                        },
                        "minutes": {
                          "type": "object"
                        },
                        "seconds": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "hours",
                        "minutes",
                        "seconds"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "cpu",
                "memory",
                "timeout"
              ],
              "type": "object"
            },
            "hooks": {
              "additionalProperties": false,
              "properties": {
                "after_checkout": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "before_start": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "build_base": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "inputs": {
                          "type": "object"
                        },
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "inputs",
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_clone": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_start": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "after_checkout",
                "before_start",
                "build_base",
                "post_clone",
                "post_start"
              ],
              "type": "object"
            },
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "mcp_servers": {
              "default": [],
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "args": {
                        "type": "array"
                      },
                      "command": {
                        "type": "string"
                      },
                      "env": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "args",
                      "command",
                      "env",
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "headers": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "headers",
                      "name",
                      "url"
                    ],
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            },
            "repositories": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "ref": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "owner",
                  "ref"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "source": {
              "anyOf": [
                {
                  "enum": [
                    "request",
                    "agent",
                    "repo_default",
                    "account_default",
                    "platform_default"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "variables": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "value"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "compute",
            "hooks",
            "id",
            "mcp_servers",
            "repositories",
            "source",
            "variables"
          ],
          "type": "object"
        },
        "event": {
          "anyOf": [
            {
              "oneOf": [
                {
                  "properties": {
                    "action": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "type": "string"
                    },
                    "number": {
                      "type": "integer"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.pull_request",
                      "default": "github.pull_request",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "number",
                    "repository",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "opened",
                        "closed",
                        "commented"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "number": {
                      "type": "integer"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.issue",
                      "default": "github.issue",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "number",
                    "repository",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "after": {
                      "type": "string"
                    },
                    "before": {
                      "type": "string"
                    },
                    "branch": {
                      "type": "string"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.push",
                      "default": "github.push",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "actor",
                    "after",
                    "before",
                    "branch",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "identifier": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "number": {
                      "type": "integer"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "linear.issue",
                      "default": "linear.issue",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "identifier",
                    "number",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "message",
                        "app_mention"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "channel_id": {
                      "type": "string"
                    },
                    "channel_name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "message_ts": {
                      "type": "string"
                    },
                    "thread_ts": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "slack.message",
                      "default": "slack.message",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "channel_id",
                    "channel_name",
                    "message_ts",
                    "thread_ts",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "channel_id": {
                      "type": "string"
                    },
                    "channel_name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "slack.channel_created",
                      "default": "slack.channel_created",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "actor",
                    "channel_id",
                    "channel_name",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "issue_alert",
                        "metric_alert"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "organization_slug": {
                      "type": "string"
                    },
                    "project_slug": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "title": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "sentry.alert",
                      "default": "sentry.alert",
                      "type": "string"
                    },
                    "url": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "organization_slug",
                    "project_slug",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "git": {
          "anyOf": [
            {
              "properties": {
                "repos": {
                  "default": [],
                  "items": {
                    "properties": {
                      "commits": {
                        "type": "array"
                      },
                      "commits_total": {
                        "type": "integer"
                      },
                      "full_name": {
                        "type": "string"
                      },
                      "local_commit": {
                        "type": "object"
                      },
                      "local_uncommitted_files": {
                        "type": "array"
                      },
                      "prs": {
                        "type": "array"
                      },
                      "remote_branch": {
                        "type": "object"
                      },
                      "remote_commit": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "commits",
                      "commits_total",
                      "full_name",
                      "local_commit",
                      "local_uncommitted_files",
                      "prs",
                      "remote_branch",
                      "remote_commit"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "repos"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "handler": {
          "anyOf": [
            {
              "properties": {
                "agent_name": {
                  "minLength": 1,
                  "type": "string"
                },
                "id": {
                  "minLength": 1,
                  "type": "string"
                },
                "service": {
                  "enum": [
                    "slack",
                    "github",
                    "linear",
                    "sentry"
                  ],
                  "type": "string"
                },
                "sha": {
                  "minLength": 1,
                  "type": "string"
                }
              },
              "required": [
                "agent_name",
                "id",
                "service",
                "sha"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "lifecycle": {
          "properties": {
            "archived": {
              "anyOf": [
                {
                  "properties": {
                    "at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "by": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "at",
                    "by"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "conversation": {
              "enum": [
                "open",
                "closed"
              ],
              "type": "string"
            },
            "detail": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "interactive": {
              "type": "boolean"
            },
            "last_execution_result": {
              "anyOf": [
                {
                  "properties": {
                    "completion_reason": {
                      "enum": [
                        "completed",
                        "budget_hit",
                        "payment_required",
                        "tool_call_failed",
                        "lifecycle_hook_failed",
                        "missing_repo_access",
                        "missing_token_permissions",
                        "missing_sandbox_variables",
                        "blocked",
                        "contact_email_required",
                        "cancelled",
                        "interrupted",
                        "error",
                        "stopped"
                      ],
                      "type": "string"
                    },
                    "detail": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "completion_reason",
                    "detail"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "prompting": {
              "properties": {
                "blocked_reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "mention_surface",
                        "ephemeral_trigger",
                        "non_interactive",
                        "harness_single_turn",
                        "closed"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "detail": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "enabled": {
                  "type": "boolean"
                },
                "surface_name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "blocked_reason",
                "detail",
                "enabled",
                "surface_name"
              ],
              "type": "object"
            },
            "status": {
              "enum": [
                "scheduled",
                "starting",
                "working",
                "waiting",
                "retrying",
                "idle",
                "closed",
                "failed",
                "stopped",
                "cancelled"
              ],
              "type": "string"
            },
            "stopped": {
              "anyOf": [
                {
                  "properties": {
                    "at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "by": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "at",
                    "by"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "timestamps": {
              "properties": {
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "last_activity_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "last_message_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "updated_at": {
                  "format": "date-time",
                  "type": "string"
                }
              },
              "required": [
                "created_at",
                "last_activity_at",
                "last_message_at",
                "updated_at"
              ],
              "type": "object"
            }
          },
          "required": [
            "archived",
            "conversation",
            "detail",
            "interactive",
            "last_execution_result",
            "prompting",
            "status",
            "stopped",
            "timestamps"
          ],
          "type": "object"
        },
        "metadata": {
          "items": {
            "type": "string"
          },
          "default": {},
          "type": "object"
        },
        "output": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "json_schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "required": [
                "json_schema"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "parent": {
          "anyOf": [
            {
              "properties": {
                "session_id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "session_id"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "permissions": {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "anyOf": [
                {
                  "enum": [
                    true,
                    "all"
                  ]
                },
                {
                  "items": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "array"
                      }
                    ]
                  },
                  "propertyNames": {
                    "$ref": "#/components/schemas/Resource"
                  },
                  "type": "object"
                }
              ],
              "default": true
            },
            "github": {
              "additionalProperties": false,
              "properties": {
                "permissions": {
                  "anyOf": [
                    {
                      "const": "read_only",
                      "type": "string"
                    },
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "repositories": {
                  "anyOf": [
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "permissions",
                "repositories"
              ],
              "type": "object"
            }
          },
          "required": [
            "ellipsis",
            "github"
          ],
          "type": "object"
        },
        "skills": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "path": {
                "type": "string"
              },
              "repository": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "owner": {
                        "type": "object"
                      },
                      "ref": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "name",
                      "owner",
                      "ref"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "path",
              "repository"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "source": {
          "enum": [
            "react",
            "web",
            "api",
            "cli",
            "mention",
            "cron"
          ],
          "type": "string"
        },
        "summary": {
          "anyOf": [
            {
              "properties": {
                "created_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "description": {
                  "type": "string"
                }
              },
              "required": [
                "created_at",
                "description"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "tokens": {
          "properties": {
            "cache_creation": {
              "default": 0,
              "type": "integer"
            },
            "cache_read": {
              "default": 0,
              "type": "integer"
            },
            "input": {
              "default": 0,
              "type": "integer"
            },
            "model": {
              "default": "",
              "type": "string"
            },
            "output": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cache_creation",
            "cache_read",
            "input",
            "model",
            "output",
            "total"
          ],
          "type": "object"
        }
      },
      "required": [
        "agent",
        "attribution",
        "budget",
        "claude_code",
        "codex",
        "cost",
        "environment",
        "event",
        "git",
        "handler",
        "id",
        "lifecycle",
        "metadata",
        "output",
        "parent",
        "permissions",
        "skills",
        "source",
        "summary",
        "tokens"
      ],
      "type": "object"
    }
  },
  "required": [
    "session"
  ],
  "type": "object"
}
```

---

# Unlink from GitHub

> Make the agent API-managed. Its repository file stops controlling the definition.

Source: https://www.ellipsis.dev/docs/api/agents/post-agents-agent_id-unlink

## POST /v1/agents/{agent_id}/unlink

Make the agent API-managed. Its repository file stops controlling the definition.

Required permissions: write:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "agent": {
    "config": {
      "ellipsis": {
        "description": str,
        "enabled": bool,
        "kind": "agent",
        "metadata": {
          "annotations": {
            "[str]": str
          },
          "labels": [
            str
          ]
        },
        "name": str,
        "version": str
      },
      "input": {
        "json_schema": {
          "[str]": any
        },
        "message": str
      },
      "session": {
        "budget": {
          "day": float,
          "month": float,
          "session": float,
          "week": float
        },
        "claude_code": {
          "effort": str,
          "fallback_model": str,
          "max_turns": int,
          "model": str,
          "prompt": str,
          "settings": {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        },
        "codex": {
          "effort": str,
          "model": str,
          "prompt": str
        },
        "environment": { # str
          "compute": {
            "cpu": int,
            "memory": { # str | null
              "gb": int,
              "mb": int
            },
            "timeout": { # str | null
              "hours": int,
              "minutes": int,
              "seconds": int
            }
          },
          "hooks": {
            "after_checkout": { # str | null
              "run": str
            },
            "before_start": { # str | null
              "run": str
            },
            "build_base": { # str | null
              "inputs": [
                str
              ],
              "run": str
            },
            "post_clone": str,
            "post_start": str
          },
          "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
          # McpRemoteServer]
            {
              "args": [
                str
              ],
              "command": str,
              "env": {
                "[str]": str
              },
              "name": str
            }
          ],
          "repositories": [
            {
              "name": str,
              "owner": str,
              "ref": str
            }
          ],
          "variables": [
            {
              "name": str,
              "value": str
            }
          ]
        },
        "output": {
          "json_schema": {
            "[str]": any
          }
        },
        "permissions": {
          "ellipsis": { # bool | str
            "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
              {
                "level": str,
                "match": [
                  str
                ]
              }
            ]
          },
          "github": {
            "permissions": { # "read_only" | null
              "[str]": str
            },
            "repositories": [
              str
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "linear_issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ]
        },
        "pull_request": {
          "base": [
            str
          ],
          "draft": bool,
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "head": [
            str
          ],
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "push": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "type": "react"
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "id": str,
    "last_session_created_at": str,
    "last_session_id": str,
    "last_sync_error": str,
    "last_synced_commit_sha": str,
    "managed_by": str,
    "name": str,
    "pending_pull_request_url": str,
    "sha": str,
    "source_details": {
      "branch": str,
      "path": str,
      "repo_id": int
    },
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.agents.unlink("check-tests")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.agents.unlink("check-tests");
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/agents/{agent_id}/unlink" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "agent": {
      "properties": {
        "config": {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "additionalProperties": false,
              "properties": {
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "enabled": {
                  "default": true,
                  "type": "boolean"
                },
                "kind": {
                  "const": "agent",
                  "type": "string"
                },
                "metadata": {
                  "additionalProperties": false,
                  "properties": {
                    "annotations": {
                      "items": {
                        "type": "string"
                      },
                      "default": {},
                      "type": "object"
                    },
                    "labels": {
                      "default": [],
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "annotations",
                    "labels"
                  ],
                  "type": "object"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "version": {
                  "default": "v1",
                  "type": "string"
                }
              },
              "required": [
                "description",
                "enabled",
                "kind",
                "metadata",
                "name",
                "version"
              ],
              "type": "object"
            },
            "input": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "json_schema": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "message": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "json_schema",
                    "message"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "session": {
              "additionalProperties": false,
              "allOf": [
                {
                  "oneOf": [
                    {
                      "properties": {
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "null"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    },
                    {
                      "properties": {
                        "claude_code": {
                          "type": "null"
                        },
                        "codex": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    }
                  ]
                }
              ],
              "properties": {
                "budget": {
                  "additionalProperties": false,
                  "properties": {
                    "day": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "month": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "session": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "week": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "day",
                    "month",
                    "session",
                    "week"
                  ],
                  "type": "object"
                },
                "claude_code": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "fallback_model": {
                          "type": "object"
                        },
                        "max_turns": {
                          "type": "object"
                        },
                        "model": {
                          "type": "object"
                        },
                        "prompt": {
                          "type": "object"
                        },
                        "settings": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "fallback_model",
                        "max_turns",
                        "model",
                        "prompt",
                        "settings"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "codex": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "model": {
                          "type": "string"
                        },
                        "prompt": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "model",
                        "prompt"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "environment": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "compute": {
                          "type": "object"
                        },
                        "hooks": {
                          "type": "object"
                        },
                        "mcp_servers": {
                          "type": "array"
                        },
                        "repositories": {
                          "type": "array"
                        },
                        "variables": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "compute",
                        "hooks",
                        "mcp_servers",
                        "repositories",
                        "variables"
                      ],
                      "type": "object"
                    }
                  ],
                  "default": {
                    "compute": {},
                    "hooks": {},
                    "mcp_servers": [],
                    "repositories": [],
                    "variables": []
                  }
                },
                "output": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "json_schema": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "json_schema"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "permissions": {
                  "additionalProperties": false,
                  "properties": {
                    "ellipsis": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "object"
                        }
                      ],
                      "default": true
                    },
                    "github": {
                      "additionalProperties": false,
                      "properties": {
                        "permissions": {
                          "type": "object"
                        },
                        "repositories": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "permissions",
                        "repositories"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "ellipsis",
                    "github"
                  ],
                  "type": "object"
                },
                "skills": {
                  "default": [],
                  "items": {
                    "additionalProperties": false,
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "repository": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "path",
                      "repository"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "budget",
                "claude_code",
                "codex",
                "environment",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "sentry",
                        "slack_channel",
                        "type"
                      ],
                      "type": "object"
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "ellipsis",
            "input",
            "session",
            "trigger"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "edited_by": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "last_session_created_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_session_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_sync_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_synced_commit_sha": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "managed_by": {
          "enum": [
            "github",
            "api"
          ],
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "pending_pull_request_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "sha": {
          "type": "string"
        },
        "source_details": {
          "anyOf": [
            {
              "properties": {
                "branch": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "repo_id": {
                  "type": "integer"
                }
              },
              "required": [
                "repo_id",
                "path",
                "branch"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "id",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config"
      ],
      "type": "object"
    }
  },
  "required": [
    "agent"
  ],
  "type": "object"
}
```

---

# Create an agent

> Create an API-managed agent. It is live immediately.

Source: https://www.ellipsis.dev/docs/api/agents/post-agents

## POST /v1/agents

Create an API-managed agent. It is live immediately.

Required permissions: write:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Request

```text
{
  "agent": {
    "ellipsis": {
      "description": str,
      "enabled": bool,
      "kind": "agent",
      "metadata": {
        "annotations": {
          "[str]": str
        },
        "labels": [
          str
        ]
      },
      "name": str,
      "version": str
    },
    "input": {
      "json_schema": {
        "[str]": any
      },
      "message": str
    },
    "session": {
      "budget": {
        "day": float,
        "month": float,
        "session": float,
        "week": float
      },
      "claude_code": {
        "effort": str,
        "fallback_model": str,
        "max_turns": int,
        "model": str,
        "prompt": str,
        "settings": {
          "path": str,
          "repository": {
            "name": str,
            "owner": str,
            "ref": str
          }
        }
      },
      "codex": {
        "effort": str,
        "model": str,
        "prompt": str
      },
      "environment": { # str
        "compute": {
          "cpu": int,
          "memory": { # str | null
            "gb": int,
            "mb": int
          },
          "timeout": { # str | null
            "hours": int,
            "minutes": int,
            "seconds": int
          }
        },
        "hooks": {
          "after_checkout": { # str | null
            "run": str
          },
          "before_start": { # str | null
            "run": str
          },
          "build_base": { # str | null
            "inputs": [
              str
            ],
            "run": str
          },
          "post_clone": str,
          "post_start": str
        },
        "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
        # McpRemoteServer]
          {
            "args": [
              str
            ],
            "command": str,
            "env": {
              "[str]": str
            },
            "name": str
          }
        ],
        "repositories": [
          {
            "name": str,
            "owner": str,
            "ref": str
          }
        ],
        "variables": [
          {
            "name": str,
            "value": str
          }
        ]
      },
      "output": {
        "json_schema": {
          "[str]": any
        }
      },
      "permissions": {
        "ellipsis": { # bool | str
          "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
            {
              "level": str,
              "match": [
                str
              ]
            }
          ]
        },
        "github": {
          "permissions": { # "read_only" | null
            "[str]": str
          },
          "repositories": [
            str
          ]
        }
      },
      "skills": [
        {
          "path": str,
          "repository": {
            "name": str,
            "owner": str,
            "ref": str
          }
        }
      ]
    },
    "trigger": { # null | ReactTrigger | CronTrigger
      "issue": {
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "labels": [
          str
        ],
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "linear_issue": {
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "on": [
          str
        ]
      },
      "pull_request": {
        "base": [
          str
        ],
        "draft": bool,
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "head": [
          str
        ],
        "labels": [
          str
        ],
        "on": [
          str
        ],
        "paths": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "push": {
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "paths": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "sentry": {
        "on": [
          str
        ],
        "projects": [
          str
        ]
      },
      "slack_channel": {},
      "type": "react"
    }
  }
}
```

### Response

```text
{
  "agent": {
    "config": {
      "ellipsis": {
        "description": str,
        "enabled": bool,
        "kind": "agent",
        "metadata": {
          "annotations": {
            "[str]": str
          },
          "labels": [
            str
          ]
        },
        "name": str,
        "version": str
      },
      "input": {
        "json_schema": {
          "[str]": any
        },
        "message": str
      },
      "session": {
        "budget": {
          "day": float,
          "month": float,
          "session": float,
          "week": float
        },
        "claude_code": {
          "effort": str,
          "fallback_model": str,
          "max_turns": int,
          "model": str,
          "prompt": str,
          "settings": {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        },
        "codex": {
          "effort": str,
          "model": str,
          "prompt": str
        },
        "environment": { # str
          "compute": {
            "cpu": int,
            "memory": { # str | null
              "gb": int,
              "mb": int
            },
            "timeout": { # str | null
              "hours": int,
              "minutes": int,
              "seconds": int
            }
          },
          "hooks": {
            "after_checkout": { # str | null
              "run": str
            },
            "before_start": { # str | null
              "run": str
            },
            "build_base": { # str | null
              "inputs": [
                str
              ],
              "run": str
            },
            "post_clone": str,
            "post_start": str
          },
          "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
          # McpRemoteServer]
            {
              "args": [
                str
              ],
              "command": str,
              "env": {
                "[str]": str
              },
              "name": str
            }
          ],
          "repositories": [
            {
              "name": str,
              "owner": str,
              "ref": str
            }
          ],
          "variables": [
            {
              "name": str,
              "value": str
            }
          ]
        },
        "output": {
          "json_schema": {
            "[str]": any
          }
        },
        "permissions": {
          "ellipsis": { # bool | str
            "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
              {
                "level": str,
                "match": [
                  str
                ]
              }
            ]
          },
          "github": {
            "permissions": { # "read_only" | null
              "[str]": str
            },
            "repositories": [
              str
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "linear_issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ]
        },
        "pull_request": {
          "base": [
            str
          ],
          "draft": bool,
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "head": [
            str
          ],
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "push": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "type": "react"
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "id": str,
    "last_session_created_at": str,
    "last_session_id": str,
    "last_sync_error": str,
    "last_synced_commit_sha": str,
    "managed_by": str,
    "name": str,
    "pending_pull_request_url": str,
    "sha": str,
    "source_details": {
      "branch": str,
      "path": str,
      "repo_id": int
    },
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.CreateAgentRequest.model_validate(
    {
      "agent": {
        "ellipsis": {
          "kind": "agent",
          "name": "check-tests",
          "version": "v1",
          "enabled": True,
          "metadata": {
            "labels": [],
            "annotations": {}
          }
        },
        "session": {
          "claude_code": {
            "prompt": "Run the tests and report failures."
          },
          "environment": "api-environment",
          "budget": {
            "session": 3
          },
          "permissions": {
            "github": {},
            "ellipsis": True
          },
          "skills": []
        }
      }
    }
)

result = client.agents.create(request.agent)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.agents.create>[0] = {
  "agent": {
    "ellipsis": {
      "kind": "agent",
      "name": "check-tests",
      "version": "v1",
      "enabled": true,
      "metadata": {
        "labels": [],
        "annotations": {}
      }
    },
    "session": {
      "claude_code": {
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "budget": {
        "session": 3
      },
      "permissions": {
        "github": {},
        "ellipsis": true
      },
      "skills": []
    }
  }
};

const result = await client.agents.create(request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/agents" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": {
    "ellipsis": {
      "kind": "agent",
      "name": "check-tests",
      "version": "v1",
      "enabled": true,
      "metadata": {
        "labels": [],
        "annotations": {}
      }
    },
    "session": {
      "claude_code": {
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "budget": {
        "session": 3
      },
      "permissions": {
        "github": {},
        "ellipsis": true
      },
      "skills": []
    }
  }
}'
```

### Request schema

```json
{
  "properties": {
    "agent": {
      "additionalProperties": false,
      "properties": {
        "ellipsis": {
          "additionalProperties": false,
          "properties": {
            "description": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "enabled": {
              "default": true,
              "type": "boolean"
            },
            "kind": {
              "const": "agent",
              "type": "string"
            },
            "metadata": {
              "additionalProperties": false,
              "properties": {
                "annotations": {
                  "items": {
                    "type": "string"
                  },
                  "default": {},
                  "type": "object"
                },
                "labels": {
                  "default": [],
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "version": {
              "default": "v1",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        "input": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "json_schema": {
                  "anyOf": [
                    {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "message": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "session": {
          "additionalProperties": false,
          "allOf": [
            {
              "oneOf": [
                {
                  "properties": {
                    "claude_code": {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    "codex": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "claude_code"
                  ]
                },
                {
                  "properties": {
                    "claude_code": {
                      "type": "null"
                    },
                    "codex": {
                      "additionalProperties": true,
                      "type": "object"
                    }
                  },
                  "required": [
                    "codex"
                  ]
                }
              ]
            }
          ],
          "properties": {
            "budget": {
              "additionalProperties": false,
              "properties": {
                "day": {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "month": {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "session": {
                  "anyOf": [
                    {
                      "exclusiveMinimum": 0,
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "week": {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "type": "object"
            },
            "claude_code": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "effort": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "fallback_model": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "max_turns": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "model": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "prompt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "settings": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "codex": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "effort": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "model": {
                      "default": "gpt-5.6-terra",
                      "type": "string"
                    },
                    "prompt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "environment": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "compute": {
                      "additionalProperties": false,
                      "properties": {
                        "cpu": {
                          "type": "object"
                        },
                        "memory": {
                          "type": "object"
                        },
                        "timeout": {
                          "type": "object"
                        }
                      },
                      "type": "object"
                    },
                    "hooks": {
                      "additionalProperties": false,
                      "properties": {
                        "after_checkout": {
                          "type": "object"
                        },
                        "before_start": {
                          "type": "object"
                        },
                        "build_base": {
                          "type": "object"
                        },
                        "post_clone": {
                          "type": "object"
                        },
                        "post_start": {
                          "type": "object"
                        }
                      },
                      "type": "object"
                    },
                    "mcp_servers": {
                      "default": [],
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "repositories": {
                      "default": [],
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "variables": {
                      "default": [],
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              ],
              "default": {
                "compute": {},
                "hooks": {},
                "mcp_servers": [],
                "repositories": [],
                "variables": []
              }
            },
            "output": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "json_schema": {
                      "additionalProperties": true,
                      "type": "object"
                    }
                  },
                  "required": [
                    "json_schema"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "permissions": {
              "additionalProperties": false,
              "properties": {
                "ellipsis": {
                  "anyOf": [
                    {
                      "enum": [
                        true,
                        "all"
                      ]
                    },
                    {
                      "items": {
                        "type": "object"
                      },
                      "propertyNames": {
                        "$ref": "#/components/schemas/Resource"
                      },
                      "type": "object"
                    }
                  ],
                  "default": true
                },
                "github": {
                  "additionalProperties": false,
                  "properties": {
                    "permissions": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repositories": {
                      "anyOf": [
                        {
                          "type": "array"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                }
              },
              "type": "object"
            },
            "skills": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "path": {
                    "type": "string"
                  },
                  "repository": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "path"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "type": "object"
        },
        "trigger": {
          "anyOf": [
            {
              "oneOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "schedule": {
                      "type": "string"
                    },
                    "type": {
                      "const": "cron",
                      "default": "cron",
                      "type": "string"
                    }
                  },
                  "required": [
                    "schedule"
                  ],
                  "type": "object"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "issue": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "linear_issue": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "pull_request": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "push": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "sentry": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "slack_channel": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "react",
                      "default": "react",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "ellipsis",
        "session"
      ],
      "type": "object"
    }
  },
  "required": [
    "agent"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "agent": {
      "properties": {
        "config": {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "additionalProperties": false,
              "properties": {
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "enabled": {
                  "default": true,
                  "type": "boolean"
                },
                "kind": {
                  "const": "agent",
                  "type": "string"
                },
                "metadata": {
                  "additionalProperties": false,
                  "properties": {
                    "annotations": {
                      "items": {
                        "type": "string"
                      },
                      "default": {},
                      "type": "object"
                    },
                    "labels": {
                      "default": [],
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "annotations",
                    "labels"
                  ],
                  "type": "object"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "version": {
                  "default": "v1",
                  "type": "string"
                }
              },
              "required": [
                "description",
                "enabled",
                "kind",
                "metadata",
                "name",
                "version"
              ],
              "type": "object"
            },
            "input": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "json_schema": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "message": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "json_schema",
                    "message"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "session": {
              "additionalProperties": false,
              "allOf": [
                {
                  "oneOf": [
                    {
                      "properties": {
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "null"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    },
                    {
                      "properties": {
                        "claude_code": {
                          "type": "null"
                        },
                        "codex": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    }
                  ]
                }
              ],
              "properties": {
                "budget": {
                  "additionalProperties": false,
                  "properties": {
                    "day": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "month": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "session": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "week": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "day",
                    "month",
                    "session",
                    "week"
                  ],
                  "type": "object"
                },
                "claude_code": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "fallback_model": {
                          "type": "object"
                        },
                        "max_turns": {
                          "type": "object"
                        },
                        "model": {
                          "type": "object"
                        },
                        "prompt": {
                          "type": "object"
                        },
                        "settings": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "fallback_model",
                        "max_turns",
                        "model",
                        "prompt",
                        "settings"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "codex": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "model": {
                          "type": "string"
                        },
                        "prompt": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "model",
                        "prompt"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "environment": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "compute": {
                          "type": "object"
                        },
                        "hooks": {
                          "type": "object"
                        },
                        "mcp_servers": {
                          "type": "array"
                        },
                        "repositories": {
                          "type": "array"
                        },
                        "variables": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "compute",
                        "hooks",
                        "mcp_servers",
                        "repositories",
                        "variables"
                      ],
                      "type": "object"
                    }
                  ],
                  "default": {
                    "compute": {},
                    "hooks": {},
                    "mcp_servers": [],
                    "repositories": [],
                    "variables": []
                  }
                },
                "output": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "json_schema": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "json_schema"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "permissions": {
                  "additionalProperties": false,
                  "properties": {
                    "ellipsis": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "object"
                        }
                      ],
                      "default": true
                    },
                    "github": {
                      "additionalProperties": false,
                      "properties": {
                        "permissions": {
                          "type": "object"
                        },
                        "repositories": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "permissions",
                        "repositories"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "ellipsis",
                    "github"
                  ],
                  "type": "object"
                },
                "skills": {
                  "default": [],
                  "items": {
                    "additionalProperties": false,
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "repository": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "path",
                      "repository"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "budget",
                "claude_code",
                "codex",
                "environment",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "sentry",
                        "slack_channel",
                        "type"
                      ],
                      "type": "object"
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "ellipsis",
            "input",
            "session",
            "trigger"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "edited_by": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "last_session_created_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_session_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_sync_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_synced_commit_sha": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "managed_by": {
          "enum": [
            "github",
            "api"
          ],
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "pending_pull_request_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "sha": {
          "type": "string"
        },
        "source_details": {
          "anyOf": [
            {
              "properties": {
                "branch": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "repo_id": {
                  "type": "integer"
                }
              },
              "required": [
                "repo_id",
                "path",
                "branch"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "id",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config"
      ],
      "type": "object"
    }
  },
  "required": [
    "agent"
  ],
  "type": "object"
}
```

---

# Update an agent

> Replace an API-managed agent definition. Edit git-managed definitions in their repository or unlink them first.

Source: https://www.ellipsis.dev/docs/api/agents/put-agents-agent_id

## PUT /v1/agents/{agent_id}

Replace an API-managed agent definition. Edit git-managed definitions in their repository or unlink them first.

Required permissions: write:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Request

```text
{
  "agent": {
    "ellipsis": {
      "description": str,
      "enabled": bool,
      "kind": "agent",
      "metadata": {
        "annotations": {
          "[str]": str
        },
        "labels": [
          str
        ]
      },
      "name": str,
      "version": str
    },
    "input": {
      "json_schema": {
        "[str]": any
      },
      "message": str
    },
    "session": {
      "budget": {
        "day": float,
        "month": float,
        "session": float,
        "week": float
      },
      "claude_code": {
        "effort": str,
        "fallback_model": str,
        "max_turns": int,
        "model": str,
        "prompt": str,
        "settings": {
          "path": str,
          "repository": {
            "name": str,
            "owner": str,
            "ref": str
          }
        }
      },
      "codex": {
        "effort": str,
        "model": str,
        "prompt": str
      },
      "environment": { # str
        "compute": {
          "cpu": int,
          "memory": { # str | null
            "gb": int,
            "mb": int
          },
          "timeout": { # str | null
            "hours": int,
            "minutes": int,
            "seconds": int
          }
        },
        "hooks": {
          "after_checkout": { # str | null
            "run": str
          },
          "before_start": { # str | null
            "run": str
          },
          "build_base": { # str | null
            "inputs": [
              str
            ],
            "run": str
          },
          "post_clone": str,
          "post_start": str
        },
        "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
        # McpRemoteServer]
          {
            "args": [
              str
            ],
            "command": str,
            "env": {
              "[str]": str
            },
            "name": str
          }
        ],
        "repositories": [
          {
            "name": str,
            "owner": str,
            "ref": str
          }
        ],
        "variables": [
          {
            "name": str,
            "value": str
          }
        ]
      },
      "output": {
        "json_schema": {
          "[str]": any
        }
      },
      "permissions": {
        "ellipsis": { # bool | str
          "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
            {
              "level": str,
              "match": [
                str
              ]
            }
          ]
        },
        "github": {
          "permissions": { # "read_only" | null
            "[str]": str
          },
          "repositories": [
            str
          ]
        }
      },
      "skills": [
        {
          "path": str,
          "repository": {
            "name": str,
            "owner": str,
            "ref": str
          }
        }
      ]
    },
    "trigger": { # null | ReactTrigger | CronTrigger
      "issue": {
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "labels": [
          str
        ],
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "linear_issue": {
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "on": [
          str
        ]
      },
      "pull_request": {
        "base": [
          str
        ],
        "draft": bool,
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "head": [
          str
        ],
        "labels": [
          str
        ],
        "on": [
          str
        ],
        "paths": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "push": {
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "paths": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "sentry": {
        "on": [
          str
        ],
        "projects": [
          str
        ]
      },
      "slack_channel": {},
      "type": "react"
    }
  }
}
```

### Response

```text
{
  "agent": {
    "config": {
      "ellipsis": {
        "description": str,
        "enabled": bool,
        "kind": "agent",
        "metadata": {
          "annotations": {
            "[str]": str
          },
          "labels": [
            str
          ]
        },
        "name": str,
        "version": str
      },
      "input": {
        "json_schema": {
          "[str]": any
        },
        "message": str
      },
      "session": {
        "budget": {
          "day": float,
          "month": float,
          "session": float,
          "week": float
        },
        "claude_code": {
          "effort": str,
          "fallback_model": str,
          "max_turns": int,
          "model": str,
          "prompt": str,
          "settings": {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        },
        "codex": {
          "effort": str,
          "model": str,
          "prompt": str
        },
        "environment": { # str
          "compute": {
            "cpu": int,
            "memory": { # str | null
              "gb": int,
              "mb": int
            },
            "timeout": { # str | null
              "hours": int,
              "minutes": int,
              "seconds": int
            }
          },
          "hooks": {
            "after_checkout": { # str | null
              "run": str
            },
            "before_start": { # str | null
              "run": str
            },
            "build_base": { # str | null
              "inputs": [
                str
              ],
              "run": str
            },
            "post_clone": str,
            "post_start": str
          },
          "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
          # McpRemoteServer]
            {
              "args": [
                str
              ],
              "command": str,
              "env": {
                "[str]": str
              },
              "name": str
            }
          ],
          "repositories": [
            {
              "name": str,
              "owner": str,
              "ref": str
            }
          ],
          "variables": [
            {
              "name": str,
              "value": str
            }
          ]
        },
        "output": {
          "json_schema": {
            "[str]": any
          }
        },
        "permissions": {
          "ellipsis": { # bool | str
            "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
              {
                "level": str,
                "match": [
                  str
                ]
              }
            ]
          },
          "github": {
            "permissions": { # "read_only" | null
              "[str]": str
            },
            "repositories": [
              str
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "linear_issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ]
        },
        "pull_request": {
          "base": [
            str
          ],
          "draft": bool,
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "head": [
            str
          ],
          "labels": [
            str
          ],
          "on": [
            str
          ],
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "push": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "type": "react"
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "id": str,
    "last_session_created_at": str,
    "last_session_id": str,
    "last_sync_error": str,
    "last_synced_commit_sha": str,
    "managed_by": str,
    "name": str,
    "pending_pull_request_url": str,
    "sha": str,
    "source_details": {
      "branch": str,
      "path": str,
      "repo_id": int
    },
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.UpdateAgentRequest.model_validate(
    {
      "agent": {
        "ellipsis": {
          "kind": "agent",
          "name": "check-tests",
          "version": "v1",
          "enabled": True,
          "metadata": {
            "labels": [],
            "annotations": {}
          }
        },
        "session": {
          "claude_code": {
            "prompt": "Run the tests and report failures."
          },
          "environment": "api-environment",
          "budget": {
            "session": 3
          },
          "permissions": {
            "github": {},
            "ellipsis": True
          },
          "skills": []
        }
      }
    }
)

result = client.agents.update("check-tests", request.agent)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.agents.update>[1] = {
  "agent": {
    "ellipsis": {
      "kind": "agent",
      "name": "check-tests",
      "version": "v1",
      "enabled": true,
      "metadata": {
        "labels": [],
        "annotations": {}
      }
    },
    "session": {
      "claude_code": {
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "budget": {
        "session": 3
      },
      "permissions": {
        "github": {},
        "ellipsis": true
      },
      "skills": []
    }
  }
};

const result = await client.agents.update("check-tests", request);
console.log(result);
```

### cURL

```bash
curl -X PUT "https://api.ellipsis.dev/v1/agents/{agent_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": {
    "ellipsis": {
      "kind": "agent",
      "name": "check-tests",
      "version": "v1",
      "enabled": true,
      "metadata": {
        "labels": [],
        "annotations": {}
      }
    },
    "session": {
      "claude_code": {
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "budget": {
        "session": 3
      },
      "permissions": {
        "github": {},
        "ellipsis": true
      },
      "skills": []
    }
  }
}'
```

### Request schema

```json
{
  "properties": {
    "agent": {
      "additionalProperties": false,
      "properties": {
        "ellipsis": {
          "additionalProperties": false,
          "properties": {
            "description": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "enabled": {
              "default": true,
              "type": "boolean"
            },
            "kind": {
              "const": "agent",
              "type": "string"
            },
            "metadata": {
              "additionalProperties": false,
              "properties": {
                "annotations": {
                  "items": {
                    "type": "string"
                  },
                  "default": {},
                  "type": "object"
                },
                "labels": {
                  "default": [],
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "version": {
              "default": "v1",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        "input": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "json_schema": {
                  "anyOf": [
                    {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "message": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "session": {
          "additionalProperties": false,
          "allOf": [
            {
              "oneOf": [
                {
                  "properties": {
                    "claude_code": {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    "codex": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "claude_code"
                  ]
                },
                {
                  "properties": {
                    "claude_code": {
                      "type": "null"
                    },
                    "codex": {
                      "additionalProperties": true,
                      "type": "object"
                    }
                  },
                  "required": [
                    "codex"
                  ]
                }
              ]
            }
          ],
          "properties": {
            "budget": {
              "additionalProperties": false,
              "properties": {
                "day": {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "month": {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "session": {
                  "anyOf": [
                    {
                      "exclusiveMinimum": 0,
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "week": {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "type": "object"
            },
            "claude_code": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "effort": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "fallback_model": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "max_turns": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "model": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "prompt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "settings": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "codex": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "effort": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "model": {
                      "default": "gpt-5.6-terra",
                      "type": "string"
                    },
                    "prompt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "environment": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "compute": {
                      "additionalProperties": false,
                      "properties": {
                        "cpu": {
                          "type": "object"
                        },
                        "memory": {
                          "type": "object"
                        },
                        "timeout": {
                          "type": "object"
                        }
                      },
                      "type": "object"
                    },
                    "hooks": {
                      "additionalProperties": false,
                      "properties": {
                        "after_checkout": {
                          "type": "object"
                        },
                        "before_start": {
                          "type": "object"
                        },
                        "build_base": {
                          "type": "object"
                        },
                        "post_clone": {
                          "type": "object"
                        },
                        "post_start": {
                          "type": "object"
                        }
                      },
                      "type": "object"
                    },
                    "mcp_servers": {
                      "default": [],
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "repositories": {
                      "default": [],
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "variables": {
                      "default": [],
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              ],
              "default": {
                "compute": {},
                "hooks": {},
                "mcp_servers": [],
                "repositories": [],
                "variables": []
              }
            },
            "output": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "json_schema": {
                      "additionalProperties": true,
                      "type": "object"
                    }
                  },
                  "required": [
                    "json_schema"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "permissions": {
              "additionalProperties": false,
              "properties": {
                "ellipsis": {
                  "anyOf": [
                    {
                      "enum": [
                        true,
                        "all"
                      ]
                    },
                    {
                      "items": {
                        "type": "object"
                      },
                      "propertyNames": {
                        "$ref": "#/components/schemas/Resource"
                      },
                      "type": "object"
                    }
                  ],
                  "default": true
                },
                "github": {
                  "additionalProperties": false,
                  "properties": {
                    "permissions": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repositories": {
                      "anyOf": [
                        {
                          "type": "array"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                }
              },
              "type": "object"
            },
            "skills": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "path": {
                    "type": "string"
                  },
                  "repository": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "path"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "type": "object"
        },
        "trigger": {
          "anyOf": [
            {
              "oneOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "schedule": {
                      "type": "string"
                    },
                    "type": {
                      "const": "cron",
                      "default": "cron",
                      "type": "string"
                    }
                  },
                  "required": [
                    "schedule"
                  ],
                  "type": "object"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "issue": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "linear_issue": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "pull_request": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "push": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "sentry": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "slack_channel": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "react",
                      "default": "react",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "ellipsis",
        "session"
      ],
      "type": "object"
    }
  },
  "required": [
    "agent"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "agent": {
      "properties": {
        "config": {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "additionalProperties": false,
              "properties": {
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "enabled": {
                  "default": true,
                  "type": "boolean"
                },
                "kind": {
                  "const": "agent",
                  "type": "string"
                },
                "metadata": {
                  "additionalProperties": false,
                  "properties": {
                    "annotations": {
                      "items": {
                        "type": "string"
                      },
                      "default": {},
                      "type": "object"
                    },
                    "labels": {
                      "default": [],
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "annotations",
                    "labels"
                  ],
                  "type": "object"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "version": {
                  "default": "v1",
                  "type": "string"
                }
              },
              "required": [
                "description",
                "enabled",
                "kind",
                "metadata",
                "name",
                "version"
              ],
              "type": "object"
            },
            "input": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "json_schema": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "message": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "json_schema",
                    "message"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "session": {
              "additionalProperties": false,
              "allOf": [
                {
                  "oneOf": [
                    {
                      "properties": {
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "null"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    },
                    {
                      "properties": {
                        "claude_code": {
                          "type": "null"
                        },
                        "codex": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "claude_code",
                        "codex"
                      ]
                    }
                  ]
                }
              ],
              "properties": {
                "budget": {
                  "additionalProperties": false,
                  "properties": {
                    "day": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "month": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "session": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "week": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "day",
                    "month",
                    "session",
                    "week"
                  ],
                  "type": "object"
                },
                "claude_code": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "fallback_model": {
                          "type": "object"
                        },
                        "max_turns": {
                          "type": "object"
                        },
                        "model": {
                          "type": "object"
                        },
                        "prompt": {
                          "type": "object"
                        },
                        "settings": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "fallback_model",
                        "max_turns",
                        "model",
                        "prompt",
                        "settings"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "codex": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "effort": {
                          "type": "object"
                        },
                        "model": {
                          "type": "string"
                        },
                        "prompt": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "effort",
                        "model",
                        "prompt"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "environment": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "compute": {
                          "type": "object"
                        },
                        "hooks": {
                          "type": "object"
                        },
                        "mcp_servers": {
                          "type": "array"
                        },
                        "repositories": {
                          "type": "array"
                        },
                        "variables": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "compute",
                        "hooks",
                        "mcp_servers",
                        "repositories",
                        "variables"
                      ],
                      "type": "object"
                    }
                  ],
                  "default": {
                    "compute": {},
                    "hooks": {},
                    "mcp_servers": [],
                    "repositories": [],
                    "variables": []
                  }
                },
                "output": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "json_schema": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "json_schema"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "permissions": {
                  "additionalProperties": false,
                  "properties": {
                    "ellipsis": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "object"
                        }
                      ],
                      "default": true
                    },
                    "github": {
                      "additionalProperties": false,
                      "properties": {
                        "permissions": {
                          "type": "object"
                        },
                        "repositories": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "permissions",
                        "repositories"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "ellipsis",
                    "github"
                  ],
                  "type": "object"
                },
                "skills": {
                  "default": [],
                  "items": {
                    "additionalProperties": false,
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "repository": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "path",
                      "repository"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "budget",
                "claude_code",
                "codex",
                "environment",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "sentry",
                        "slack_channel",
                        "type"
                      ],
                      "type": "object"
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "ellipsis",
            "input",
            "session",
            "trigger"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "edited_by": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "last_session_created_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_session_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_sync_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_synced_commit_sha": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "managed_by": {
          "enum": [
            "github",
            "api"
          ],
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "pending_pull_request_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "sha": {
          "type": "string"
        },
        "source_details": {
          "anyOf": [
            {
              "properties": {
                "branch": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "repo_id": {
                  "type": "integer"
                }
              },
              "required": [
                "repo_id",
                "path",
                "branch"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "id",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config"
      ],
      "type": "object"
    }
  },
  "required": [
    "agent"
  ],
  "type": "object"
}
```

---

# Delete an environment

> Delete an API-managed environment. New sessions referencing it will fail.

Source: https://www.ellipsis.dev/docs/api/environments/delete-environments-environment_id

## DELETE /v1/environments/{environment_id}

Delete an API-managed environment. New sessions referencing it will fail.

Required permissions: delete:environments.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.environments.delete("api-environment")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.environments.delete("api-environment");
console.log(result);
```

### cURL

```bash
curl -X DELETE "https://api.ellipsis.dev/v1/environments/{environment_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

---

# Get an environment

> Read an environment definition.

Source: https://www.ellipsis.dev/docs/api/environments/get-environments-environment_id

## GET /v1/environments/{environment_id}

Read an environment definition.

Required permissions: read:environments.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "environment": {
    "created_at": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "environment": {
      "compute": {
        "cpu": int,
        "memory": { # str | null
          "gb": int,
          "mb": int
        },
        "timeout": { # str | null
          "hours": int,
          "minutes": int,
          "seconds": int
        }
      },
      "ellipsis": {
        "description": str,
        "kind": "environment",
        "metadata": {
          "annotations": {
            "[str]": str
          },
          "labels": [
            str
          ]
        },
        "name": str
      },
      "hooks": {
        "after_checkout": { # str | null
          "run": str
        },
        "before_start": { # str | null
          "run": str
        },
        "build_base": { # str | null
          "inputs": [
            str
          ],
          "run": str
        },
        "post_clone": str,
        "post_start": str
      },
      "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
      # McpRemoteServer]
        {
          "args": [
            str
          ],
          "command": str,
          "env": {
            "[str]": str
          },
          "name": str
        }
      ],
      "repositories": [
        {
          "name": str,
          "owner": str,
          "ref": str
        }
      ],
      "variables": [
        {
          "name": str,
          "value": str
        }
      ]
    },
    "id": str,
    "last_sync_error": str,
    "last_synced_commit_sha": str,
    "managed_by": str,
    "name": str,
    "sha": str,
    "source_details": {
      "branch": str,
      "path": str,
      "repo_id": int
    },
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.environments.get("api-environment")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.environments.get("api-environment");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/environments/{environment_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "environment": {
      "properties": {
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "edited_by": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "environment": {
          "additionalProperties": false,
          "properties": {
            "compute": {
              "additionalProperties": false,
              "properties": {
                "cpu": {
                  "anyOf": [
                    {
                      "maximum": 32,
                      "minimum": 2,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "memory": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "gb": {
                          "type": "object"
                        },
                        "mb": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "gb",
                        "mb"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "timeout": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "hours": {
                          "type": "object"
                        },
                        "minutes": {
                          "type": "object"
                        },
                        "seconds": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "hours",
                        "minutes",
                        "seconds"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "cpu",
                "memory",
                "timeout"
              ],
              "type": "object"
            },
            "ellipsis": {
              "additionalProperties": false,
              "properties": {
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "kind": {
                  "const": "environment",
                  "type": "string"
                },
                "metadata": {
                  "additionalProperties": false,
                  "properties": {
                    "annotations": {
                      "items": {
                        "type": "string"
                      },
                      "default": {},
                      "type": "object"
                    },
                    "labels": {
                      "default": [],
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "annotations",
                    "labels"
                  ],
                  "type": "object"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "kind"
              ],
              "type": "object"
            },
            "hooks": {
              "additionalProperties": false,
              "properties": {
                "after_checkout": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "before_start": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "build_base": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "inputs": {
                          "type": "object"
                        },
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "inputs",
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_clone": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_start": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "after_checkout",
                "before_start",
                "build_base",
                "post_clone",
                "post_start"
              ],
              "type": "object"
            },
            "mcp_servers": {
              "default": [],
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "args": {
                        "type": "array"
                      },
                      "command": {
                        "type": "string"
                      },
                      "env": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "args",
                      "command",
                      "env",
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "headers": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "headers",
                      "name",
                      "url"
                    ],
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            },
            "repositories": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "ref": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "owner",
                  "ref"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "variables": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "value"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "ellipsis"
          ],
          "type": "object"
        },
        "id": {
          "type": "string"
        },
        "last_sync_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_synced_commit_sha": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "managed_by": {
          "enum": [
            "github",
            "api"
          ],
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "sha": {
          "type": "string"
        },
        "source_details": {
          "anyOf": [
            {
              "properties": {
                "branch": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "repo_id": {
                  "type": "integer"
                }
              },
              "required": [
                "repo_id",
                "path",
                "branch"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "environment"
      ],
      "type": "object"
    }
  },
  "required": [
    "environment"
  ],
  "type": "object"
}
```

---

# List environments

> List saved environments.

Source: https://www.ellipsis.dev/docs/api/environments/get-environments

## GET /v1/environments

List saved environments.

Required permissions: read:environments.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "environments": [
    {
      "created_at": str,
      "edited_by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "type": str
      },
      "environment": {
        "compute": {
          "cpu": int,
          "memory": { # str | null
            "gb": int,
            "mb": int
          },
          "timeout": { # str | null
            "hours": int,
            "minutes": int,
            "seconds": int
          }
        },
        "ellipsis": {
          "description": str,
          "kind": "environment",
          "metadata": {
            "annotations": {
              "[str]": str
            },
            "labels": [
              str
            ]
          },
          "name": str
        },
        "hooks": {
          "after_checkout": { # str | null
            "run": str
          },
          "before_start": { # str | null
            "run": str
          },
          "build_base": { # str | null
            "inputs": [
              str
            ],
            "run": str
          },
          "post_clone": str,
          "post_start": str
        },
        "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
        # McpRemoteServer]
          {
            "args": [
              str
            ],
            "command": str,
            "env": {
              "[str]": str
            },
            "name": str
          }
        ],
        "repositories": [
          {
            "name": str,
            "owner": str,
            "ref": str
          }
        ],
        "variables": [
          {
            "name": str,
            "value": str
          }
        ]
      },
      "id": str,
      "last_sync_error": str,
      "last_synced_commit_sha": str,
      "managed_by": str,
      "name": str,
      "sha": str,
      "source_details": {
        "branch": str,
        "path": str,
        "repo_id": int
      },
      "updated_at": str
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.environments.list()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.environments.list();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/environments" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "environments": {
      "items": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "edited_by": {
            "anyOf": [
              {
                "properties": {
                  "avatar_url": {
                    "type": "string"
                  },
                  "id": {
                    "type": "integer"
                  },
                  "login": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "User",
                      "Organization",
                      "Bot",
                      "Mannequin"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "avatar_url",
                  "id",
                  "login",
                  "type"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "environment": {
            "additionalProperties": false,
            "properties": {
              "compute": {
                "additionalProperties": false,
                "properties": {
                  "cpu": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "memory": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "timeout": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "cpu",
                  "memory",
                  "timeout"
                ],
                "type": "object"
              },
              "ellipsis": {
                "additionalProperties": false,
                "properties": {
                  "description": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "kind": {
                    "const": "environment",
                    "type": "string"
                  },
                  "metadata": {
                    "additionalProperties": false,
                    "properties": {
                      "annotations": {
                        "type": "object"
                      },
                      "labels": {
                        "type": "array"
                      }
                    },
                    "required": [
                      "annotations",
                      "labels"
                    ],
                    "type": "object"
                  },
                  "name": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "kind"
                ],
                "type": "object"
              },
              "hooks": {
                "additionalProperties": false,
                "properties": {
                  "after_checkout": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "before_start": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "build_base": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "post_clone": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "post_start": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "after_checkout",
                  "before_start",
                  "build_base",
                  "post_clone",
                  "post_start"
                ],
                "type": "object"
              },
              "mcp_servers": {
                "default": [],
                "items": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "object"
                    },
                    {
                      "type": "object"
                    },
                    {
                      "type": "object"
                    }
                  ]
                },
                "type": "array"
              },
              "repositories": {
                "default": [],
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "owner": {
                      "type": "object"
                    },
                    "ref": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "name",
                    "owner",
                    "ref"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "variables": {
                "default": [],
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "value": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "name",
                    "value"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "ellipsis"
            ],
            "type": "object"
          },
          "id": {
            "type": "string"
          },
          "last_sync_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "last_synced_commit_sha": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "managed_by": {
            "enum": [
              "github",
              "api"
            ],
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "sha": {
            "type": "string"
          },
          "source_details": {
            "anyOf": [
              {
                "properties": {
                  "branch": {
                    "type": "string"
                  },
                  "path": {
                    "type": "string"
                  },
                  "repo_id": {
                    "type": "integer"
                  }
                },
                "required": [
                  "repo_id",
                  "path",
                  "branch"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "sha",
          "created_at",
          "updated_at",
          "managed_by",
          "environment"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "environments"
  ],
  "type": "object"
}
```

---

# Environments

> Environments define where agents run. Create reusable configurations, inspect saved environments, and update or remove them.

Source: https://www.ellipsis.dev/docs/api/environments

- [`POST /v1/environments`](https://www.ellipsis.dev/docs/api/environments/post-environments): Create an environment
- [`GET /v1/environments`](https://www.ellipsis.dev/docs/api/environments/get-environments): List environments
- [`GET /v1/environments/{environment_id}`](https://www.ellipsis.dev/docs/api/environments/get-environments-environment_id): Get an environment
- [`PUT /v1/environments/{environment_id}`](https://www.ellipsis.dev/docs/api/environments/put-environments-environment_id): Update an environment
- [`DELETE /v1/environments/{environment_id}`](https://www.ellipsis.dev/docs/api/environments/delete-environments-environment_id): Delete an environment

---

# Create an environment

> Create an API-managed environment. Sessions can reference its name or ID.

Source: https://www.ellipsis.dev/docs/api/environments/post-environments

## POST /v1/environments

Create an API-managed environment. Sessions can reference its name or ID.

Required permissions: write:environments.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Request

```text
{
  "environment": {
    "compute": {
      "cpu": int,
      "memory": { # str | null
        "gb": int,
        "mb": int
      },
      "timeout": { # str | null
        "hours": int,
        "minutes": int,
        "seconds": int
      }
    },
    "ellipsis": {
      "description": str,
      "kind": "environment",
      "metadata": {
        "annotations": {
          "[str]": str
        },
        "labels": [
          str
        ]
      },
      "name": str
    },
    "hooks": {
      "after_checkout": { # str | null
        "run": str
      },
      "before_start": { # str | null
        "run": str
      },
      "build_base": { # str | null
        "inputs": [
          str
        ],
        "run": str
      },
      "post_clone": str,
      "post_start": str
    },
    "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
    # McpRemoteServer]
      {
        "args": [
          str
        ],
        "command": str,
        "env": {
          "[str]": str
        },
        "name": str
      }
    ],
    "repositories": [
      {
        "name": str,
        "owner": str,
        "ref": str
      }
    ],
    "variables": [
      {
        "name": str,
        "value": str
      }
    ]
  }
}
```

### Response

```text
{
  "environment": {
    "created_at": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "environment": {
      "compute": {
        "cpu": int,
        "memory": { # str | null
          "gb": int,
          "mb": int
        },
        "timeout": { # str | null
          "hours": int,
          "minutes": int,
          "seconds": int
        }
      },
      "ellipsis": {
        "description": str,
        "kind": "environment",
        "metadata": {
          "annotations": {
            "[str]": str
          },
          "labels": [
            str
          ]
        },
        "name": str
      },
      "hooks": {
        "after_checkout": { # str | null
          "run": str
        },
        "before_start": { # str | null
          "run": str
        },
        "build_base": { # str | null
          "inputs": [
            str
          ],
          "run": str
        },
        "post_clone": str,
        "post_start": str
      },
      "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
      # McpRemoteServer]
        {
          "args": [
            str
          ],
          "command": str,
          "env": {
            "[str]": str
          },
          "name": str
        }
      ],
      "repositories": [
        {
          "name": str,
          "owner": str,
          "ref": str
        }
      ],
      "variables": [
        {
          "name": str,
          "value": str
        }
      ]
    },
    "id": str,
    "last_sync_error": str,
    "last_synced_commit_sha": str,
    "managed_by": str,
    "name": str,
    "sha": str,
    "source_details": {
      "branch": str,
      "path": str,
      "repo_id": int
    },
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.CreateEnvironmentRequest.model_validate(
    {
      "environment": {
        "ellipsis": {
          "kind": "environment",
          "name": "api-environment",
          "metadata": {
            "labels": [],
            "annotations": {}
          }
        },
        "repositories": [
          {
            "name": "api-repo"
          }
        ],
        "compute": {},
        "hooks": {},
        "mcp_servers": [],
        "variables": []
      }
    }
)

result = client.environments.create(request.environment)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.environments.create>[0] = {
  "environment": {
    "ellipsis": {
      "kind": "environment",
      "name": "api-environment",
      "metadata": {
        "labels": [],
        "annotations": {}
      }
    },
    "repositories": [
      {
        "name": "api-repo"
      }
    ],
    "compute": {},
    "hooks": {},
    "mcp_servers": [],
    "variables": []
  }
};

const result = await client.environments.create(request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/environments" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "ellipsis": {
      "kind": "environment",
      "name": "api-environment",
      "metadata": {
        "labels": [],
        "annotations": {}
      }
    },
    "repositories": [
      {
        "name": "api-repo"
      }
    ],
    "compute": {},
    "hooks": {},
    "mcp_servers": [],
    "variables": []
  }
}'
```

### Request schema

```json
{
  "properties": {
    "environment": {
      "additionalProperties": false,
      "properties": {
        "compute": {
          "additionalProperties": false,
          "properties": {
            "cpu": {
              "anyOf": [
                {
                  "maximum": 32,
                  "minimum": 2,
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "memory": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "gb": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "mb": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "timeout": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "hours": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "minutes": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "seconds": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        "ellipsis": {
          "additionalProperties": false,
          "properties": {
            "description": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "kind": {
              "const": "environment",
              "type": "string"
            },
            "metadata": {
              "additionalProperties": false,
              "properties": {
                "annotations": {
                  "items": {
                    "type": "string"
                  },
                  "default": {},
                  "type": "object"
                },
                "labels": {
                  "default": [],
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        "hooks": {
          "additionalProperties": false,
          "properties": {
            "after_checkout": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "run": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "run"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "before_start": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "run": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "run"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "build_base": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "inputs": {
                      "anyOf": [
                        {
                          "type": "array"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "run": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "run"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "post_clone": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "post_start": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        "mcp_servers": {
          "default": [],
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ],
                "type": "object"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "args": {
                    "default": [],
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "command": {
                    "type": "string"
                  },
                  "env": {
                    "items": {
                      "type": "string"
                    },
                    "default": {},
                    "type": "object"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "command"
                ],
                "type": "object"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "headers": {
                    "items": {
                      "type": "string"
                    },
                    "default": {},
                    "type": "object"
                  },
                  "name": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "url"
                ],
                "type": "object"
              }
            ]
          },
          "type": "array"
        },
        "repositories": {
          "default": [],
          "items": {
            "additionalProperties": false,
            "properties": {
              "name": {
                "type": "string"
              },
              "owner": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "ref": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "variables": {
          "default": [],
          "items": {
            "additionalProperties": false,
            "properties": {
              "name": {
                "type": "string"
              },
              "value": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "ellipsis"
      ],
      "type": "object"
    }
  },
  "required": [
    "environment"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "environment": {
      "properties": {
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "edited_by": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "environment": {
          "additionalProperties": false,
          "properties": {
            "compute": {
              "additionalProperties": false,
              "properties": {
                "cpu": {
                  "anyOf": [
                    {
                      "maximum": 32,
                      "minimum": 2,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "memory": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "gb": {
                          "type": "object"
                        },
                        "mb": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "gb",
                        "mb"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "timeout": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "hours": {
                          "type": "object"
                        },
                        "minutes": {
                          "type": "object"
                        },
                        "seconds": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "hours",
                        "minutes",
                        "seconds"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "cpu",
                "memory",
                "timeout"
              ],
              "type": "object"
            },
            "ellipsis": {
              "additionalProperties": false,
              "properties": {
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "kind": {
                  "const": "environment",
                  "type": "string"
                },
                "metadata": {
                  "additionalProperties": false,
                  "properties": {
                    "annotations": {
                      "items": {
                        "type": "string"
                      },
                      "default": {},
                      "type": "object"
                    },
                    "labels": {
                      "default": [],
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "annotations",
                    "labels"
                  ],
                  "type": "object"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "kind"
              ],
              "type": "object"
            },
            "hooks": {
              "additionalProperties": false,
              "properties": {
                "after_checkout": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "before_start": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "build_base": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "inputs": {
                          "type": "object"
                        },
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "inputs",
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_clone": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_start": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "after_checkout",
                "before_start",
                "build_base",
                "post_clone",
                "post_start"
              ],
              "type": "object"
            },
            "mcp_servers": {
              "default": [],
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "args": {
                        "type": "array"
                      },
                      "command": {
                        "type": "string"
                      },
                      "env": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "args",
                      "command",
                      "env",
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "headers": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "headers",
                      "name",
                      "url"
                    ],
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            },
            "repositories": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "ref": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "owner",
                  "ref"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "variables": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "value"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "ellipsis"
          ],
          "type": "object"
        },
        "id": {
          "type": "string"
        },
        "last_sync_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_synced_commit_sha": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "managed_by": {
          "enum": [
            "github",
            "api"
          ],
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "sha": {
          "type": "string"
        },
        "source_details": {
          "anyOf": [
            {
              "properties": {
                "branch": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "repo_id": {
                  "type": "integer"
                }
              },
              "required": [
                "repo_id",
                "path",
                "branch"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "environment"
      ],
      "type": "object"
    }
  },
  "required": [
    "environment"
  ],
  "type": "object"
}
```

---

# Update an environment

> Replace an API-managed environment definition. Git-managed definitions must be edited in their repository.

Source: https://www.ellipsis.dev/docs/api/environments/put-environments-environment_id

## PUT /v1/environments/{environment_id}

Replace an API-managed environment definition. Git-managed definitions must be edited in their repository.

Required permissions: write:environments.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Request

```text
{
  "environment": {
    "compute": {
      "cpu": int,
      "memory": { # str | null
        "gb": int,
        "mb": int
      },
      "timeout": { # str | null
        "hours": int,
        "minutes": int,
        "seconds": int
      }
    },
    "ellipsis": {
      "description": str,
      "kind": "environment",
      "metadata": {
        "annotations": {
          "[str]": str
        },
        "labels": [
          str
        ]
      },
      "name": str
    },
    "hooks": {
      "after_checkout": { # str | null
        "run": str
      },
      "before_start": { # str | null
        "run": str
      },
      "build_base": { # str | null
        "inputs": [
          str
        ],
        "run": str
      },
      "post_clone": str,
      "post_start": str
    },
    "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
    # McpRemoteServer]
      {
        "args": [
          str
        ],
        "command": str,
        "env": {
          "[str]": str
        },
        "name": str
      }
    ],
    "repositories": [
      {
        "name": str,
        "owner": str,
        "ref": str
      }
    ],
    "variables": [
      {
        "name": str,
        "value": str
      }
    ]
  }
}
```

### Response

```text
{
  "environment": {
    "created_at": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "environment": {
      "compute": {
        "cpu": int,
        "memory": { # str | null
          "gb": int,
          "mb": int
        },
        "timeout": { # str | null
          "hours": int,
          "minutes": int,
          "seconds": int
        }
      },
      "ellipsis": {
        "description": str,
        "kind": "environment",
        "metadata": {
          "annotations": {
            "[str]": str
          },
          "labels": [
            str
          ]
        },
        "name": str
      },
      "hooks": {
        "after_checkout": { # str | null
          "run": str
        },
        "before_start": { # str | null
          "run": str
        },
        "build_base": { # str | null
          "inputs": [
            str
          ],
          "run": str
        },
        "post_clone": str,
        "post_start": str
      },
      "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
      # McpRemoteServer]
        {
          "args": [
            str
          ],
          "command": str,
          "env": {
            "[str]": str
          },
          "name": str
        }
      ],
      "repositories": [
        {
          "name": str,
          "owner": str,
          "ref": str
        }
      ],
      "variables": [
        {
          "name": str,
          "value": str
        }
      ]
    },
    "id": str,
    "last_sync_error": str,
    "last_synced_commit_sha": str,
    "managed_by": str,
    "name": str,
    "sha": str,
    "source_details": {
      "branch": str,
      "path": str,
      "repo_id": int
    },
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.UpdateEnvironmentRequest.model_validate(
    {
      "environment": {
        "ellipsis": {
          "kind": "environment",
          "name": "api-environment",
          "metadata": {
            "labels": [],
            "annotations": {}
          }
        },
        "repositories": [
          {
            "name": "api-repo"
          }
        ],
        "compute": {},
        "hooks": {},
        "mcp_servers": [],
        "variables": []
      }
    }
)

result = client.environments.update(
    "api-environment",
    request.environment,
)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.environments.update>[1] = {
  "environment": {
    "ellipsis": {
      "kind": "environment",
      "name": "api-environment",
      "metadata": {
        "labels": [],
        "annotations": {}
      }
    },
    "repositories": [
      {
        "name": "api-repo"
      }
    ],
    "compute": {},
    "hooks": {},
    "mcp_servers": [],
    "variables": []
  }
};

const result = await client.environments.update("api-environment", request);
console.log(result);
```

### cURL

```bash
curl -X PUT "https://api.ellipsis.dev/v1/environments/{environment_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "ellipsis": {
      "kind": "environment",
      "name": "api-environment",
      "metadata": {
        "labels": [],
        "annotations": {}
      }
    },
    "repositories": [
      {
        "name": "api-repo"
      }
    ],
    "compute": {},
    "hooks": {},
    "mcp_servers": [],
    "variables": []
  }
}'
```

### Request schema

```json
{
  "properties": {
    "environment": {
      "additionalProperties": false,
      "properties": {
        "compute": {
          "additionalProperties": false,
          "properties": {
            "cpu": {
              "anyOf": [
                {
                  "maximum": 32,
                  "minimum": 2,
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "memory": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "gb": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "mb": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "timeout": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "hours": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "minutes": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "seconds": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        "ellipsis": {
          "additionalProperties": false,
          "properties": {
            "description": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "kind": {
              "const": "environment",
              "type": "string"
            },
            "metadata": {
              "additionalProperties": false,
              "properties": {
                "annotations": {
                  "items": {
                    "type": "string"
                  },
                  "default": {},
                  "type": "object"
                },
                "labels": {
                  "default": [],
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        "hooks": {
          "additionalProperties": false,
          "properties": {
            "after_checkout": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "run": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "run"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "before_start": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "run": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "run"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "build_base": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "inputs": {
                      "anyOf": [
                        {
                          "type": "array"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "run": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "run"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "post_clone": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "post_start": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        "mcp_servers": {
          "default": [],
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ],
                "type": "object"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "args": {
                    "default": [],
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "command": {
                    "type": "string"
                  },
                  "env": {
                    "items": {
                      "type": "string"
                    },
                    "default": {},
                    "type": "object"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "command"
                ],
                "type": "object"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "headers": {
                    "items": {
                      "type": "string"
                    },
                    "default": {},
                    "type": "object"
                  },
                  "name": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "url"
                ],
                "type": "object"
              }
            ]
          },
          "type": "array"
        },
        "repositories": {
          "default": [],
          "items": {
            "additionalProperties": false,
            "properties": {
              "name": {
                "type": "string"
              },
              "owner": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "ref": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "variables": {
          "default": [],
          "items": {
            "additionalProperties": false,
            "properties": {
              "name": {
                "type": "string"
              },
              "value": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "ellipsis"
      ],
      "type": "object"
    }
  },
  "required": [
    "environment"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "environment": {
      "properties": {
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "edited_by": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "environment": {
          "additionalProperties": false,
          "properties": {
            "compute": {
              "additionalProperties": false,
              "properties": {
                "cpu": {
                  "anyOf": [
                    {
                      "maximum": 32,
                      "minimum": 2,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "memory": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "gb": {
                          "type": "object"
                        },
                        "mb": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "gb",
                        "mb"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "timeout": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "hours": {
                          "type": "object"
                        },
                        "minutes": {
                          "type": "object"
                        },
                        "seconds": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "hours",
                        "minutes",
                        "seconds"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "cpu",
                "memory",
                "timeout"
              ],
              "type": "object"
            },
            "ellipsis": {
              "additionalProperties": false,
              "properties": {
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "kind": {
                  "const": "environment",
                  "type": "string"
                },
                "metadata": {
                  "additionalProperties": false,
                  "properties": {
                    "annotations": {
                      "items": {
                        "type": "string"
                      },
                      "default": {},
                      "type": "object"
                    },
                    "labels": {
                      "default": [],
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "annotations",
                    "labels"
                  ],
                  "type": "object"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "kind"
              ],
              "type": "object"
            },
            "hooks": {
              "additionalProperties": false,
              "properties": {
                "after_checkout": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "before_start": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "build_base": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "inputs": {
                          "type": "object"
                        },
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "inputs",
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_clone": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_start": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "after_checkout",
                "before_start",
                "build_base",
                "post_clone",
                "post_start"
              ],
              "type": "object"
            },
            "mcp_servers": {
              "default": [],
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "args": {
                        "type": "array"
                      },
                      "command": {
                        "type": "string"
                      },
                      "env": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "args",
                      "command",
                      "env",
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "headers": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "headers",
                      "name",
                      "url"
                    ],
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            },
            "repositories": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "ref": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "owner",
                  "ref"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "variables": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "value"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "ellipsis"
          ],
          "type": "object"
        },
        "id": {
          "type": "string"
        },
        "last_sync_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_synced_commit_sha": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "managed_by": {
          "enum": [
            "github",
            "api"
          ],
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "sha": {
          "type": "string"
        },
        "source_details": {
          "anyOf": [
            {
              "properties": {
                "branch": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "repo_id": {
                  "type": "integer"
                }
              },
              "required": [
                "repo_id",
                "path",
                "branch"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "environment"
      ],
      "type": "object"
    }
  },
  "required": [
    "environment"
  ],
  "type": "object"
}
```

---

# Get handler metrics

> Read session counts by current status and accumulated cost for a saved handler. Optional start and end timestamps filter session creation time, including start and excluding end. Cost includes the selected sessions' full history, in millicents. Requires configs:read matching handlers/{service} and unrestricted sessions:read.

Source: https://www.ellipsis.dev/docs/api/handlers/get-handlers-handler_id-metrics

## GET /v1/handlers/{handler_id}/metrics

Read session counts by current status and accumulated cost for a saved handler. Optional start and end timestamps filter session creation time, including start and excluding end. Cost includes the selected sessions' full history, in millicents. Requires configs:read matching handlers/{service} and unrestricted sessions:read.

Required permissions: read:sessions, read:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "cost": int,
  "end": str,
  "handler_id": str,
  "sessions": {
    "active": int,
    "cancelled": int,
    "completed": int,
    "failed": int,
    "stopped": int,
    "total": int
  },
  "spend_windows": [
    {
      "limit_usd": float,
      "platform_max_usd": float,
      "spent_usd": float,
      "window_days": int
    }
  ],
  "start": str
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.handlers.metrics("...")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.handlers.metrics('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/handlers/{handler_id}/metrics" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "cost": {
      "type": "integer"
    },
    "end": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "handler_id": {
      "type": "string"
    },
    "sessions": {
      "properties": {
        "active": {
          "type": "integer"
        },
        "cancelled": {
          "type": "integer"
        },
        "completed": {
          "type": "integer"
        },
        "failed": {
          "type": "integer"
        },
        "stopped": {
          "type": "integer"
        },
        "total": {
          "type": "integer"
        }
      },
      "required": [
        "total",
        "active",
        "completed",
        "failed",
        "stopped",
        "cancelled"
      ],
      "type": "object"
    },
    "spend_windows": {
      "items": {
        "properties": {
          "limit_usd": {
            "type": "number"
          },
          "platform_max_usd": {
            "type": "number"
          },
          "spent_usd": {
            "type": "number"
          },
          "window_days": {
            "type": "integer"
          }
        },
        "required": [
          "window_days",
          "spent_usd",
          "limit_usd",
          "platform_max_usd"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "start": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "handler_id",
    "start",
    "end",
    "sessions",
    "cost",
    "spend_windows"
  ],
  "type": "object"
}
```

---

# List handlers

> List the account's synced Slack, GitHub, Linear, and Sentry handlers. Disabled handlers and the last valid definitions after failed syncs are included. Requires configs:read; scoped grants match handlers/{service}.

Source: https://www.ellipsis.dev/docs/api/handlers/get-handlers

## GET /v1/handlers

List the account's synced Slack, GitHub, Linear, and Sentry handlers. Disabled handlers and the last valid definitions after failed syncs are included. Requires configs:read; scoped grants match handlers/{service}.

Required permissions: read:configs.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "handlers": [ # list[SlackHandler | GithubHandler | LinearHandler |
  # SentryHandler]
    {
      "config": {
        "ellipsis": {
          "description": str,
          "enabled": bool,
          "kind": "github",
          "metadata": {
            "annotations": {
              "[str]": str
            },
            "labels": [
              str
            ]
          },
          "name": str,
          "version": str
        },
        "github": {
          "mentions": {
            "allow_leading_ellipsis": bool,
            "for": {
              "private": {
                "bots": bool,
                "users": bool
              },
              "public": {
                "bots": bool,
                "users": bool
              }
            },
            "require_leading_mention": bool
          },
          "repositories": [
            str
          ]
        },
        "session": {
          "budget": {
            "day": float,
            "month": float,
            "session": float,
            "week": float
          },
          "claude_code": {
            "effort": str,
            "fallback_model": str,
            "max_turns": int,
            "model": str,
            "prompt": str,
            "settings": {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          },
          "codex": {
            "effort": str,
            "model": str,
            "prompt": str
          },
          "environment": { # str
            "compute": {
              "cpu": int,
              "memory": { # str | null
                "gb": int,
                "mb": int
              },
              "timeout": { # str | null
                "hours": int,
                "minutes": int,
                "seconds": int
              }
            },
            "hooks": {
              "after_checkout": { # str | null
                "run": str
              },
              "before_start": { # str | null
                "run": str
              },
              "build_base": { # str | null
                "inputs": [
                  str
                ],
                "run": str
              },
              "post_clone": str,
              "post_start": str
            },
            "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
            # McpRemoteServer]
              {
                "args": [
                  str
                ],
                "command": str,
                "env": {
                  "[str]": str
                },
                "name": str
              }
            ],
            "repositories": [
              {
                "name": str,
                "owner": str,
                "ref": str
              }
            ],
            "variables": [
              {
                "name": str,
                "value": str
              }
            ]
          },
          "permissions": {
            "ellipsis": { # bool | str
              "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                {
                  "level": str,
                  "match": [
                    str
                  ]
                }
              ]
            },
            "github": {
              "permissions": { # "read_only" | null
                "[str]": str
              },
              "repositories": [
                str
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        }
      },
      "created_at": str,
      "edited_by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "type": str
      },
      "id": str,
      "last_sync_error": str,
      "last_synced_commit_sha": str,
      "managed_by": "github",
      "raw_yaml": str,
      "service": "github",
      "sha": str,
      "source_details": {
        "branch": str,
        "path": str,
        "repo_id": int
      },
      "updated_at": str
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.handlers.list()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.handlers.list();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/handlers" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "handlers": {
      "items": {
        "oneOf": [
          {
            "properties": {
              "config": {
                "additionalProperties": false,
                "properties": {
                  "ellipsis": {
                    "additionalProperties": false,
                    "properties": {
                      "description": {
                        "type": "object"
                      },
                      "enabled": {
                        "type": "boolean"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "metadata": {
                        "type": "object"
                      },
                      "name": {
                        "type": "object"
                      },
                      "version": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "kind"
                    ],
                    "type": "object"
                  },
                  "session": {
                    "additionalProperties": false,
                    "allOf": [
                      {
                        "type": "object"
                      }
                    ],
                    "properties": {
                      "budget": {
                        "type": "object"
                      },
                      "claude_code": {
                        "type": "object"
                      },
                      "codex": {
                        "type": "object"
                      },
                      "environment": {
                        "type": "object"
                      },
                      "permissions": {
                        "type": "object"
                      },
                      "skills": {
                        "type": "array"
                      }
                    },
                    "type": "object"
                  },
                  "slack": {
                    "additionalProperties": false,
                    "properties": {
                      "channels": {
                        "type": "array"
                      },
                      "direct_messages": {
                        "type": "array"
                      }
                    },
                    "type": "object"
                  }
                },
                "required": [
                  "ellipsis",
                  "slack",
                  "session"
                ],
                "type": "object"
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "edited_by": {
                "anyOf": [
                  {
                    "properties": {
                      "avatar_url": {
                        "type": "string"
                      },
                      "id": {
                        "type": "integer"
                      },
                      "login": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "type": "string"
              },
              "last_sync_error": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "last_synced_commit_sha": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "managed_by": {
                "const": "github",
                "default": "github",
                "type": "string"
              },
              "raw_yaml": {
                "type": "string"
              },
              "service": {
                "const": "slack",
                "default": "slack",
                "type": "string"
              },
              "sha": {
                "type": "string"
              },
              "source_details": {
                "properties": {
                  "branch": {
                    "type": "string"
                  },
                  "path": {
                    "type": "string"
                  },
                  "repo_id": {
                    "type": "integer"
                  }
                },
                "required": [
                  "repo_id",
                  "path",
                  "branch"
                ],
                "type": "object"
              },
              "updated_at": {
                "format": "date-time",
                "type": "string"
              }
            },
            "required": [
              "id",
              "sha",
              "created_at",
              "updated_at",
              "raw_yaml",
              "source_details",
              "config"
            ],
            "type": "object"
          },
          {
            "properties": {
              "config": {
                "additionalProperties": false,
                "properties": {
                  "ellipsis": {
                    "additionalProperties": false,
                    "properties": {
                      "description": {
                        "type": "object"
                      },
                      "enabled": {
                        "type": "boolean"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "metadata": {
                        "type": "object"
                      },
                      "name": {
                        "type": "object"
                      },
                      "version": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "kind"
                    ],
                    "type": "object"
                  },
                  "github": {
                    "additionalProperties": false,
                    "properties": {
                      "mentions": {
                        "type": "object"
                      },
                      "repositories": {
                        "type": "array"
                      }
                    },
                    "type": "object"
                  },
                  "session": {
                    "additionalProperties": false,
                    "allOf": [
                      {
                        "type": "object"
                      }
                    ],
                    "properties": {
                      "budget": {
                        "type": "object"
                      },
                      "claude_code": {
                        "type": "object"
                      },
                      "codex": {
                        "type": "object"
                      },
                      "environment": {
                        "type": "object"
                      },
                      "permissions": {
                        "type": "object"
                      },
                      "skills": {
                        "type": "array"
                      }
                    },
                    "type": "object"
                  }
                },
                "required": [
                  "ellipsis",
                  "github",
                  "session"
                ],
                "type": "object"
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "edited_by": {
                "anyOf": [
                  {
                    "properties": {
                      "avatar_url": {
                        "type": "string"
                      },
                      "id": {
                        "type": "integer"
                      },
                      "login": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "type": "string"
              },
              "last_sync_error": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "last_synced_commit_sha": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "managed_by": {
                "const": "github",
                "default": "github",
                "type": "string"
              },
              "raw_yaml": {
                "type": "string"
              },
              "service": {
                "const": "github",
                "default": "github",
                "type": "string"
              },
              "sha": {
                "type": "string"
              },
              "source_details": {
                "properties": {
                  "branch": {
                    "type": "string"
                  },
                  "path": {
                    "type": "string"
                  },
                  "repo_id": {
                    "type": "integer"
                  }
                },
                "required": [
                  "repo_id",
                  "path",
                  "branch"
                ],
                "type": "object"
              },
              "updated_at": {
                "format": "date-time",
                "type": "string"
              }
            },
            "required": [
              "id",
              "sha",
              "created_at",
              "updated_at",
              "raw_yaml",
              "source_details",
              "config"
            ],
            "type": "object"
          },
          {
            "properties": {
              "config": {
                "additionalProperties": false,
                "properties": {
                  "ellipsis": {
                    "additionalProperties": false,
                    "properties": {
                      "description": {
                        "type": "object"
                      },
                      "enabled": {
                        "type": "boolean"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "metadata": {
                        "type": "object"
                      },
                      "name": {
                        "type": "object"
                      },
                      "version": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "kind"
                    ],
                    "type": "object"
                  },
                  "linear": {
                    "additionalProperties": false,
                    "properties": {
                      "projects": {
                        "type": "array"
                      },
                      "teams": {
                        "type": "array"
                      }
                    },
                    "type": "object"
                  },
                  "session": {
                    "additionalProperties": false,
                    "allOf": [
                      {
                        "type": "object"
                      }
                    ],
                    "properties": {
                      "budget": {
                        "type": "object"
                      },
                      "claude_code": {
                        "type": "object"
                      },
                      "codex": {
                        "type": "object"
                      },
                      "environment": {
                        "type": "object"
                      },
                      "permissions": {
                        "type": "object"
                      },
                      "skills": {
                        "type": "array"
                      }
                    },
                    "type": "object"
                  }
                },
                "required": [
                  "ellipsis",
                  "linear",
                  "session"
                ],
                "type": "object"
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "edited_by": {
                "anyOf": [
                  {
                    "properties": {
                      "avatar_url": {
                        "type": "string"
                      },
                      "id": {
                        "type": "integer"
                      },
                      "login": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "type": "string"
              },
              "last_sync_error": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "last_synced_commit_sha": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "managed_by": {
                "const": "github",
                "default": "github",
                "type": "string"
              },
              "raw_yaml": {
                "type": "string"
              },
              "service": {
                "const": "linear",
                "default": "linear",
                "type": "string"
              },
              "sha": {
                "type": "string"
              },
              "source_details": {
                "properties": {
                  "branch": {
                    "type": "string"
                  },
                  "path": {
                    "type": "string"
                  },
                  "repo_id": {
                    "type": "integer"
                  }
                },
                "required": [
                  "repo_id",
                  "path",
                  "branch"
                ],
                "type": "object"
              },
              "updated_at": {
                "format": "date-time",
                "type": "string"
              }
            },
            "required": [
              "id",
              "sha",
              "created_at",
              "updated_at",
              "raw_yaml",
              "source_details",
              "config"
            ],
            "type": "object"
          },
          {
            "properties": {
              "config": {
                "additionalProperties": false,
                "properties": {
                  "ellipsis": {
                    "additionalProperties": false,
                    "properties": {
                      "description": {
                        "type": "object"
                      },
                      "enabled": {
                        "type": "boolean"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "metadata": {
                        "type": "object"
                      },
                      "name": {
                        "type": "object"
                      },
                      "version": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "kind"
                    ],
                    "type": "object"
                  },
                  "sentry": {
                    "additionalProperties": false,
                    "properties": {
                      "on": {
                        "type": "array"
                      },
                      "organizations": {
                        "type": "array"
                      },
                      "projects": {
                        "type": "array"
                      }
                    },
                    "required": [
                      "projects"
                    ],
                    "type": "object"
                  },
                  "session": {
                    "additionalProperties": false,
                    "allOf": [
                      {
                        "type": "object"
                      }
                    ],
                    "properties": {
                      "budget": {
                        "type": "object"
                      },
                      "claude_code": {
                        "type": "object"
                      },
                      "codex": {
                        "type": "object"
                      },
                      "environment": {
                        "type": "object"
                      },
                      "permissions": {
                        "type": "object"
                      },
                      "skills": {
                        "type": "array"
                      }
                    },
                    "type": "object"
                  }
                },
                "required": [
                  "ellipsis",
                  "sentry",
                  "session"
                ],
                "type": "object"
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "edited_by": {
                "anyOf": [
                  {
                    "properties": {
                      "avatar_url": {
                        "type": "string"
                      },
                      "id": {
                        "type": "integer"
                      },
                      "login": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "type": "string"
              },
              "last_sync_error": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "last_synced_commit_sha": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "managed_by": {
                "const": "github",
                "default": "github",
                "type": "string"
              },
              "raw_yaml": {
                "type": "string"
              },
              "service": {
                "const": "sentry",
                "default": "sentry",
                "type": "string"
              },
              "sha": {
                "type": "string"
              },
              "source_details": {
                "properties": {
                  "branch": {
                    "type": "string"
                  },
                  "path": {
                    "type": "string"
                  },
                  "repo_id": {
                    "type": "integer"
                  }
                },
                "required": [
                  "repo_id",
                  "path",
                  "branch"
                ],
                "type": "object"
              },
              "updated_at": {
                "format": "date-time",
                "type": "string"
              }
            },
            "required": [
              "id",
              "sha",
              "created_at",
              "updated_at",
              "raw_yaml",
              "source_details",
              "config"
            ],
            "type": "object"
          }
        ]
      },
      "type": "array"
    }
  },
  "required": [
    "handlers"
  ],
  "type": "object"
}
```

---

# Handlers

> Handlers define how agents respond to events. Discover your handlers and inspect their activity and usage.

Source: https://www.ellipsis.dev/docs/api/handlers

- [`GET /v1/handlers`](https://www.ellipsis.dev/docs/api/handlers/get-handlers): List handlers
- [`GET /v1/handlers/{handler_id}/metrics`](https://www.ellipsis.dev/docs/api/handlers/get-handlers-handler_id-metrics): Get handler metrics

---

# List repositories

> List repositories available through the GitHub installation.

Source: https://www.ellipsis.dev/docs/api/integrations/get-integrations-github-repos

## GET /v1/integrations/github/repos

List repositories available through the GitHub installation.

Required permissions: read:integrations.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "backfill_complete": bool,
  "backfill_statuses": [
    {
      "backfill_complete": bool,
      "repository_id": int
    }
  ],
  "repositories": [
    {
      "default_branch": str,
      "description": str,
      "full_name": str,
      "html_url": str,
      "id": int,
      "name": str,
      "owner": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "type": str
      },
      "private": bool
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.integrations.github.repos()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.integrations.github.repos();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/integrations/github/repos" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "backfill_complete": {
      "default": false,
      "type": "boolean"
    },
    "backfill_statuses": {
      "items": {
        "properties": {
          "backfill_complete": {
            "type": "boolean"
          },
          "repository_id": {
            "type": "integer"
          }
        },
        "required": [
          "repository_id",
          "backfill_complete"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "repositories": {
      "items": {
        "properties": {
          "default_branch": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "full_name": {
            "type": "string"
          },
          "html_url": {
            "type": "string"
          },
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "owner": {
            "properties": {
              "avatar_url": {
                "type": "string"
              },
              "id": {
                "type": "integer"
              },
              "login": {
                "type": "string"
              },
              "type": {
                "enum": [
                  "User",
                  "Organization",
                  "Bot",
                  "Mannequin"
                ],
                "type": "string"
              }
            },
            "required": [
              "avatar_url",
              "id",
              "login",
              "type"
            ],
            "type": "object"
          },
          "private": {
            "type": "boolean"
          }
        },
        "required": [
          "owner",
          "html_url",
          "id",
          "name",
          "full_name",
          "private"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "repositories"
  ],
  "type": "object"
}
```

---

# List integrations

> Read connected integrations and their settings.

Source: https://www.ellipsis.dev/docs/api/integrations/get-integrations

## GET /v1/integrations

Read connected integrations and their settings.

Required permissions: read:integrations.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "github": {
    "account_login": str,
    "account_type": str,
    "created_at": str,
    "id": int,
    "needs_permissions_update": bool,
    "repository_count": int,
    "repository_selection": str,
    "suspended": bool,
    "suspended_at": str,
    "updated_at": str
  },
  "jira": {
    "cloud_id": str,
    "created_at": str,
    "scope": [
      str
    ],
    "updated_at": str
  },
  "linear": {
    "created_at": str,
    "mcp_inclusion": str,
    "organization_id": str,
    "teams": [
      {
        "id": str,
        "is_enabled": bool,
        "key": str,
        "name": str
      }
    ],
    "updated_at": str
  },
  "sentry": [
    {
      "integration_id": str,
      "organization_slug": str
    }
  ],
  "slack": {
    "created_at": str,
    "mcp_inclusion": str,
    "operations_channel_id": str,
    "team_id": str,
    "team_name": str,
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.integrations.list()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.integrations.list();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/integrations" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "github": {
      "anyOf": [
        {
          "properties": {
            "account_login": {
              "type": "string"
            },
            "account_type": {
              "enum": [
                "User",
                "Organization",
                "Bot",
                "Mannequin"
              ],
              "type": "string"
            },
            "created_at": {
              "format": "date-time",
              "type": "string"
            },
            "id": {
              "type": "integer"
            },
            "needs_permissions_update": {
              "type": "boolean"
            },
            "repository_count": {
              "type": "integer"
            },
            "repository_selection": {
              "enum": [
                "all",
                "selected"
              ],
              "type": "string"
            },
            "suspended": {
              "type": "boolean"
            },
            "suspended_at": {
              "anyOf": [
                {
                  "format": "date-time",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "updated_at": {
              "format": "date-time",
              "type": "string"
            }
          },
          "required": [
            "id",
            "created_at",
            "updated_at",
            "needs_permissions_update",
            "account_login",
            "account_type",
            "repository_selection",
            "suspended",
            "repository_count"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "jira": {
      "anyOf": [
        {
          "properties": {
            "cloud_id": {
              "type": "string"
            },
            "created_at": {
              "format": "date-time",
              "type": "string"
            },
            "scope": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "updated_at": {
              "format": "date-time",
              "type": "string"
            }
          },
          "required": [
            "created_at",
            "updated_at",
            "scope",
            "cloud_id"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "linear": {
      "anyOf": [
        {
          "properties": {
            "created_at": {
              "format": "date-time",
              "type": "string"
            },
            "mcp_inclusion": {
              "enum": [
                "all_sessions",
                "opt_in"
              ],
              "type": "string"
            },
            "organization_id": {
              "type": "string"
            },
            "teams": {
              "items": {
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "is_enabled": {
                    "type": "boolean"
                  },
                  "key": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "is_enabled"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "updated_at": {
              "format": "date-time",
              "type": "string"
            }
          },
          "required": [
            "created_at",
            "updated_at",
            "organization_id",
            "teams"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "sentry": {
      "default": [],
      "items": {
        "properties": {
          "integration_id": {
            "type": "string"
          },
          "organization_slug": {
            "type": "string"
          }
        },
        "required": [
          "integration_id",
          "organization_slug"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "slack": {
      "anyOf": [
        {
          "properties": {
            "created_at": {
              "format": "date-time",
              "type": "string"
            },
            "mcp_inclusion": {
              "enum": [
                "all_sessions",
                "opt_in"
              ],
              "type": "string"
            },
            "operations_channel_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "team_id": {
              "type": "string"
            },
            "team_name": {
              "type": "string"
            },
            "updated_at": {
              "format": "date-time",
              "type": "string"
            }
          },
          "required": [
            "created_at",
            "updated_at",
            "team_id",
            "team_name"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "type": "object"
}
```

---

# Integrations

> Integrations connect your account to external services. List connections and discover GitHub repositories available to your agents.

Source: https://www.ellipsis.dev/docs/api/integrations

- [`GET /v1/integrations`](https://www.ellipsis.dev/docs/api/integrations/get-integrations): List integrations
- [`GET /v1/integrations/github/repos`](https://www.ellipsis.dev/docs/api/integrations/get-integrations-github-repos): List repositories

---

# Get identity

> Read the account and identity associated with the credential.

Source: https://www.ellipsis.dev/docs/api/platform/get-identity

## GET /v1/identity

Read the account and identity associated with the credential.

Required permissions: read:account.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "api_key_id": str,
  "customer_id": str,
  "customer_login": str,
  "gh_user": {
    "avatar_url": str,
    "bio": str,
    "blog": str,
    "business_plus": bool,
    "collaborators": int,
    "company": str,
    "created_at": str,
    "disk_usage": int,
    "email": str,
    "events_url": str,
    "followers": int,
    "followers_url": str,
    "following": int,
    "following_url": str,
    "gists_url": str,
    "gravatar_id": str,
    "hireable": bool,
    "html_url": str,
    "id": int,
    "ldap_dn": str,
    "location": str,
    "login": str,
    "name": str,
    "node_id": str,
    "notification_email": str,
    "organizations_url": str,
    "owned_private_repos": int,
    "plan": {
      "collaborators": int,
      "name": str,
      "private_repos": int,
      "space": int
    },
    "private_gists": int,
    "public_gists": int,
    "public_repos": int,
    "received_events_url": str,
    "repos_url": str,
    "site_admin": bool,
    "starred_url": str,
    "subscriptions_url": str,
    "total_private_repos": int,
    "twitter_username": str,
    "two_factor_authentication": bool,
    "type": str,
    "updated_at": str,
    "url": str,
    "user_view_type": str
  },
  "sandbox_id": str,
  "user_id": str
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.identity()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.identity();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/identity" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "api_key_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "customer_id": {
      "type": "string"
    },
    "customer_login": {
      "type": "string"
    },
    "gh_user": {
      "anyOf": [
        {
          "properties": {
            "avatar_url": {
              "type": "string"
            },
            "bio": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "blog": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "business_plus": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ]
            },
            "collaborators": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "company": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "created_at": {
              "anyOf": [
                {
                  "format": "date-time",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "disk_usage": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "email": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "events_url": {
              "type": "string"
            },
            "followers": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "followers_url": {
              "type": "string"
            },
            "following": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "following_url": {
              "type": "string"
            },
            "gists_url": {
              "type": "string"
            },
            "gravatar_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "hireable": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ]
            },
            "html_url": {
              "type": "string"
            },
            "id": {
              "type": "integer"
            },
            "ldap_dn": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "location": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "login": {
              "type": "string"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "node_id": {
              "type": "string"
            },
            "notification_email": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "organizations_url": {
              "type": "string"
            },
            "owned_private_repos": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "plan": {
              "anyOf": [
                {
                  "properties": {
                    "collaborators": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "private_repos": {
                      "type": "integer"
                    },
                    "space": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "collaborators",
                    "name",
                    "space",
                    "private_repos"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "private_gists": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "public_gists": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "public_repos": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "received_events_url": {
              "type": "string"
            },
            "repos_url": {
              "type": "string"
            },
            "site_admin": {
              "type": "boolean"
            },
            "starred_url": {
              "type": "string"
            },
            "subscriptions_url": {
              "type": "string"
            },
            "total_private_repos": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "twitter_username": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "two_factor_authentication": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ]
            },
            "type": {
              "enum": [
                "User",
                "Organization",
                "Bot",
                "Mannequin"
              ],
              "type": "string"
            },
            "updated_at": {
              "anyOf": [
                {
                  "format": "date-time",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "url": {
              "type": "string"
            },
            "user_view_type": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "login",
            "avatar_url",
            "html_url",
            "node_id",
            "url",
            "followers_url",
            "following_url",
            "gists_url",
            "starred_url",
            "subscriptions_url",
            "organizations_url",
            "repos_url",
            "events_url",
            "received_events_url",
            "site_admin"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "sandbox_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "user_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "customer_id",
    "customer_login",
    "user_id",
    "gh_user",
    "api_key_id",
    "sandbox_id"
  ],
  "type": "object"
}
```

---

# Identity

> Identity describes the account and credentials behind a request. Inspect the identity associated with your API token.

Source: https://www.ellipsis.dev/docs/api/platform

- [`GET /v1/identity`](https://www.ellipsis.dev/docs/api/platform/get-identity): Get identity

---

# List review configurations

> Read available review pipeline configurations.

Source: https://www.ellipsis.dev/docs/api/reviews/get-reviews-configs

## GET /v1/reviews/configs

Read available review pipeline configurations.

Required permissions: read:reviews.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "configs": [
    {
      "enabled": bool,
      "id": str,
      "last_sync_error": str,
      "name": str,
      "path": str,
      "repository": {
        "id": int,
        "name": str,
        "owner_login": str
      }
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.reviews.configs()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.reviews.configs();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/reviews/configs" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "configs": {
      "items": {
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "last_sync_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "path": {
            "type": "string"
          },
          "repository": {
            "anyOf": [
              {
                "properties": {
                  "id": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  },
                  "owner_login": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "owner_login",
                  "name"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "name",
          "path",
          "enabled"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "configs"
  ],
  "type": "object"
}
```

---

# Get a review

> Read findings, stage results, coverage, and cost for a review.

Source: https://www.ellipsis.dev/docs/api/reviews/get-reviews-review_id

## GET /v1/reviews/{review_id}

Read findings, stage results, coverage, and cost for a review.

Required permissions: read:reviews.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "budget_millicents": int,
  "completed_at": str,
  "configuration": {
    "config_id": str,
    "effective_yaml": str,
    "raw_yaml": str
  },
  "cost_millicents": int,
  "counters": {
    "n_anchor_valid": int,
    "n_coerced": int,
    "n_dropped": int,
    "n_not_commentable": int,
    "n_parsed": int,
    "n_raw_lines": int,
    "n_snapped": int,
    "parser_version": str
  },
  "created_at": str,
  "description_error": str,
  "description_outcome": str,
  "findings": [
    {
      "agent_name": str,
      "anchor": str,
      "category": str,
      "claim": str,
      "confidence": float,
      "disposition": str,
      "end_line": int,
      "evidence": str,
      "extra": {
        "[str]": any
      },
      "filter_verdict_reason": str,
      "id": str,
      "in_scope": bool,
      "merged_into_finding_id": str,
      "path": str,
      "posted_comment_id": int,
      "severity": int,
      "side": str,
      "snapped_from": [
        any
      ],
      "stage": str,
      "start_line": int,
      "suggested_fix": str
    }
  ],
  "id": str,
  "post": bool,
  "post_error": str,
  "posted_review_id": int,
  "pull_request": {
    "additions": int,
    "author": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "base_sha": str,
    "changed_files": int,
    "deletions": int,
    "head_sha": str,
    "number": int,
    "title": str,
    "url": str
  },
  "repository": {
    "id": int,
    "name": str,
    "owner": str
  },
  "requested_by": {
    "attribution_id": str,
    "attribution_type": str
  },
  "review_body": str,
  "reviewed_commits": [
    {
      "author_avatar_url": str,
      "author_login": str,
      "authored_at": str,
      "message": str,
      "sha": str
    }
  ],
  "scope": {
    "empty": bool,
    "head": str,
    "kind": str,
    "watermark": str
  },
  "skip_reason": str,
  "stages": [
    {
      "agent_name": str,
      "cost_millicents": int,
      "created_at": str,
      "finalized_at": str,
      "n_findings": int,
      "session_id": str,
      "stage": str,
      "status": str,
      "status_reason": str
    }
  ],
  "status": str,
  "trigger": str
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.reviews.get("review_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.reviews.get("review_example");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/reviews/{review_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "budget_millicents": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "completed_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "configuration": {
      "anyOf": [
        {
          "properties": {
            "config_id": {
              "type": "string"
            },
            "effective_yaml": {
              "type": "string"
            },
            "raw_yaml": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "config_id",
            "effective_yaml"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "cost_millicents": {
      "default": 0,
      "type": "integer"
    },
    "counters": {
      "anyOf": [
        {
          "properties": {
            "n_anchor_valid": {
              "default": 0,
              "type": "integer"
            },
            "n_coerced": {
              "default": 0,
              "type": "integer"
            },
            "n_dropped": {
              "default": 0,
              "type": "integer"
            },
            "n_not_commentable": {
              "default": 0,
              "type": "integer"
            },
            "n_parsed": {
              "default": 0,
              "type": "integer"
            },
            "n_raw_lines": {
              "default": 0,
              "type": "integer"
            },
            "n_snapped": {
              "default": 0,
              "type": "integer"
            },
            "parser_version": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "description_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "description_outcome": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "findings": {
      "default": [],
      "items": {
        "properties": {
          "agent_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "anchor": {
            "enum": [
              "valid",
              "snapped",
              "not_commentable"
            ],
            "type": "string"
          },
          "category": {
            "default": "other",
            "type": "string"
          },
          "claim": {
            "type": "string"
          },
          "confidence": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "disposition": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "end_line": {
            "type": "integer"
          },
          "evidence": {
            "default": "",
            "type": "string"
          },
          "extra": {
            "additionalProperties": true,
            "default": {},
            "type": "object"
          },
          "filter_verdict_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "in_scope": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ]
          },
          "merged_into_finding_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "path": {
            "type": "string"
          },
          "posted_comment_id": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "severity": {
            "default": 3,
            "type": "integer"
          },
          "side": {
            "default": "RIGHT",
            "type": "string"
          },
          "snapped_from": {
            "anyOf": [
              {
                "maxItems": 2,
                "minItems": 2,
                "prefixItems": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "integer"
                  }
                ],
                "type": "array"
              },
              {
                "type": "null"
              }
            ]
          },
          "stage": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "start_line": {
            "type": "integer"
          },
          "suggested_fix": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "path",
          "start_line",
          "end_line",
          "claim"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "id": {
      "type": "string"
    },
    "post": {
      "default": true,
      "type": "boolean"
    },
    "post_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "posted_review_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "pull_request": {
      "properties": {
        "additions": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "author": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "login",
                "avatar_url",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "base_sha": {
          "type": "string"
        },
        "changed_files": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "deletions": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_sha": {
          "type": "string"
        },
        "number": {
          "type": "integer"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "url": {
          "type": "string"
        }
      },
      "required": [
        "number",
        "url",
        "base_sha",
        "head_sha"
      ],
      "type": "object"
    },
    "repository": {
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "owner": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "owner",
        "name"
      ],
      "type": "object"
    },
    "requested_by": {
      "anyOf": [
        {
          "properties": {
            "attribution_id": {
              "type": "string"
            },
            "attribution_type": {
              "type": "string"
            }
          },
          "required": [
            "attribution_type",
            "attribution_id"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "review_body": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "reviewed_commits": {
      "default": [],
      "items": {
        "properties": {
          "author_avatar_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "author_login": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "authored_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "message": {
            "type": "string"
          },
          "sha": {
            "type": "string"
          }
        },
        "required": [
          "sha",
          "message"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "scope": {
      "properties": {
        "empty": {
          "type": "boolean"
        },
        "head": {
          "type": "string"
        },
        "kind": {
          "enum": [
            "incremental",
            "full"
          ],
          "type": "string"
        },
        "watermark": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "kind",
        "watermark",
        "head",
        "empty"
      ],
      "type": "object"
    },
    "skip_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "stages": {
      "default": [],
      "items": {
        "properties": {
          "agent_name": {
            "type": "string"
          },
          "cost_millicents": {
            "default": 0,
            "type": "integer"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "finalized_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "n_findings": {
            "default": 0,
            "type": "integer"
          },
          "session_id": {
            "type": "string"
          },
          "stage": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "status_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "stage",
          "agent_name",
          "session_id",
          "status"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "status": {
      "type": "string"
    },
    "trigger": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "trigger",
    "repository",
    "pull_request",
    "scope"
  ],
  "type": "object"
}
```

---

# List reviews

> List review runs and their statuses.

Source: https://www.ellipsis.dev/docs/api/reviews/get-reviews

## GET /v1/reviews

List review runs and their statuses.

Required permissions: read:reviews.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "has_more": bool,
  "next_cursor": str,
  "reviews": [
    {
      "budget_millicents": int,
      "completed_at": str,
      "configuration": {
        "config_id": str,
        "effective_yaml": str,
        "raw_yaml": str
      },
      "cost_millicents": int,
      "counters": {
        "n_anchor_valid": int,
        "n_coerced": int,
        "n_dropped": int,
        "n_not_commentable": int,
        "n_parsed": int,
        "n_raw_lines": int,
        "n_snapped": int,
        "parser_version": str
      },
      "created_at": str,
      "description_error": str,
      "description_outcome": str,
      "findings": [
        {
          "agent_name": str,
          "anchor": str,
          "category": str,
          "claim": str,
          "confidence": float,
          "disposition": str,
          "end_line": int,
          "evidence": str,
          "extra": {
            "[str]": any
          },
          "filter_verdict_reason": str,
          "id": str,
          "in_scope": bool,
          "merged_into_finding_id": str,
          "path": str,
          "posted_comment_id": int,
          "severity": int,
          "side": str,
          "snapped_from": [
            any
          ],
          "stage": str,
          "start_line": int,
          "suggested_fix": str
        }
      ],
      "id": str,
      "post": bool,
      "post_error": str,
      "posted_review_id": int,
      "pull_request": {
        "additions": int,
        "author": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        },
        "base_sha": str,
        "changed_files": int,
        "deletions": int,
        "head_sha": str,
        "number": int,
        "title": str,
        "url": str
      },
      "repository": {
        "id": int,
        "name": str,
        "owner": str
      },
      "requested_by": {
        "attribution_id": str,
        "attribution_type": str
      },
      "review_body": str,
      "reviewed_commits": [
        {
          "author_avatar_url": str,
          "author_login": str,
          "authored_at": str,
          "message": str,
          "sha": str
        }
      ],
      "scope": {
        "empty": bool,
        "head": str,
        "kind": str,
        "watermark": str
      },
      "skip_reason": str,
      "stages": [
        {
          "agent_name": str,
          "cost_millicents": int,
          "created_at": str,
          "finalized_at": str,
          "n_findings": int,
          "session_id": str,
          "stage": str,
          "status": str,
          "status_reason": str
        }
      ],
      "status": str,
      "trigger": str
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

for item in client.reviews.list():
    print(item)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

for await (const item of await client.reviews.list()) {
  console.log(item);
}
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/reviews" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "has_more": {
      "default": false,
      "type": "boolean"
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "reviews": {
      "items": {
        "properties": {
          "budget_millicents": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "completed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "configuration": {
            "anyOf": [
              {
                "properties": {
                  "config_id": {
                    "type": "string"
                  },
                  "effective_yaml": {
                    "type": "string"
                  },
                  "raw_yaml": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "config_id",
                  "effective_yaml"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "cost_millicents": {
            "default": 0,
            "type": "integer"
          },
          "counters": {
            "anyOf": [
              {
                "properties": {
                  "n_anchor_valid": {
                    "default": 0,
                    "type": "integer"
                  },
                  "n_coerced": {
                    "default": 0,
                    "type": "integer"
                  },
                  "n_dropped": {
                    "default": 0,
                    "type": "integer"
                  },
                  "n_not_commentable": {
                    "default": 0,
                    "type": "integer"
                  },
                  "n_parsed": {
                    "default": 0,
                    "type": "integer"
                  },
                  "n_raw_lines": {
                    "default": 0,
                    "type": "integer"
                  },
                  "n_snapped": {
                    "default": 0,
                    "type": "integer"
                  },
                  "parser_version": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "description_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "description_outcome": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "findings": {
            "default": [],
            "items": {
              "properties": {
                "agent_name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "anchor": {
                  "enum": [
                    "valid",
                    "snapped",
                    "not_commentable"
                  ],
                  "type": "string"
                },
                "category": {
                  "default": "other",
                  "type": "string"
                },
                "claim": {
                  "type": "string"
                },
                "confidence": {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "disposition": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "end_line": {
                  "type": "integer"
                },
                "evidence": {
                  "default": "",
                  "type": "string"
                },
                "extra": {
                  "additionalProperties": true,
                  "default": {},
                  "type": "object"
                },
                "filter_verdict_reason": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "in_scope": {
                  "anyOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "merged_into_finding_id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "path": {
                  "type": "string"
                },
                "posted_comment_id": {
                  "anyOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "severity": {
                  "default": 3,
                  "type": "integer"
                },
                "side": {
                  "default": "RIGHT",
                  "type": "string"
                },
                "snapped_from": {
                  "anyOf": [
                    {
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "stage": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "start_line": {
                  "type": "integer"
                },
                "suggested_fix": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "path",
                "start_line",
                "end_line",
                "claim"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "id": {
            "type": "string"
          },
          "post": {
            "default": true,
            "type": "boolean"
          },
          "post_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "posted_review_id": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "pull_request": {
            "properties": {
              "additions": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "author": {
                "anyOf": [
                  {
                    "properties": {
                      "avatar_url": {
                        "type": "string"
                      },
                      "id": {
                        "type": "integer"
                      },
                      "login": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "login",
                      "avatar_url",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "base_sha": {
                "type": "string"
              },
              "changed_files": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "deletions": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "head_sha": {
                "type": "string"
              },
              "number": {
                "type": "integer"
              },
              "title": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "url": {
                "type": "string"
              }
            },
            "required": [
              "number",
              "url",
              "base_sha",
              "head_sha"
            ],
            "type": "object"
          },
          "repository": {
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "owner": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "owner",
              "name"
            ],
            "type": "object"
          },
          "requested_by": {
            "anyOf": [
              {
                "properties": {
                  "attribution_id": {
                    "type": "string"
                  },
                  "attribution_type": {
                    "type": "string"
                  }
                },
                "required": [
                  "attribution_type",
                  "attribution_id"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "review_body": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "reviewed_commits": {
            "default": [],
            "items": {
              "properties": {
                "author_avatar_url": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "author_login": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "authored_at": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "message": {
                  "type": "string"
                },
                "sha": {
                  "type": "string"
                }
              },
              "required": [
                "sha",
                "message"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "scope": {
            "properties": {
              "empty": {
                "type": "boolean"
              },
              "head": {
                "type": "string"
              },
              "kind": {
                "enum": [
                  "incremental",
                  "full"
                ],
                "type": "string"
              },
              "watermark": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "kind",
              "watermark",
              "head",
              "empty"
            ],
            "type": "object"
          },
          "skip_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "stages": {
            "default": [],
            "items": {
              "properties": {
                "agent_name": {
                  "type": "string"
                },
                "cost_millicents": {
                  "default": 0,
                  "type": "integer"
                },
                "created_at": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "finalized_at": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "n_findings": {
                  "default": 0,
                  "type": "integer"
                },
                "session_id": {
                  "type": "string"
                },
                "stage": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "status_reason": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "stage",
                "agent_name",
                "session_id",
                "status"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "status": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "trigger",
          "repository",
          "pull_request",
          "scope"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "reviews"
  ],
  "type": "object"
}
```

---

# Reviews

> Code reviews inspect changes in your repositories. Start a review, inspect its results, and discover available review configurations.

Source: https://www.ellipsis.dev/docs/api/reviews

- [`POST /v1/reviews`](https://www.ellipsis.dev/docs/api/reviews/post-reviews): Run a review
- [`GET /v1/reviews`](https://www.ellipsis.dev/docs/api/reviews/get-reviews): List reviews
- [`GET /v1/reviews/{review_id}`](https://www.ellipsis.dev/docs/api/reviews/get-reviews-review_id): Get a review
- [`GET /v1/reviews/configs`](https://www.ellipsis.dev/docs/api/reviews/get-reviews-configs): List review configurations

---

# Run a review

> Review an open pull request using its resolved pipeline. Set post to false to inspect findings without posting to GitHub.

Source: https://www.ellipsis.dev/docs/api/reviews/post-reviews

## POST /v1/reviews

Review an open pull request using its resolved pipeline. Set post to false to inspect findings without posting to GitHub.

Required permissions: write:reviews.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.

### Request

```text
{
  "owner": str,
  "post": bool,
  "pull_request_number": int,
  "repo": str,
  "scope": {
    "head": str,
    "kind": str,
    "watermark": str
  }
}
```

### Response

```text
{
  "budget_millicents": int,
  "completed_at": str,
  "configuration": {
    "config_id": str,
    "effective_yaml": str,
    "raw_yaml": str
  },
  "cost_millicents": int,
  "counters": {
    "n_anchor_valid": int,
    "n_coerced": int,
    "n_dropped": int,
    "n_not_commentable": int,
    "n_parsed": int,
    "n_raw_lines": int,
    "n_snapped": int,
    "parser_version": str
  },
  "created_at": str,
  "description_error": str,
  "description_outcome": str,
  "findings": [
    {
      "agent_name": str,
      "anchor": str,
      "category": str,
      "claim": str,
      "confidence": float,
      "disposition": str,
      "end_line": int,
      "evidence": str,
      "extra": {
        "[str]": any
      },
      "filter_verdict_reason": str,
      "id": str,
      "in_scope": bool,
      "merged_into_finding_id": str,
      "path": str,
      "posted_comment_id": int,
      "severity": int,
      "side": str,
      "snapped_from": [
        any
      ],
      "stage": str,
      "start_line": int,
      "suggested_fix": str
    }
  ],
  "id": str,
  "post": bool,
  "post_error": str,
  "posted_review_id": int,
  "pull_request": {
    "additions": int,
    "author": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "base_sha": str,
    "changed_files": int,
    "deletions": int,
    "head_sha": str,
    "number": int,
    "title": str,
    "url": str
  },
  "repository": {
    "id": int,
    "name": str,
    "owner": str
  },
  "requested_by": {
    "attribution_id": str,
    "attribution_type": str
  },
  "review_body": str,
  "reviewed_commits": [
    {
      "author_avatar_url": str,
      "author_login": str,
      "authored_at": str,
      "message": str,
      "sha": str
    }
  ],
  "scope": {
    "empty": bool,
    "head": str,
    "kind": str,
    "watermark": str
  },
  "skip_reason": str,
  "stages": [
    {
      "agent_name": str,
      "cost_millicents": int,
      "created_at": str,
      "finalized_at": str,
      "n_findings": int,
      "session_id": str,
      "stage": str,
      "status": str,
      "status_reason": str
    }
  ],
  "status": str,
  "trigger": str
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.CreateReviewRequest.model_validate(
    {
      "owner": "your-org",
      "repo": "api-repo",
      "pull_request_number": 42,
      "post": False
    }
)

result = client.reviews.create(
    request.owner,
    request.pull_request_number,
    request.repo,
    post=request.post,
)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.reviews.create>[0] = {
  "owner": "your-org",
  "repo": "api-repo",
  "pull_request_number": 42,
  "post": false
};

const result = await client.reviews.create(request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/reviews" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "your-org",
  "repo": "api-repo",
  "pull_request_number": 42,
  "post": false
}'
```

### Request schema

```json
{
  "properties": {
    "owner": {
      "type": "string"
    },
    "post": {
      "default": true,
      "type": "boolean"
    },
    "pull_request_number": {
      "type": "integer"
    },
    "repo": {
      "type": "string"
    },
    "scope": {
      "properties": {
        "head": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "kind": {
          "enum": [
            "incremental",
            "full"
          ],
          "type": "string"
        },
        "watermark": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object"
    }
  },
  "required": [
    "owner",
    "repo",
    "pull_request_number"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "budget_millicents": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "completed_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "configuration": {
      "anyOf": [
        {
          "properties": {
            "config_id": {
              "type": "string"
            },
            "effective_yaml": {
              "type": "string"
            },
            "raw_yaml": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "config_id",
            "effective_yaml"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "cost_millicents": {
      "default": 0,
      "type": "integer"
    },
    "counters": {
      "anyOf": [
        {
          "properties": {
            "n_anchor_valid": {
              "default": 0,
              "type": "integer"
            },
            "n_coerced": {
              "default": 0,
              "type": "integer"
            },
            "n_dropped": {
              "default": 0,
              "type": "integer"
            },
            "n_not_commentable": {
              "default": 0,
              "type": "integer"
            },
            "n_parsed": {
              "default": 0,
              "type": "integer"
            },
            "n_raw_lines": {
              "default": 0,
              "type": "integer"
            },
            "n_snapped": {
              "default": 0,
              "type": "integer"
            },
            "parser_version": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "description_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "description_outcome": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "findings": {
      "default": [],
      "items": {
        "properties": {
          "agent_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "anchor": {
            "enum": [
              "valid",
              "snapped",
              "not_commentable"
            ],
            "type": "string"
          },
          "category": {
            "default": "other",
            "type": "string"
          },
          "claim": {
            "type": "string"
          },
          "confidence": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "disposition": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "end_line": {
            "type": "integer"
          },
          "evidence": {
            "default": "",
            "type": "string"
          },
          "extra": {
            "additionalProperties": true,
            "default": {},
            "type": "object"
          },
          "filter_verdict_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "in_scope": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ]
          },
          "merged_into_finding_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "path": {
            "type": "string"
          },
          "posted_comment_id": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "severity": {
            "default": 3,
            "type": "integer"
          },
          "side": {
            "default": "RIGHT",
            "type": "string"
          },
          "snapped_from": {
            "anyOf": [
              {
                "maxItems": 2,
                "minItems": 2,
                "prefixItems": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "integer"
                  }
                ],
                "type": "array"
              },
              {
                "type": "null"
              }
            ]
          },
          "stage": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "start_line": {
            "type": "integer"
          },
          "suggested_fix": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "path",
          "start_line",
          "end_line",
          "claim"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "id": {
      "type": "string"
    },
    "post": {
      "default": true,
      "type": "boolean"
    },
    "post_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "posted_review_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "pull_request": {
      "properties": {
        "additions": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "author": {
          "anyOf": [
            {
              "properties": {
                "avatar_url": {
                  "type": "string"
                },
                "id": {
                  "type": "integer"
                },
                "login": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "login",
                "avatar_url",
                "type"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "base_sha": {
          "type": "string"
        },
        "changed_files": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "deletions": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_sha": {
          "type": "string"
        },
        "number": {
          "type": "integer"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "url": {
          "type": "string"
        }
      },
      "required": [
        "number",
        "url",
        "base_sha",
        "head_sha"
      ],
      "type": "object"
    },
    "repository": {
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "owner": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "owner",
        "name"
      ],
      "type": "object"
    },
    "requested_by": {
      "anyOf": [
        {
          "properties": {
            "attribution_id": {
              "type": "string"
            },
            "attribution_type": {
              "type": "string"
            }
          },
          "required": [
            "attribution_type",
            "attribution_id"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "review_body": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "reviewed_commits": {
      "default": [],
      "items": {
        "properties": {
          "author_avatar_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "author_login": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "authored_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "message": {
            "type": "string"
          },
          "sha": {
            "type": "string"
          }
        },
        "required": [
          "sha",
          "message"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "scope": {
      "properties": {
        "empty": {
          "type": "boolean"
        },
        "head": {
          "type": "string"
        },
        "kind": {
          "enum": [
            "incremental",
            "full"
          ],
          "type": "string"
        },
        "watermark": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "kind",
        "watermark",
        "head",
        "empty"
      ],
      "type": "object"
    },
    "skip_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "stages": {
      "default": [],
      "items": {
        "properties": {
          "agent_name": {
            "type": "string"
          },
          "cost_millicents": {
            "default": 0,
            "type": "integer"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "finalized_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "n_findings": {
            "default": 0,
            "type": "integer"
          },
          "session_id": {
            "type": "string"
          },
          "stage": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "status_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "stage",
          "agent_name",
          "session_id",
          "status"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "status": {
      "type": "string"
    },
    "trigger": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "trigger",
    "repository",
    "pull_request",
    "scope"
  ],
  "type": "object"
}
```

---

# Delete a secret

> Delete a stored secret. New sessions that require it will fail.

Source: https://www.ellipsis.dev/docs/api/secrets/delete-secrets-name

## DELETE /v1/secrets/{name}

Delete a stored secret. New sessions that require it will fail.

Required permissions: delete:secrets.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.secrets.delete("NPM_TOKEN")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.secrets.delete("NPM_TOKEN");
console.log(result);
```

### cURL

```bash
curl -X DELETE "https://api.ellipsis.dev/v1/secrets/{name}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

---

# List secret names

> List secret names and metadata. Values are never returned.

Source: https://www.ellipsis.dev/docs/api/secrets/get-secrets

## GET /v1/secrets

List secret names and metadata. Values are never returned.

Required permissions: read:secrets.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "secrets": [
    {
      "created_at": str,
      "name": str,
      "updated_at": str
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.secrets.list()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.secrets.list();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/secrets" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "secrets": {
      "items": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "name",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "secrets"
  ],
  "type": "object"
}
```

---

# Secrets

> Secrets supply credentials to agent environments. Set values, list stored names, and remove credentials you no longer need.

Source: https://www.ellipsis.dev/docs/api/secrets

- [`PUT /v1/secrets`](https://www.ellipsis.dev/docs/api/secrets/put-secrets): Set secrets
- [`GET /v1/secrets`](https://www.ellipsis.dev/docs/api/secrets/get-secrets): List secret names
- [`DELETE /v1/secrets/{name}`](https://www.ellipsis.dev/docs/api/secrets/delete-secrets-name): Delete a secret

---

# Set secrets

> Store secret values for environments to reference. Values cannot be read back.

Source: https://www.ellipsis.dev/docs/api/secrets/put-secrets

## PUT /v1/secrets

Store secret values for environments to reference. Values cannot be read back.

Required permissions: write:secrets.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Request

```text
{
  "secrets": [
    {
      "name": str,
      "value": str
    }
  ]
}
```

### Response

```text
{
  "secrets": [
    {
      "created_at": str,
      "name": str,
      "updated_at": str
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.PutSecretsRequest.model_validate(
    {
      "secrets": [
        {
          "name": "NPM_TOKEN",
          "value": "replace-me"
        }
      ]
    }
)

result = client.secrets.set(request.secrets)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.secrets.set>[0] = {
  "secrets": [
    {
      "name": "NPM_TOKEN",
      "value": "replace-me"
    }
  ]
};

const result = await client.secrets.set(request);
console.log(result);
```

### cURL

```bash
curl -X PUT "https://api.ellipsis.dev/v1/secrets" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "secrets": [
    {
      "name": "NPM_TOKEN",
      "value": "replace-me"
    }
  ]
}'
```

### Request schema

```json
{
  "properties": {
    "secrets": {
      "items": {
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "value"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "secrets"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "secrets": {
      "items": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "name",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "secrets"
  ],
  "type": "object"
}
```

---

# Get a VM image

> Read a reusable image and its provider snapshot ID, repositories, cache key, and expiration.

Source: https://www.ellipsis.dev/docs/api/vm-images/get-vm-images-image_id

## GET /v1/vm-images/{image_id}

Read a reusable image and its provider snapshot ID, repositories, cache key, and expiration.

Required permissions: read:environments.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "cache_key": str,
  "created_at": str,
  "expires_at": str,
  "id": str,
  "repositories": [
    {
      "id": int,
      "name": str,
      "owner_id": int,
      "owner_name": str,
      "sha": str
    }
  ],
  "snapshot_id": str,
  "source": str,
  "status": str
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.vm_images.get("...")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.vmImages.get('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/vm-images/{image_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "cache_key": {
      "type": "string"
    },
    "created_at": {
      "format": "date-time",
      "type": "string"
    },
    "expires_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "repositories": {
      "items": {
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "owner_id": {
            "type": "integer"
          },
          "owner_name": {
            "type": "string"
          },
          "sha": {
            "type": "string"
          }
        },
        "required": [
          "owner_id",
          "owner_name",
          "id",
          "name",
          "sha"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "snapshot_id": {
      "type": "string"
    },
    "source": {
      "enum": [
        "provisioning",
        "refresh",
        "build"
      ],
      "type": "string"
    },
    "status": {
      "enum": [
        "ready",
        "expired"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "snapshot_id",
    "created_at",
    "expires_at",
    "status",
    "source",
    "repositories",
    "cache_key"
  ],
  "type": "object"
}
```

---

# List VM images

> List reusable snapshots of prepared environments, including repository revisions, build identity, and expiration. Use limit and offset to page through results.

Source: https://www.ellipsis.dev/docs/api/vm-images/get-vm-images

## GET /v1/vm-images

List reusable snapshots of prepared environments, including repository revisions, build identity, and expiration. Use limit and offset to page through results.

Required permissions: read:environments.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "images": [
    {
      "cache_key": str,
      "created_at": str,
      "expires_at": str,
      "id": str,
      "repositories": [
        {
          "id": int,
          "name": str,
          "owner_id": int,
          "owner_name": str,
          "sha": str
        }
      ],
      "snapshot_id": str,
      "source": str,
      "status": str
    }
  ],
  "next_offset": int
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.vm_images.list()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.vmImages.list();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/vm-images" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "images": {
      "items": {
        "properties": {
          "cache_key": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string"
          },
          "repositories": {
            "items": {
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "owner_id": {
                  "type": "integer"
                },
                "owner_name": {
                  "type": "string"
                },
                "sha": {
                  "type": "string"
                }
              },
              "required": [
                "owner_id",
                "owner_name",
                "id",
                "name",
                "sha"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "snapshot_id": {
            "type": "string"
          },
          "source": {
            "enum": [
              "provisioning",
              "refresh",
              "build"
            ],
            "type": "string"
          },
          "status": {
            "enum": [
              "ready",
              "expired"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "snapshot_id",
          "created_at",
          "expires_at",
          "status",
          "source",
          "repositories",
          "cache_key"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "next_offset": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "images",
    "next_offset"
  ],
  "type": "object"
}
```

---

# VM images

> Virtual machine images capture prepared environments for reuse. List images and inspect their configuration and build details.

Source: https://www.ellipsis.dev/docs/api/vm-images

- [`GET /v1/vm-images`](https://www.ellipsis.dev/docs/api/vm-images/get-vm-images): List VM images
- [`GET /v1/vm-images/{image_id}`](https://www.ellipsis.dev/docs/api/vm-images/get-vm-images-image_id): Get a VM image

---

# Get a VM

> Read a machine and its most recent execution. The VM ID remains the same when a session resumes on that machine.

Source: https://www.ellipsis.dev/docs/api/vms/get-vms-vm_id

## GET /v1/vms/{vm_id}

Read a machine and its most recent execution. The VM ID remains the same when a session resumes on that machine.

Required permissions: read:environments.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration. Only the token's own VM.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "id": str,
  "latest_execution": {
    "cache_tier": str,
    "cost_sandbox_cpu": int,
    "cost_sandbox_memory": int,
    "cpu": float,
    "encrypted_ports": [
      int
    ],
    "environment_variable_keys": [
      str
    ],
    "failed_at": str,
    "hooks": {
      "after_checkout": { # str | null
        "run": str
      },
      "before_start": { # str | null
        "run": str
      },
      "build_base": { # str | null
        "inputs": [
          str
        ],
        "run": str
      },
      "post_clone": str,
      "post_start": str
    },
    "id": str,
    "memory_mib": int,
    "phase_timings": {
      "[str]": float
    },
    "post_clone": str,
    "post_start": str,
    "repositories": [
      {
        "id": int,
        "name": str,
        "owner_id": int,
        "owner_name": str,
        "sha": str
      }
    ],
    "running_at": str,
    "scheduled_at": str,
    "source": str,
    "source_session_id": str,
    "status": str,
    "terminated_at": str,
    "terminating_at": str,
    "timeout_seconds": int,
    "tunnels": [
      {
        "port": int,
        "tcp_host": str,
        "tcp_port": int,
        "tls_host": str,
        "tls_port": int,
        "tunnel_url": str,
        "unencrypted_host": str,
        "unencrypted_port": int
      }
    ],
    "type": str,
    "unencrypted_ports": [
      int
    ]
  },
  "status": str
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.vms.get("...")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.vms.get('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/vms/{vm_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "id": {
      "type": "string"
    },
    "latest_execution": {
      "properties": {
        "cache_tier": {
          "anyOf": [
            {
              "enum": [
                "exact",
                "incremental",
                "full"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "cost_sandbox_cpu": {
          "type": "integer"
        },
        "cost_sandbox_memory": {
          "type": "integer"
        },
        "cpu": {
          "type": "number"
        },
        "encrypted_ports": {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        "environment_variable_keys": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "failed_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "hooks": {
          "additionalProperties": false,
          "properties": {
            "after_checkout": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "run": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "run"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "before_start": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "run": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "run"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "build_base": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "inputs": {
                      "anyOf": [
                        {
                          "type": "array"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "run": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "inputs",
                    "run"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "post_clone": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "post_start": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "after_checkout",
            "before_start",
            "build_base",
            "post_clone",
            "post_start"
          ],
          "type": "object"
        },
        "id": {
          "type": "string"
        },
        "memory_mib": {
          "type": "integer"
        },
        "phase_timings": {
          "items": {
            "type": "number"
          },
          "type": "object"
        },
        "post_clone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "post_start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "repositories": {
          "items": {
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "owner_id": {
                "type": "integer"
              },
              "owner_name": {
                "type": "string"
              },
              "sha": {
                "type": "string"
              }
            },
            "required": [
              "owner_id",
              "owner_name",
              "id",
              "name",
              "sha"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "running_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "scheduled_at": {
          "format": "date-time",
          "type": "string"
        },
        "source": {
          "enum": [
            "cli",
            "web_ui",
            "ingest_pull_request_job_run",
            "session",
            "image_refresh",
            "test",
            "script"
          ],
          "type": "string"
        },
        "source_session_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "enum": [
            "scheduled",
            "building",
            "running",
            "released",
            "terminating",
            "terminated",
            "failed"
          ],
          "type": "string"
        },
        "terminated_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "terminating_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "timeout_seconds": {
          "type": "integer"
        },
        "tunnels": {
          "items": {
            "properties": {
              "port": {
                "type": "integer"
              },
              "tcp_host": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tcp_port": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tls_host": {
                "type": "string"
              },
              "tls_port": {
                "type": "integer"
              },
              "tunnel_url": {
                "type": "string"
              },
              "unencrypted_host": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "unencrypted_port": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "port",
              "tunnel_url",
              "tls_host",
              "tls_port"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "type": {
          "enum": [
            "claude_code"
          ],
          "type": "string"
        },
        "unencrypted_ports": {
          "items": {
            "type": "integer"
          },
          "type": "array"
        }
      },
      "required": [
        "id",
        "scheduled_at",
        "running_at",
        "terminating_at",
        "terminated_at",
        "failed_at",
        "type",
        "source",
        "source_session_id",
        "repositories",
        "status",
        "tunnels",
        "post_start",
        "post_clone",
        "environment_variable_keys",
        "timeout_seconds",
        "cpu",
        "memory_mib",
        "unencrypted_ports",
        "encrypted_ports",
        "cost_sandbox_cpu",
        "cost_sandbox_memory",
        "phase_timings",
        "cache_tier"
      ],
      "type": "object"
    },
    "status": {
      "enum": [
        "starting",
        "running",
        "paused",
        "deleting",
        "deleted",
        "unknown"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "latest_execution"
  ],
  "type": "object"
}
```

---

# List VMs

> List machines once each, newest execution first. Includes paused and deleted VMs and their last recorded state. Use limit and offset to page through results.

Source: https://www.ellipsis.dev/docs/api/vms/get-vms

## GET /v1/vms

List machines once each, newest execution first. Includes paused and deleted VMs and their last recorded state. Use limit and offset to page through results.

Required permissions: read:environments.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration. Only the token's own VM.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "next_offset": int,
  "vms": [
    {
      "id": str,
      "latest_execution": {
        "cache_tier": str,
        "cost_sandbox_cpu": int,
        "cost_sandbox_memory": int,
        "cpu": float,
        "encrypted_ports": [
          int
        ],
        "environment_variable_keys": [
          str
        ],
        "failed_at": str,
        "hooks": {
          "after_checkout": { # str | null
            "run": str
          },
          "before_start": { # str | null
            "run": str
          },
          "build_base": { # str | null
            "inputs": [
              str
            ],
            "run": str
          },
          "post_clone": str,
          "post_start": str
        },
        "id": str,
        "memory_mib": int,
        "phase_timings": {
          "[str]": float
        },
        "post_clone": str,
        "post_start": str,
        "repositories": [
          {
            "id": int,
            "name": str,
            "owner_id": int,
            "owner_name": str,
            "sha": str
          }
        ],
        "running_at": str,
        "scheduled_at": str,
        "source": str,
        "source_session_id": str,
        "status": str,
        "terminated_at": str,
        "terminating_at": str,
        "timeout_seconds": int,
        "tunnels": [
          {
            "port": int,
            "tcp_host": str,
            "tcp_port": int,
            "tls_host": str,
            "tls_port": int,
            "tunnel_url": str,
            "unencrypted_host": str,
            "unencrypted_port": int
          }
        ],
        "type": str,
        "unencrypted_ports": [
          int
        ]
      },
      "status": str
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.vms.list()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.vms.list();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/vms" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "next_offset": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "vms": {
      "items": {
        "properties": {
          "id": {
            "type": "string"
          },
          "latest_execution": {
            "properties": {
              "cache_tier": {
                "anyOf": [
                  {
                    "enum": [
                      "exact",
                      "incremental",
                      "full"
                    ],
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "cost_sandbox_cpu": {
                "type": "integer"
              },
              "cost_sandbox_memory": {
                "type": "integer"
              },
              "cpu": {
                "type": "number"
              },
              "encrypted_ports": {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              },
              "environment_variable_keys": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "failed_at": {
                "anyOf": [
                  {
                    "format": "date-time",
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "hooks": {
                "additionalProperties": false,
                "properties": {
                  "after_checkout": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "before_start": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "build_base": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "post_clone": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "post_start": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "after_checkout",
                  "before_start",
                  "build_base",
                  "post_clone",
                  "post_start"
                ],
                "type": "object"
              },
              "id": {
                "type": "string"
              },
              "memory_mib": {
                "type": "integer"
              },
              "phase_timings": {
                "items": {
                  "type": "number"
                },
                "type": "object"
              },
              "post_clone": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "post_start": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "repositories": {
                "items": {
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "owner_id": {
                      "type": "integer"
                    },
                    "owner_name": {
                      "type": "string"
                    },
                    "sha": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "owner_id",
                    "owner_name",
                    "id",
                    "name",
                    "sha"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "running_at": {
                "anyOf": [
                  {
                    "format": "date-time",
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "scheduled_at": {
                "format": "date-time",
                "type": "string"
              },
              "source": {
                "enum": [
                  "cli",
                  "web_ui",
                  "ingest_pull_request_job_run",
                  "session",
                  "image_refresh",
                  "test",
                  "script"
                ],
                "type": "string"
              },
              "source_session_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "enum": [
                  "scheduled",
                  "building",
                  "running",
                  "released",
                  "terminating",
                  "terminated",
                  "failed"
                ],
                "type": "string"
              },
              "terminated_at": {
                "anyOf": [
                  {
                    "format": "date-time",
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "terminating_at": {
                "anyOf": [
                  {
                    "format": "date-time",
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "timeout_seconds": {
                "type": "integer"
              },
              "tunnels": {
                "items": {
                  "properties": {
                    "port": {
                      "type": "integer"
                    },
                    "tcp_host": {
                      "type": "object"
                    },
                    "tcp_port": {
                      "type": "object"
                    },
                    "tls_host": {
                      "type": "string"
                    },
                    "tls_port": {
                      "type": "integer"
                    },
                    "tunnel_url": {
                      "type": "string"
                    },
                    "unencrypted_host": {
                      "type": "object"
                    },
                    "unencrypted_port": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "port",
                    "tunnel_url",
                    "tls_host",
                    "tls_port"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "type": {
                "enum": [
                  "claude_code"
                ],
                "type": "string"
              },
              "unencrypted_ports": {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              }
            },
            "required": [
              "id",
              "scheduled_at",
              "running_at",
              "terminating_at",
              "terminated_at",
              "failed_at",
              "type",
              "source",
              "source_session_id",
              "repositories",
              "status",
              "tunnels",
              "post_start",
              "post_clone",
              "environment_variable_keys",
              "timeout_seconds",
              "cpu",
              "memory_mib",
              "unencrypted_ports",
              "encrypted_ports",
              "cost_sandbox_cpu",
              "cost_sandbox_memory",
              "phase_timings",
              "cache_tier"
            ],
            "type": "object"
          },
          "status": {
            "enum": [
              "starting",
              "running",
              "paused",
              "deleting",
              "deleted",
              "unknown"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "latest_execution"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "vms",
    "next_offset"
  ],
  "type": "object"
}
```

---

# VMs

> Virtual machines provide the compute for agent sessions. List machines and inspect their latest recorded state.

Source: https://www.ellipsis.dev/docs/api/vms

- [`GET /v1/vms`](https://www.ellipsis.dev/docs/api/vms/get-vms): List VMs
- [`GET /v1/vms/{vm_id}`](https://www.ellipsis.dev/docs/api/vms/get-vms-vm_id): Get a VM

---

# Delete a webhook

> Delete a webhook and cancel outstanding deliveries.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints/delete-webhooks-webhook_id

## DELETE /v1/webhooks/{webhook_id}

Delete a webhook and cancel outstanding deliveries.

Required permissions: delete:webhooks.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.webhooks.delete("webhook_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.webhooks.delete("webhook_example");
console.log(result);
```

### cURL

```bash
curl -X DELETE "https://api.ellipsis.dev/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

---

# Get a delivery

> Inspect the event payload and delivery attempts.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks-deliveries-delivery_id

## GET /v1/webhooks/deliveries/{delivery_id}

Inspect the event payload and delivery attempts.

Required permissions: read:webhooks.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "delivery": {
    "attempt_count": int,
    "attempts": [
      {
        "completed_at": str,
        "duration_ms": int,
        "error": str,
        "http_status": int,
        "id": str,
        "number": int,
        "started_at": str
      }
    ],
    "completed_at": str,
    "created_at": str,
    "event_id": str,
    "event_type": str,
    "id": str,
    "last_error": str,
    "last_http_status": int,
    "next_attempt_at": str,
    "payload": { # WebhookSessionCreateEvent | WebhookPingEvent
      "api_version": "v1",
      "created_at": str,
      "data": {
        "session": {
          "agent": {
            "config": {
              "ellipsis": {
                "description": str,
                "enabled": bool,
                "kind": "agent",
                "metadata": {
                  "annotations": {
                    "[str]": str
                  },
                  "labels": [
                    str
                  ]
                },
                "name": str,
                "version": str
              },
              "input": {
                "json_schema": {
                  "[str]": any
                },
                "message": str
              },
              "session": {
                "budget": {
                  "day": float,
                  "month": float,
                  "session": float,
                  "week": float
                },
                "claude_code": {
                  "effort": str,
                  "fallback_model": str,
                  "max_turns": int,
                  "model": str,
                  "prompt": str,
                  "settings": {
                    "path": str,
                    "repository": {
                      "name": str,
                      "owner": str,
                      "ref": str
                    }
                  }
                },
                "codex": {
                  "effort": str,
                  "model": str,
                  "prompt": str
                },
                "environment": { # str
                  "compute": {
                    "cpu": int,
                    "memory": { # str | null
                      "gb": int,
                      "mb": int
                    },
                    "timeout": { # str | null
                      "hours": int,
                      "minutes": int,
                      "seconds": int
                    }
                  },
                  "hooks": {
                    "after_checkout": { # str | null
                      "run": str
                    },
                    "before_start": { # str | null
                      "run": str
                    },
                    "build_base": { # str | null
                      "inputs": [
                        str
                      ],
                      "run": str
                    },
                    "post_clone": str,
                    "post_start": str
                  },
                  "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
                  # McpRemoteServer]
                    {
                      "args": [
                        str
                      ],
                      "command": str,
                      "env": {
                        "[str]": str
                      },
                      "name": str
                    }
                  ],
                  "repositories": [
                    {
                      "name": str,
                      "owner": str,
                      "ref": str
                    }
                  ],
                  "variables": [
                    {
                      "name": str,
                      "value": str
                    }
                  ]
                },
                "output": {
                  "json_schema": {
                    "[str]": any
                  }
                },
                "permissions": {
                  "ellipsis": { # bool | str
                    "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                      {
                        "level": str,
                        "match": [
                          str
                        ]
                      }
                    ]
                  },
                  "github": {
                    "permissions": { # "read_only" | null
                      "[str]": str
                    },
                    "repositories": [
                      str
                    ]
                  }
                },
                "skills": [
                  {
                    "path": str,
                    "repository": {
                      "name": str,
                      "owner": str,
                      "ref": str
                    }
                  }
                ]
              },
              "trigger": { # null | ReactTrigger | CronTrigger
                "issue": {
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "labels": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "linear_issue": {
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "on": [
                    str
                  ]
                },
                "pull_request": {
                  "base": [
                    str
                  ],
                  "draft": bool,
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "head": [
                    str
                  ],
                  "labels": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "paths": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "push": {
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "paths": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "sentry": {
                  "on": [
                    str
                  ],
                  "projects": [
                    str
                  ]
                },
                "slack_channel": {},
                "type": "react"
              }
            },
            "id": str
          },
          "attribution": {
            "id": str,
            "type": str,
            "user": {
              "avatar_url": str,
              "id": int,
              "login": str,
              "type": str
            }
          },
          "budget": float,
          "claude_code": {
            "effort": str,
            "fallback_model": str,
            "max_turns": int,
            "model": str,
            "prompt": str,
            "settings": {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          },
          "codex": {
            "effort": str,
            "model": str,
            "prompt": str
          },
          "cost": {
            "cpu": int,
            "fee": int,
            "llm": int,
            "memory": int,
            "total": int
          },
          "environment": {
            "compute": {
              "cpu": int,
              "memory": { # str | null
                "gb": int,
                "mb": int
              },
              "timeout": { # str | null
                "hours": int,
                "minutes": int,
                "seconds": int
              }
            },
            "hooks": {
              "after_checkout": { # str | null
                "run": str
              },
              "before_start": { # str | null
                "run": str
              },
              "build_base": { # str | null
                "inputs": [
                  str
                ],
                "run": str
              },
              "post_clone": str,
              "post_start": str
            },
            "id": str,
            "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
            # McpRemoteServer]
              {
                "args": [
                  str
                ],
                "command": str,
                "env": {
                  "[str]": str
                },
                "name": str
              }
            ],
            "repositories": [
              {
                "name": str,
                "owner": str,
                "ref": str
              }
            ],
            "source": str,
            "variables": [
              {
                "name": str,
                "value": str
              }
            ]
          },
          "event": { # null | GithubPullRequestEvent | GithubIssueEvent |
          # GithubPushEvent | LinearIssueEvent | SlackMessageEvent |
          # SlackChannelCreatedEvent | SentryAlertEvent
            "action": str, # "review_commented"
            "actor": {
              "avatar_url": str,
              "is_bot": bool,
              "name": str
            },
            "branch": str,
            "number": int,
            "repository": str,
            "title": str,
            "type": "github.pull_request",
            "url": str
          },
          "git": {
            "repos": [
              {
                "commits": [
                  {
                    "committed_at": str,
                    "pushed": bool,
                    "sha": str,
                    "subject": str
                  }
                ],
                "commits_total": int,
                "full_name": str,
                "local_commit": str,
                "local_uncommitted_files": [
                  {
                    "additions": int,
                    "deletions": int,
                    "path": str,
                    "status": str
                  }
                ],
                "prs": [
                  {
                    "gh_pr_id": int,
                    "number": int,
                    "title": str,
                    "url": str
                  }
                ],
                "remote_branch": str,
                "remote_commit": str
              }
            ]
          },
          "handler": {
            "agent_name": str,
            "id": str,
            "service": str,
            "sha": str
          },
          "id": str,
          "lifecycle": {
            "archived": {
              "at": str,
              "by": {
                "avatar_url": str,
                "id": int,
                "login": str,
                "type": str
              }
            },
            "conversation": str,
            "detail": str,
            "interactive": bool,
            "last_execution_result": {
              "completion_reason": str,
              "detail": str
            },
            "prompting": {
              "blocked_reason": str,
              "detail": str,
              "enabled": bool,
              "surface_name": str
            },
            "status": str,
            "stopped": {
              "at": str,
              "by": {
                "avatar_url": str,
                "id": int,
                "login": str,
                "type": str
              }
            },
            "timestamps": {
              "created_at": str,
              "last_activity_at": str,
              "last_message_at": str,
              "updated_at": str
            }
          },
          "metadata": {
            "[str]": str
          },
          "output": {
            "json_schema": {
              "[str]": any
            }
          },
          "parent": {
            "session_id": str
          },
          "permissions": {
            "ellipsis": { # bool | str
              "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                {
                  "level": str,
                  "match": [
                    str
                  ]
                }
              ]
            },
            "github": {
              "permissions": { # "read_only" | null
                "[str]": str
              },
              "repositories": [
                str
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ],
          "source": str,
          "summary": {
            "created_at": str,
            "description": str
          },
          "tokens": {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": int
          }
        }
      },
      "id": str,
      "type": "session.create"
    },
    "status": str,
    "url": str,
    "webhook_id": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.webhooks.deliveries.get("delivery_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.webhooks.deliveries.get("delivery_example");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/webhooks/deliveries/{delivery_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "delivery": {
      "properties": {
        "attempt_count": {
          "type": "integer"
        },
        "attempts": {
          "items": {
            "properties": {
              "completed_at": {
                "anyOf": [
                  {
                    "format": "date-time",
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "duration_ms": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "error": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "http_status": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "type": "string"
              },
              "number": {
                "type": "integer"
              },
              "started_at": {
                "format": "date-time",
                "type": "string"
              }
            },
            "required": [
              "id",
              "number",
              "started_at",
              "completed_at",
              "http_status",
              "duration_ms",
              "error"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "completed_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "event_id": {
          "type": "string"
        },
        "event_type": {
          "enum": [
            "session.create",
            "webhook.ping"
          ],
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "last_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_http_status": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "next_attempt_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "payload": {
          "oneOf": [
            {
              "properties": {
                "api_version": {
                  "const": "v1",
                  "default": "v1",
                  "type": "string"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "data": {
                  "properties": {
                    "session": {
                      "additionalProperties": false,
                      "allOf": [
                        {
                          "type": "object"
                        }
                      ],
                      "properties": {
                        "agent": {
                          "type": "object"
                        },
                        "attribution": {
                          "type": "object"
                        },
                        "budget": {
                          "type": "number"
                        },
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "object"
                        },
                        "cost": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "event": {
                          "type": "object"
                        },
                        "git": {
                          "type": "object"
                        },
                        "handler": {
                          "type": "object"
                        },
                        "id": {
                          "type": "string"
                        },
                        "lifecycle": {
                          "type": "object"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "parent": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        },
                        "source": {
                          "type": "string"
                        },
                        "summary": {
                          "type": "object"
                        },
                        "tokens": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "agent",
                        "attribution",
                        "budget",
                        "claude_code",
                        "codex",
                        "cost",
                        "environment",
                        "event",
                        "git",
                        "handler",
                        "id",
                        "lifecycle",
                        "metadata",
                        "output",
                        "parent",
                        "permissions",
                        "skills",
                        "source",
                        "summary",
                        "tokens"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "session"
                  ],
                  "type": "object"
                },
                "id": {
                  "type": "string"
                },
                "type": {
                  "const": "session.create",
                  "default": "session.create",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "created_at",
                "data"
              ],
              "type": "object"
            },
            {
              "properties": {
                "api_version": {
                  "const": "v1",
                  "default": "v1",
                  "type": "string"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "data": {
                  "properties": {
                    "webhook_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "webhook_id"
                  ],
                  "type": "object"
                },
                "id": {
                  "type": "string"
                },
                "type": {
                  "const": "webhook.ping",
                  "default": "webhook.ping",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "created_at",
                "data"
              ],
              "type": "object"
            }
          ]
        },
        "status": {
          "enum": [
            "pending",
            "delivering",
            "retrying",
            "succeeded",
            "failed",
            "cancelled"
          ],
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "webhook_id": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "webhook_id",
        "event_id",
        "event_type",
        "url",
        "status",
        "created_at",
        "completed_at",
        "attempt_count",
        "next_attempt_at",
        "last_http_status",
        "last_error",
        "payload",
        "attempts"
      ],
      "type": "object"
    }
  },
  "required": [
    "delivery"
  ],
  "type": "object"
}
```

---

# List deliveries

> List recent deliveries and their statuses.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks-deliveries

## GET /v1/webhooks/deliveries

List recent deliveries and their statuses.

Required permissions: read:webhooks.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "deliveries": [
    {
      "attempt_count": int,
      "completed_at": str,
      "created_at": str,
      "event_id": str,
      "event_type": str,
      "id": str,
      "last_error": str,
      "last_http_status": int,
      "next_attempt_at": str,
      "status": str,
      "url": str,
      "webhook_id": str
    }
  ],
  "has_more": bool,
  "next_cursor": str
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

for item in client.webhooks.deliveries.list():
    print(item)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

for await (const item of await client.webhooks.deliveries.list()) {
  console.log(item);
}
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/webhooks/deliveries" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "deliveries": {
      "items": {
        "properties": {
          "attempt_count": {
            "type": "integer"
          },
          "completed_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "event_id": {
            "type": "string"
          },
          "event_type": {
            "enum": [
              "session.create",
              "webhook.ping"
            ],
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "last_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "last_http_status": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "next_attempt_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "enum": [
              "pending",
              "delivering",
              "retrying",
              "succeeded",
              "failed",
              "cancelled"
            ],
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "webhook_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "webhook_id",
          "event_id",
          "event_type",
          "url",
          "status",
          "created_at",
          "completed_at",
          "attempt_count",
          "next_attempt_at",
          "last_http_status",
          "last_error"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "has_more": {
      "default": false,
      "type": "boolean"
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "deliveries"
  ],
  "type": "object"
}
```

---

# Get a webhook

> Read a webhook endpoint and its state. The signing secret is not returned.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks-webhook_id

## GET /v1/webhooks/{webhook_id}

Read a webhook endpoint and its state. The signing secret is not returned.

Required permissions: read:webhooks.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "webhook": {
    "activated_at": str,
    "created_at": str,
    "description": str,
    "events": [
      "session.create"
    ],
    "id": str,
    "last_delivery": {
      "attempt_count": int,
      "completed_at": str,
      "created_at": str,
      "event_id": str,
      "event_type": str,
      "id": str,
      "last_error": str,
      "last_http_status": int,
      "next_attempt_at": str,
      "status": str,
      "url": str,
      "webhook_id": str
    },
    "state": str,
    "updated_at": str,
    "url": str,
    "verified_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.webhooks.get("webhook_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.webhooks.get("webhook_example");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "webhook": {
      "properties": {
        "activated_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "events": {
          "items": {
            "const": "session.create",
            "type": "string"
          },
          "type": "array"
        },
        "id": {
          "type": "string"
        },
        "last_delivery": {
          "anyOf": [
            {
              "properties": {
                "attempt_count": {
                  "type": "integer"
                },
                "completed_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "event_id": {
                  "type": "string"
                },
                "event_type": {
                  "enum": [
                    "session.create",
                    "webhook.ping"
                  ],
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "last_error": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "last_http_status": {
                  "anyOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "next_attempt_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "enum": [
                    "pending",
                    "delivering",
                    "retrying",
                    "succeeded",
                    "failed",
                    "cancelled"
                  ],
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "webhook_id": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "webhook_id",
                "event_id",
                "event_type",
                "url",
                "status",
                "created_at",
                "completed_at",
                "attempt_count",
                "next_attempt_at",
                "last_http_status",
                "last_error"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "state": {
          "enum": [
            "unverified",
            "pending",
            "active"
          ],
          "type": "string"
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "verified_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "url",
        "events",
        "description",
        "state",
        "created_at",
        "updated_at",
        "verified_at",
        "activated_at"
      ],
      "type": "object"
    }
  },
  "required": [
    "webhook"
  ],
  "type": "object"
}
```

---

# List webhooks

> List webhook endpoints and activation states.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks

## GET /v1/webhooks

List webhook endpoints and activation states.

Required permissions: read:webhooks.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "webhooks": [
    {
      "activated_at": str,
      "created_at": str,
      "description": str,
      "events": [
        "session.create"
      ],
      "id": str,
      "last_delivery": {
        "attempt_count": int,
        "completed_at": str,
        "created_at": str,
        "event_id": str,
        "event_type": str,
        "id": str,
        "last_error": str,
        "last_http_status": int,
        "next_attempt_at": str,
        "status": str,
        "url": str,
        "webhook_id": str
      },
      "state": str,
      "updated_at": str,
      "url": str,
      "verified_at": str
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.webhooks.list()
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.webhooks.list();
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/webhooks" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "webhooks": {
      "items": {
        "properties": {
          "activated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "events": {
            "items": {
              "const": "session.create",
              "type": "string"
            },
            "type": "array"
          },
          "id": {
            "type": "string"
          },
          "last_delivery": {
            "anyOf": [
              {
                "properties": {
                  "attempt_count": {
                    "type": "integer"
                  },
                  "completed_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "event_id": {
                    "type": "string"
                  },
                  "event_type": {
                    "enum": [
                      "session.create",
                      "webhook.ping"
                    ],
                    "type": "string"
                  },
                  "id": {
                    "type": "string"
                  },
                  "last_error": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "last_http_status": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "next_attempt_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "status": {
                    "enum": [
                      "pending",
                      "delivering",
                      "retrying",
                      "succeeded",
                      "failed",
                      "cancelled"
                    ],
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "webhook_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "webhook_id",
                  "event_id",
                  "event_type",
                  "url",
                  "status",
                  "created_at",
                  "completed_at",
                  "attempt_count",
                  "next_attempt_at",
                  "last_http_status",
                  "last_error"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "state": {
            "enum": [
              "unverified",
              "pending",
              "active"
            ],
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "verified_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "url",
          "events",
          "description",
          "state",
          "created_at",
          "updated_at",
          "verified_at",
          "activated_at"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "webhooks"
  ],
  "type": "object"
}
```

---

# Webhooks

> Webhooks send events to your application. Configure destinations, send test events, and inspect delivery attempts.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints

- [`POST /v1/webhooks`](https://www.ellipsis.dev/docs/api/webhook-endpoints/post-webhooks): Create a webhook
- [`GET /v1/webhooks`](https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks): List webhooks
- [`GET /v1/webhooks/{webhook_id}`](https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks-webhook_id): Get a webhook
- [`PUT /v1/webhooks/{webhook_id}`](https://www.ellipsis.dev/docs/api/webhook-endpoints/put-webhooks-webhook_id): Update a webhook
- [`DELETE /v1/webhooks/{webhook_id}`](https://www.ellipsis.dev/docs/api/webhook-endpoints/delete-webhooks-webhook_id): Delete a webhook
- [`GET /v1/webhooks/deliveries`](https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks-deliveries): List deliveries
- [`GET /v1/webhooks/deliveries/{delivery_id}`](https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks-deliveries-delivery_id): Get a delivery
- [`POST /v1/webhooks/{webhook_id}/ping`](https://www.ellipsis.dev/docs/api/webhook-endpoints/post-webhooks-webhook_id-ping): Send a test event

---

# Send a test event

> Send a signed webhook.ping. The receiver must return HTTP 200.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints/post-webhooks-webhook_id-ping

## POST /v1/webhooks/{webhook_id}/ping

Send a signed webhook.ping. The receiver must return HTTP 200.

Required permissions: write:webhooks.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Response

```text
{
  "delivery": {
    "attempt_count": int,
    "attempts": [
      {
        "completed_at": str,
        "duration_ms": int,
        "error": str,
        "http_status": int,
        "id": str,
        "number": int,
        "started_at": str
      }
    ],
    "completed_at": str,
    "created_at": str,
    "event_id": str,
    "event_type": str,
    "id": str,
    "last_error": str,
    "last_http_status": int,
    "next_attempt_at": str,
    "payload": { # WebhookSessionCreateEvent | WebhookPingEvent
      "api_version": "v1",
      "created_at": str,
      "data": {
        "session": {
          "agent": {
            "config": {
              "ellipsis": {
                "description": str,
                "enabled": bool,
                "kind": "agent",
                "metadata": {
                  "annotations": {
                    "[str]": str
                  },
                  "labels": [
                    str
                  ]
                },
                "name": str,
                "version": str
              },
              "input": {
                "json_schema": {
                  "[str]": any
                },
                "message": str
              },
              "session": {
                "budget": {
                  "day": float,
                  "month": float,
                  "session": float,
                  "week": float
                },
                "claude_code": {
                  "effort": str,
                  "fallback_model": str,
                  "max_turns": int,
                  "model": str,
                  "prompt": str,
                  "settings": {
                    "path": str,
                    "repository": {
                      "name": str,
                      "owner": str,
                      "ref": str
                    }
                  }
                },
                "codex": {
                  "effort": str,
                  "model": str,
                  "prompt": str
                },
                "environment": { # str
                  "compute": {
                    "cpu": int,
                    "memory": { # str | null
                      "gb": int,
                      "mb": int
                    },
                    "timeout": { # str | null
                      "hours": int,
                      "minutes": int,
                      "seconds": int
                    }
                  },
                  "hooks": {
                    "after_checkout": { # str | null
                      "run": str
                    },
                    "before_start": { # str | null
                      "run": str
                    },
                    "build_base": { # str | null
                      "inputs": [
                        str
                      ],
                      "run": str
                    },
                    "post_clone": str,
                    "post_start": str
                  },
                  "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
                  # McpRemoteServer]
                    {
                      "args": [
                        str
                      ],
                      "command": str,
                      "env": {
                        "[str]": str
                      },
                      "name": str
                    }
                  ],
                  "repositories": [
                    {
                      "name": str,
                      "owner": str,
                      "ref": str
                    }
                  ],
                  "variables": [
                    {
                      "name": str,
                      "value": str
                    }
                  ]
                },
                "output": {
                  "json_schema": {
                    "[str]": any
                  }
                },
                "permissions": {
                  "ellipsis": { # bool | str
                    "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                      {
                        "level": str,
                        "match": [
                          str
                        ]
                      }
                    ]
                  },
                  "github": {
                    "permissions": { # "read_only" | null
                      "[str]": str
                    },
                    "repositories": [
                      str
                    ]
                  }
                },
                "skills": [
                  {
                    "path": str,
                    "repository": {
                      "name": str,
                      "owner": str,
                      "ref": str
                    }
                  }
                ]
              },
              "trigger": { # null | ReactTrigger | CronTrigger
                "issue": {
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "labels": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "linear_issue": {
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "on": [
                    str
                  ]
                },
                "pull_request": {
                  "base": [
                    str
                  ],
                  "draft": bool,
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "head": [
                    str
                  ],
                  "labels": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "paths": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "push": {
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "paths": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "sentry": {
                  "on": [
                    str
                  ],
                  "projects": [
                    str
                  ]
                },
                "slack_channel": {},
                "type": "react"
              }
            },
            "id": str
          },
          "attribution": {
            "id": str,
            "type": str,
            "user": {
              "avatar_url": str,
              "id": int,
              "login": str,
              "type": str
            }
          },
          "budget": float,
          "claude_code": {
            "effort": str,
            "fallback_model": str,
            "max_turns": int,
            "model": str,
            "prompt": str,
            "settings": {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          },
          "codex": {
            "effort": str,
            "model": str,
            "prompt": str
          },
          "cost": {
            "cpu": int,
            "fee": int,
            "llm": int,
            "memory": int,
            "total": int
          },
          "environment": {
            "compute": {
              "cpu": int,
              "memory": { # str | null
                "gb": int,
                "mb": int
              },
              "timeout": { # str | null
                "hours": int,
                "minutes": int,
                "seconds": int
              }
            },
            "hooks": {
              "after_checkout": { # str | null
                "run": str
              },
              "before_start": { # str | null
                "run": str
              },
              "build_base": { # str | null
                "inputs": [
                  str
                ],
                "run": str
              },
              "post_clone": str,
              "post_start": str
            },
            "id": str,
            "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
            # McpRemoteServer]
              {
                "args": [
                  str
                ],
                "command": str,
                "env": {
                  "[str]": str
                },
                "name": str
              }
            ],
            "repositories": [
              {
                "name": str,
                "owner": str,
                "ref": str
              }
            ],
            "source": str,
            "variables": [
              {
                "name": str,
                "value": str
              }
            ]
          },
          "event": { # null | GithubPullRequestEvent | GithubIssueEvent |
          # GithubPushEvent | LinearIssueEvent | SlackMessageEvent |
          # SlackChannelCreatedEvent | SentryAlertEvent
            "action": str, # "review_commented"
            "actor": {
              "avatar_url": str,
              "is_bot": bool,
              "name": str
            },
            "branch": str,
            "number": int,
            "repository": str,
            "title": str,
            "type": "github.pull_request",
            "url": str
          },
          "git": {
            "repos": [
              {
                "commits": [
                  {
                    "committed_at": str,
                    "pushed": bool,
                    "sha": str,
                    "subject": str
                  }
                ],
                "commits_total": int,
                "full_name": str,
                "local_commit": str,
                "local_uncommitted_files": [
                  {
                    "additions": int,
                    "deletions": int,
                    "path": str,
                    "status": str
                  }
                ],
                "prs": [
                  {
                    "gh_pr_id": int,
                    "number": int,
                    "title": str,
                    "url": str
                  }
                ],
                "remote_branch": str,
                "remote_commit": str
              }
            ]
          },
          "handler": {
            "agent_name": str,
            "id": str,
            "service": str,
            "sha": str
          },
          "id": str,
          "lifecycle": {
            "archived": {
              "at": str,
              "by": {
                "avatar_url": str,
                "id": int,
                "login": str,
                "type": str
              }
            },
            "conversation": str,
            "detail": str,
            "interactive": bool,
            "last_execution_result": {
              "completion_reason": str,
              "detail": str
            },
            "prompting": {
              "blocked_reason": str,
              "detail": str,
              "enabled": bool,
              "surface_name": str
            },
            "status": str,
            "stopped": {
              "at": str,
              "by": {
                "avatar_url": str,
                "id": int,
                "login": str,
                "type": str
              }
            },
            "timestamps": {
              "created_at": str,
              "last_activity_at": str,
              "last_message_at": str,
              "updated_at": str
            }
          },
          "metadata": {
            "[str]": str
          },
          "output": {
            "json_schema": {
              "[str]": any
            }
          },
          "parent": {
            "session_id": str
          },
          "permissions": {
            "ellipsis": { # bool | str
              "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                {
                  "level": str,
                  "match": [
                    str
                  ]
                }
              ]
            },
            "github": {
              "permissions": { # "read_only" | null
                "[str]": str
              },
              "repositories": [
                str
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ],
          "source": str,
          "summary": {
            "created_at": str,
            "description": str
          },
          "tokens": {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": int
          }
        }
      },
      "id": str,
      "type": "session.create"
    },
    "status": str,
    "url": str,
    "webhook_id": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.webhooks.ping("webhook_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.webhooks.ping("webhook_example");
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/webhooks/{webhook_id}/ping" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "delivery": {
      "properties": {
        "attempt_count": {
          "type": "integer"
        },
        "attempts": {
          "items": {
            "properties": {
              "completed_at": {
                "anyOf": [
                  {
                    "format": "date-time",
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "duration_ms": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "error": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "http_status": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "type": "string"
              },
              "number": {
                "type": "integer"
              },
              "started_at": {
                "format": "date-time",
                "type": "string"
              }
            },
            "required": [
              "id",
              "number",
              "started_at",
              "completed_at",
              "http_status",
              "duration_ms",
              "error"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "completed_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "event_id": {
          "type": "string"
        },
        "event_type": {
          "enum": [
            "session.create",
            "webhook.ping"
          ],
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "last_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_http_status": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "next_attempt_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "payload": {
          "oneOf": [
            {
              "properties": {
                "api_version": {
                  "const": "v1",
                  "default": "v1",
                  "type": "string"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "data": {
                  "properties": {
                    "session": {
                      "additionalProperties": false,
                      "allOf": [
                        {
                          "type": "object"
                        }
                      ],
                      "properties": {
                        "agent": {
                          "type": "object"
                        },
                        "attribution": {
                          "type": "object"
                        },
                        "budget": {
                          "type": "number"
                        },
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "object"
                        },
                        "cost": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "event": {
                          "type": "object"
                        },
                        "git": {
                          "type": "object"
                        },
                        "handler": {
                          "type": "object"
                        },
                        "id": {
                          "type": "string"
                        },
                        "lifecycle": {
                          "type": "object"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "parent": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        },
                        "source": {
                          "type": "string"
                        },
                        "summary": {
                          "type": "object"
                        },
                        "tokens": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "agent",
                        "attribution",
                        "budget",
                        "claude_code",
                        "codex",
                        "cost",
                        "environment",
                        "event",
                        "git",
                        "handler",
                        "id",
                        "lifecycle",
                        "metadata",
                        "output",
                        "parent",
                        "permissions",
                        "skills",
                        "source",
                        "summary",
                        "tokens"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "session"
                  ],
                  "type": "object"
                },
                "id": {
                  "type": "string"
                },
                "type": {
                  "const": "session.create",
                  "default": "session.create",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "created_at",
                "data"
              ],
              "type": "object"
            },
            {
              "properties": {
                "api_version": {
                  "const": "v1",
                  "default": "v1",
                  "type": "string"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "data": {
                  "properties": {
                    "webhook_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "webhook_id"
                  ],
                  "type": "object"
                },
                "id": {
                  "type": "string"
                },
                "type": {
                  "const": "webhook.ping",
                  "default": "webhook.ping",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "created_at",
                "data"
              ],
              "type": "object"
            }
          ]
        },
        "status": {
          "enum": [
            "pending",
            "delivering",
            "retrying",
            "succeeded",
            "failed",
            "cancelled"
          ],
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "webhook_id": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "webhook_id",
        "event_id",
        "event_type",
        "url",
        "status",
        "created_at",
        "completed_at",
        "attempt_count",
        "next_attempt_at",
        "last_http_status",
        "last_error",
        "payload",
        "attempts"
      ],
      "type": "object"
    }
  },
  "required": [
    "delivery"
  ],
  "type": "object"
}
```

---

# Create a webhook

> Create a session-event webhook. Save the signing secret returned once in this response. Verify the initial ping, then request activation through Support.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints/post-webhooks

## POST /v1/webhooks

Create a session-event webhook. Save the signing secret returned once in this response. Verify the initial ping, then request activation through Support.

Required permissions: write:webhooks.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Request

```text
{
  "description": str,
  "events": [
    "session.create"
  ],
  "url": str
}
```

### Response

```text
{
  "secret": str,
  "webhook": {
    "activated_at": str,
    "created_at": str,
    "description": str,
    "events": [
      "session.create"
    ],
    "id": str,
    "last_delivery": {
      "attempt_count": int,
      "completed_at": str,
      "created_at": str,
      "event_id": str,
      "event_type": str,
      "id": str,
      "last_error": str,
      "last_http_status": int,
      "next_attempt_at": str,
      "status": str,
      "url": str,
      "webhook_id": str
    },
    "state": str,
    "updated_at": str,
    "url": str,
    "verified_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.WebhookConfigRequest.model_validate(
    {
      "url": "https://example.com/ellipsis",
      "events": [
        "session.create"
      ]
    }
)

result = client.webhooks.create(request.events, request.url)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.webhooks.create>[0] = {
  "url": "https://example.com/ellipsis",
  "events": [
    "session.create"
  ]
};

const result = await client.webhooks.create(request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/webhooks" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/ellipsis",
  "events": [
    "session.create"
  ]
}'
```

### Request schema

```json
{
  "additionalProperties": false,
  "examples": [
    {
      "events": [
        "session.create"
      ],
      "url": "https://example.com/hooks"
    }
  ],
  "properties": {
    "description": {
      "anyOf": [
        {
          "maxLength": 500,
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "events": {
      "examples": [
        [
          "session.create"
        ]
      ],
      "items": {
        "const": "session.create",
        "type": "string"
      },
      "maxItems": 1,
      "minItems": 1,
      "type": "array"
    },
    "url": {
      "examples": [
        "https://example.com/hooks"
      ],
      "maxLength": 2048,
      "type": "string"
    }
  },
  "required": [
    "url",
    "events"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "secret": {
      "type": "string"
    },
    "webhook": {
      "properties": {
        "activated_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "events": {
          "items": {
            "const": "session.create",
            "type": "string"
          },
          "type": "array"
        },
        "id": {
          "type": "string"
        },
        "last_delivery": {
          "anyOf": [
            {
              "properties": {
                "attempt_count": {
                  "type": "integer"
                },
                "completed_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "event_id": {
                  "type": "string"
                },
                "event_type": {
                  "enum": [
                    "session.create",
                    "webhook.ping"
                  ],
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "last_error": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "last_http_status": {
                  "anyOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "next_attempt_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "enum": [
                    "pending",
                    "delivering",
                    "retrying",
                    "succeeded",
                    "failed",
                    "cancelled"
                  ],
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "webhook_id": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "webhook_id",
                "event_id",
                "event_type",
                "url",
                "status",
                "created_at",
                "completed_at",
                "attempt_count",
                "next_attempt_at",
                "last_http_status",
                "last_error"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "state": {
          "enum": [
            "unverified",
            "pending",
            "active"
          ],
          "type": "string"
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "verified_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "url",
        "events",
        "description",
        "state",
        "created_at",
        "updated_at",
        "verified_at",
        "activated_at"
      ],
      "type": "object"
    }
  },
  "required": [
    "webhook",
    "secret"
  ],
  "type": "object"
}
```

---

# Update a webhook

> Update a webhook. Changing its URL resets verification and approval and sends a new ping.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints/put-webhooks-webhook_id

## PUT /v1/webhooks/{webhook_id}

Update a webhook. Changing its URL resets verification and approval and sends a new ping.

Required permissions: write:webhooks.
API key: Supported.
CLI user token: Supported.
Sandbox token: Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.

### Request

```text
{
  "description": str,
  "events": [
    "session.create"
  ],
  "url": str
}
```

### Response

```text
{
  "webhook": {
    "activated_at": str,
    "created_at": str,
    "description": str,
    "events": [
      "session.create"
    ],
    "id": str,
    "last_delivery": {
      "attempt_count": int,
      "completed_at": str,
      "created_at": str,
      "event_id": str,
      "event_type": str,
      "id": str,
      "last_error": str,
      "last_http_status": int,
      "next_attempt_at": str,
      "status": str,
      "url": str,
      "webhook_id": str
    },
    "state": str,
    "updated_at": str,
    "url": str,
    "verified_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.WebhookConfigRequest.model_validate(
    {
      "url": "https://example.com/ellipsis",
      "events": [
        "session.create"
      ]
    }
)

result = client.webhooks.update(
    "webhook_example",
    request.events,
    request.url,
)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.webhooks.update>[1] = {
  "url": "https://example.com/ellipsis",
  "events": [
    "session.create"
  ]
};

const result = await client.webhooks.update("webhook_example", request);
console.log(result);
```

### cURL

```bash
curl -X PUT "https://api.ellipsis.dev/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/ellipsis",
  "events": [
    "session.create"
  ]
}'
```

### Request schema

```json
{
  "additionalProperties": false,
  "examples": [
    {
      "events": [
        "session.create"
      ],
      "url": "https://example.com/hooks"
    }
  ],
  "properties": {
    "description": {
      "anyOf": [
        {
          "maxLength": 500,
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "events": {
      "examples": [
        [
          "session.create"
        ]
      ],
      "items": {
        "const": "session.create",
        "type": "string"
      },
      "maxItems": 1,
      "minItems": 1,
      "type": "array"
    },
    "url": {
      "examples": [
        "https://example.com/hooks"
      ],
      "maxLength": 2048,
      "type": "string"
    }
  },
  "required": [
    "url",
    "events"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "webhook": {
      "properties": {
        "activated_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "events": {
          "items": {
            "const": "session.create",
            "type": "string"
          },
          "type": "array"
        },
        "id": {
          "type": "string"
        },
        "last_delivery": {
          "anyOf": [
            {
              "properties": {
                "attempt_count": {
                  "type": "integer"
                },
                "completed_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "event_id": {
                  "type": "string"
                },
                "event_type": {
                  "enum": [
                    "session.create",
                    "webhook.ping"
                  ],
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "last_error": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "last_http_status": {
                  "anyOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "next_attempt_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "enum": [
                    "pending",
                    "delivering",
                    "retrying",
                    "succeeded",
                    "failed",
                    "cancelled"
                  ],
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "webhook_id": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "webhook_id",
                "event_id",
                "event_type",
                "url",
                "status",
                "created_at",
                "completed_at",
                "attempt_count",
                "next_attempt_at",
                "last_http_status",
                "last_error"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "state": {
          "enum": [
            "unverified",
            "pending",
            "active"
          ],
          "type": "string"
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "verified_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "url",
        "events",
        "description",
        "state",
        "created_at",
        "updated_at",
        "verified_at",
        "activated_at"
      ],
      "type": "object"
    }
  },
  "required": [
    "webhook"
  ],
  "type": "object"
}
```

---

# Search sessions

> Search session history. Supply q and filter by service, handler, or source.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-search

## GET /v1/sessions/search

Search session history. Supply q and filter by service, handler, or source.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "results": [
    {
      "matched": [
        str
      ],
      "recap_snippet": str,
      "record_hit_count": int,
      "record_hits": [
        {
          "created_at": str,
          "id": str,
          "record_type": str,
          "snippet": str,
          "stream_seq": int
        }
      ],
      "session": {
        "agent": {
          "config": {
            "ellipsis": {
              "description": str,
              "enabled": bool,
              "kind": "agent",
              "metadata": {
                "annotations": {
                  "[str]": str
                },
                "labels": [
                  str
                ]
              },
              "name": str,
              "version": str
            },
            "input": {
              "json_schema": {
                "[str]": any
              },
              "message": str
            },
            "session": {
              "budget": {
                "day": float,
                "month": float,
                "session": float,
                "week": float
              },
              "claude_code": {
                "effort": str,
                "fallback_model": str,
                "max_turns": int,
                "model": str,
                "prompt": str,
                "settings": {
                  "path": str,
                  "repository": {
                    "name": str,
                    "owner": str,
                    "ref": str
                  }
                }
              },
              "codex": {
                "effort": str,
                "model": str,
                "prompt": str
              },
              "environment": { # str
                "compute": {
                  "cpu": int,
                  "memory": { # str | null
                    "gb": int,
                    "mb": int
                  },
                  "timeout": { # str | null
                    "hours": int,
                    "minutes": int,
                    "seconds": int
                  }
                },
                "hooks": {
                  "after_checkout": { # str | null
                    "run": str
                  },
                  "before_start": { # str | null
                    "run": str
                  },
                  "build_base": { # str | null
                    "inputs": [
                      str
                    ],
                    "run": str
                  },
                  "post_clone": str,
                  "post_start": str
                },
                "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
                # McpRemoteServer]
                  {
                    "args": [
                      str
                    ],
                    "command": str,
                    "env": {
                      "[str]": str
                    },
                    "name": str
                  }
                ],
                "repositories": [
                  {
                    "name": str,
                    "owner": str,
                    "ref": str
                  }
                ],
                "variables": [
                  {
                    "name": str,
                    "value": str
                  }
                ]
              },
              "output": {
                "json_schema": {
                  "[str]": any
                }
              },
              "permissions": {
                "ellipsis": { # bool | str
                  "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                    {
                      "level": str,
                      "match": [
                        str
                      ]
                    }
                  ]
                },
                "github": {
                  "permissions": { # "read_only" | null
                    "[str]": str
                  },
                  "repositories": [
                    str
                  ]
                }
              },
              "skills": [
                {
                  "path": str,
                  "repository": {
                    "name": str,
                    "owner": str,
                    "ref": str
                  }
                }
              ]
            },
            "trigger": { # null | ReactTrigger | CronTrigger
              "issue": {
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "labels": [
                  str
                ],
                "on": [
                  str
                ],
                "repositories": { # list[str]
                  "exclude": [
                    str
                  ],
                  "include": [
                    str
                  ]
                }
              },
              "linear_issue": {
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "on": [
                  str
                ]
              },
              "pull_request": {
                "base": [
                  str
                ],
                "draft": bool,
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "head": [
                  str
                ],
                "labels": [
                  str
                ],
                "on": [
                  str
                ],
                "paths": [
                  str
                ],
                "repositories": { # list[str]
                  "exclude": [
                    str
                  ],
                  "include": [
                    str
                  ]
                }
              },
              "push": {
                "branch": [
                  str
                ],
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "paths": [
                  str
                ],
                "repositories": { # list[str]
                  "exclude": [
                    str
                  ],
                  "include": [
                    str
                  ]
                }
              },
              "sentry": {
                "on": [
                  str
                ],
                "projects": [
                  str
                ]
              },
              "slack_channel": {},
              "type": "react"
            }
          },
          "id": str
        },
        "attribution": {
          "id": str,
          "type": str,
          "user": {
            "avatar_url": str,
            "id": int,
            "login": str,
            "type": str
          }
        },
        "budget": float,
        "claude_code": {
          "effort": str,
          "fallback_model": str,
          "max_turns": int,
          "model": str,
          "prompt": str,
          "settings": {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        },
        "codex": {
          "effort": str,
          "model": str,
          "prompt": str
        },
        "cost": {
          "cpu": int,
          "fee": int,
          "llm": int,
          "memory": int,
          "total": int
        },
        "environment": {
          "compute": {
            "cpu": int,
            "memory": { # str | null
              "gb": int,
              "mb": int
            },
            "timeout": { # str | null
              "hours": int,
              "minutes": int,
              "seconds": int
            }
          },
          "hooks": {
            "after_checkout": { # str | null
              "run": str
            },
            "before_start": { # str | null
              "run": str
            },
            "build_base": { # str | null
              "inputs": [
                str
              ],
              "run": str
            },
            "post_clone": str,
            "post_start": str
          },
          "id": str,
          "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
          # McpRemoteServer]
            {
              "args": [
                str
              ],
              "command": str,
              "env": {
                "[str]": str
              },
              "name": str
            }
          ],
          "repositories": [
            {
              "name": str,
              "owner": str,
              "ref": str
            }
          ],
          "source": str,
          "variables": [
            {
              "name": str,
              "value": str
            }
          ]
        },
        "event": { # null | GithubPullRequestEvent | GithubIssueEvent |
        # GithubPushEvent | LinearIssueEvent | SlackMessageEvent |
        # SlackChannelCreatedEvent | SentryAlertEvent
          "action": str, # "review_commented"
          "actor": {
            "avatar_url": str,
            "is_bot": bool,
            "name": str
          },
          "branch": str,
          "number": int,
          "repository": str,
          "title": str,
          "type": "github.pull_request",
          "url": str
        },
        "git": {
          "repos": [
            {
              "commits": [
                {
                  "committed_at": str,
                  "pushed": bool,
                  "sha": str,
                  "subject": str
                }
              ],
              "commits_total": int,
              "full_name": str,
              "local_commit": str,
              "local_uncommitted_files": [
                {
                  "additions": int,
                  "deletions": int,
                  "path": str,
                  "status": str
                }
              ],
              "prs": [
                {
                  "gh_pr_id": int,
                  "number": int,
                  "title": str,
                  "url": str
                }
              ],
              "remote_branch": str,
              "remote_commit": str
            }
          ]
        },
        "handler": {
          "agent_name": str,
          "id": str,
          "service": str,
          "sha": str
        },
        "id": str,
        "lifecycle": {
          "archived": {
            "at": str,
            "by": {
              "avatar_url": str,
              "id": int,
              "login": str,
              "type": str
            }
          },
          "conversation": str,
          "detail": str,
          "interactive": bool,
          "last_execution_result": {
            "completion_reason": str,
            "detail": str
          },
          "prompting": {
            "blocked_reason": str,
            "detail": str,
            "enabled": bool,
            "surface_name": str
          },
          "status": str,
          "stopped": {
            "at": str,
            "by": {
              "avatar_url": str,
              "id": int,
              "login": str,
              "type": str
            }
          },
          "timestamps": {
            "created_at": str,
            "last_activity_at": str,
            "last_message_at": str,
            "updated_at": str
          }
        },
        "metadata": {
          "[str]": str
        },
        "output": {
          "json_schema": {
            "[str]": any
          }
        },
        "parent": {
          "session_id": str
        },
        "permissions": {
          "ellipsis": { # bool | str
            "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
              {
                "level": str,
                "match": [
                  str
                ]
              }
            ]
          },
          "github": {
            "permissions": { # "read_only" | null
              "[str]": str
            },
            "repositories": [
              str
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ],
        "source": str,
        "summary": {
          "created_at": str,
          "description": str
        },
        "tokens": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "model": str,
          "output": int,
          "total": int
        }
      }
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.sessions.search(q="validation")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.sessions.search({ q: "validation" });
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/search?q=..." \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "results": {
      "items": {
        "properties": {
          "matched": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "recap_snippet": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "record_hit_count": {
            "type": "integer"
          },
          "record_hits": {
            "items": {
              "properties": {
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "record_type": {
                  "type": "string"
                },
                "snippet": {
                  "type": "string"
                },
                "stream_seq": {
                  "type": "integer"
                }
              },
              "required": [
                "id",
                "stream_seq",
                "record_type",
                "created_at",
                "snippet"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "session": {
            "additionalProperties": false,
            "allOf": [
              {
                "oneOf": [
                  {
                    "properties": {
                      "claude_code": {
                        "type": "object"
                      },
                      "codex": {
                        "type": "null"
                      }
                    },
                    "required": [
                      "claude_code",
                      "codex"
                    ]
                  },
                  {
                    "properties": {
                      "claude_code": {
                        "type": "null"
                      },
                      "codex": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "claude_code",
                      "codex"
                    ]
                  }
                ]
              }
            ],
            "properties": {
              "agent": {
                "anyOf": [
                  {
                    "properties": {
                      "config": {
                        "type": "object"
                      },
                      "id": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "config",
                      "id"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "attribution": {
                "properties": {
                  "id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "type": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "user": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "type",
                  "user"
                ],
                "type": "object"
              },
              "budget": {
                "default": 0,
                "type": "number"
              },
              "claude_code": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "effort": {
                        "type": "object"
                      },
                      "fallback_model": {
                        "type": "object"
                      },
                      "max_turns": {
                        "type": "object"
                      },
                      "model": {
                        "type": "object"
                      },
                      "prompt": {
                        "type": "object"
                      },
                      "settings": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "effort",
                      "fallback_model",
                      "max_turns",
                      "model",
                      "prompt",
                      "settings"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "codex": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "effort": {
                        "type": "object"
                      },
                      "model": {
                        "type": "string"
                      },
                      "prompt": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "effort",
                      "model",
                      "prompt"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "cost": {
                "properties": {
                  "cpu": {
                    "default": 0,
                    "type": "integer"
                  },
                  "fee": {
                    "default": 0,
                    "type": "integer"
                  },
                  "llm": {
                    "default": 0,
                    "type": "integer"
                  },
                  "memory": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cpu",
                  "fee",
                  "llm",
                  "memory",
                  "total"
                ],
                "type": "object"
              },
              "environment": {
                "additionalProperties": false,
                "properties": {
                  "compute": {
                    "additionalProperties": false,
                    "properties": {
                      "cpu": {
                        "type": "object"
                      },
                      "memory": {
                        "type": "object"
                      },
                      "timeout": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "cpu",
                      "memory",
                      "timeout"
                    ],
                    "type": "object"
                  },
                  "hooks": {
                    "additionalProperties": false,
                    "properties": {
                      "after_checkout": {
                        "type": "object"
                      },
                      "before_start": {
                        "type": "object"
                      },
                      "build_base": {
                        "type": "object"
                      },
                      "post_clone": {
                        "type": "object"
                      },
                      "post_start": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "after_checkout",
                      "before_start",
                      "build_base",
                      "post_clone",
                      "post_start"
                    ],
                    "type": "object"
                  },
                  "id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "mcp_servers": {
                    "default": [],
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "repositories": {
                    "default": [],
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "source": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "variables": {
                    "default": [],
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "compute",
                  "hooks",
                  "id",
                  "mcp_servers",
                  "repositories",
                  "source",
                  "variables"
                ],
                "type": "object"
              },
              "event": {
                "anyOf": [
                  {
                    "oneOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "object"
                      }
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "git": {
                "anyOf": [
                  {
                    "properties": {
                      "repos": {
                        "type": "array"
                      }
                    },
                    "required": [
                      "repos"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "handler": {
                "anyOf": [
                  {
                    "properties": {
                      "agent_name": {
                        "type": "string"
                      },
                      "id": {
                        "type": "string"
                      },
                      "service": {
                        "type": "string"
                      },
                      "sha": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "agent_name",
                      "id",
                      "service",
                      "sha"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "type": "string"
              },
              "lifecycle": {
                "properties": {
                  "archived": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "conversation": {
                    "enum": [
                      "open",
                      "closed"
                    ],
                    "type": "string"
                  },
                  "detail": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "interactive": {
                    "type": "boolean"
                  },
                  "last_execution_result": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "prompting": {
                    "properties": {
                      "blocked_reason": {
                        "type": "object"
                      },
                      "detail": {
                        "type": "object"
                      },
                      "enabled": {
                        "type": "boolean"
                      },
                      "surface_name": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "blocked_reason",
                      "detail",
                      "enabled",
                      "surface_name"
                    ],
                    "type": "object"
                  },
                  "status": {
                    "enum": [
                      "scheduled",
                      "starting",
                      "working",
                      "waiting",
                      "retrying",
                      "idle",
                      "closed",
                      "failed",
                      "stopped",
                      "cancelled"
                    ],
                    "type": "string"
                  },
                  "stopped": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "timestamps": {
                    "properties": {
                      "created_at": {
                        "type": "string"
                      },
                      "last_activity_at": {
                        "type": "object"
                      },
                      "last_message_at": {
                        "type": "object"
                      },
                      "updated_at": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "created_at",
                      "last_activity_at",
                      "last_message_at",
                      "updated_at"
                    ],
                    "type": "object"
                  }
                },
                "required": [
                  "archived",
                  "conversation",
                  "detail",
                  "interactive",
                  "last_execution_result",
                  "prompting",
                  "status",
                  "stopped",
                  "timestamps"
                ],
                "type": "object"
              },
              "metadata": {
                "items": {
                  "type": "string"
                },
                "default": {},
                "type": "object"
              },
              "output": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "json_schema": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "json_schema"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "parent": {
                "anyOf": [
                  {
                    "properties": {
                      "session_id": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "session_id"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "permissions": {
                "additionalProperties": false,
                "properties": {
                  "ellipsis": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "object"
                      }
                    ],
                    "default": true
                  },
                  "github": {
                    "additionalProperties": false,
                    "properties": {
                      "permissions": {
                        "type": "object"
                      },
                      "repositories": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "permissions",
                      "repositories"
                    ],
                    "type": "object"
                  }
                },
                "required": [
                  "ellipsis",
                  "github"
                ],
                "type": "object"
              },
              "skills": {
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "path": {
                      "type": "string"
                    },
                    "repository": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "path",
                    "repository"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "source": {
                "enum": [
                  "react",
                  "web",
                  "api",
                  "cli",
                  "mention",
                  "cron"
                ],
                "type": "string"
              },
              "summary": {
                "anyOf": [
                  {
                    "properties": {
                      "created_at": {
                        "type": "object"
                      },
                      "description": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "created_at",
                      "description"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tokens": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "default": "",
                    "type": "string"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "model",
                  "output",
                  "total"
                ],
                "type": "object"
              }
            },
            "required": [
              "agent",
              "attribution",
              "budget",
              "claude_code",
              "codex",
              "cost",
              "environment",
              "event",
              "git",
              "handler",
              "id",
              "lifecycle",
              "metadata",
              "output",
              "parent",
              "permissions",
              "skills",
              "source",
              "summary",
              "tokens"
            ],
            "type": "object"
          }
        },
        "required": [
          "session",
          "matched",
          "recap_snippet",
          "record_hits",
          "record_hit_count"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "type": "object"
}
```

---

# Get changes

> Read the changes produced by a session.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-diff

## GET /v1/sessions/{session_id}/diff

Read the changes produced by a session.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration. Only the token's own session.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "files": [
    {
      "full_name": str,
      "patch": str,
      "path": str
    }
  ],
  "omitted_paths": [
    str
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.sessions.diff("session_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.sessions.diff("session_example");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/diff" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "files": {
      "items": {
        "properties": {
          "full_name": {
            "type": "string"
          },
          "patch": {
            "type": "string"
          },
          "path": {
            "type": "string"
          }
        },
        "required": [
          "full_name",
          "path",
          "patch"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "omitted_paths": {
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "files",
    "omitted_paths"
  ],
  "type": "object"
}
```

---

# Download a transcript

> Download the session transcript.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-download

## GET /v1/sessions/{session_id}/download

Download the session transcript.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "archived_through_feed_seq": int,
  "earliest_feed_seq": int,
  "format": str,
  "has_more": bool,
  "latest_feed_seq": int,
  "segments": [
    {
      "bytes": int,
      "download_url": str,
      "end_feed_seq": int,
      "expires_in": int,
      "record_count": int,
      "start_feed_seq": int
    }
  ],
  "session_id": str
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.sessions.download("session_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.sessions.download("session_example");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/download" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "archived_through_feed_seq": {
      "type": "integer"
    },
    "earliest_feed_seq": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "format": {
      "default": "ellipsis_session_log@1",
      "type": "string"
    },
    "has_more": {
      "type": "boolean"
    },
    "latest_feed_seq": {
      "type": "integer"
    },
    "segments": {
      "items": {
        "properties": {
          "bytes": {
            "type": "integer"
          },
          "download_url": {
            "type": "string"
          },
          "end_feed_seq": {
            "type": "integer"
          },
          "expires_in": {
            "type": "integer"
          },
          "record_count": {
            "type": "integer"
          },
          "start_feed_seq": {
            "type": "integer"
          }
        },
        "required": [
          "start_feed_seq",
          "end_feed_seq",
          "record_count",
          "bytes",
          "download_url",
          "expires_in"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "session_id": {
      "type": "string"
    }
  },
  "required": [
    "session_id",
    "earliest_feed_seq",
    "archived_through_feed_seq",
    "latest_feed_seq",
    "has_more",
    "segments"
  ],
  "type": "object"
}
```

---

# List executions

> Read execution attempts in order, including resolved settings and result summaries.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-executions

## GET /v1/sessions/{session_id}/executions

Read execution attempts in order, including resolved settings and result summaries.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "executions": [
    {
      "attempt_index": int,
      "created_at": str,
      "execution_index": int,
      "exit_status": str,
      "harness": str,
      "id": str,
      "instructions": str,
      "model": str,
      "query": str,
      "result": {
        "exit_code": int,
        "harness_session_id": str,
        "is_error": bool,
        "reason": str,
        "structured_output": {
          "[str]": any
        },
        "text": str
      },
      "resumed": bool,
      "session_id": str,
      "status": str,
      "wake_index": int
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.sessions.executions("session_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.sessions.executions("session_example");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/executions" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "executions": {
      "items": {
        "properties": {
          "attempt_index": {
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "execution_index": {
            "type": "integer"
          },
          "exit_status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "harness": {
            "anyOf": [
              {
                "enum": [
                  "claude_code",
                  "codex"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string"
          },
          "instructions": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "query": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "anyOf": [
              {
                "properties": {
                  "exit_code": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "harness_session_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "reason": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "structured_output": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "text": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "resumed": {
            "type": "boolean"
          },
          "session_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "running",
              "failed",
              "done"
            ],
            "type": "string"
          },
          "wake_index": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "session_id",
          "created_at",
          "execution_index",
          "wake_index",
          "attempt_index",
          "resumed",
          "status"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "executions"
  ],
  "type": "object"
}
```

---

# Get commits and pull requests

> Read commits and pull requests associated with a session.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-git

## GET /v1/sessions/{session_id}/git

Read commits and pull requests associated with a session.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "repos": [
    {
      "commits": [
        {
          "committed_at": str,
          "pushed": bool,
          "sha": str,
          "subject": str
        }
      ],
      "commits_total": int,
      "full_name": str,
      "prs": [
        {
          "number": int,
          "pull_request": {
            "additions": int,
            "base": {
              "ref": str,
              "sha": str
            },
            "changed_files": int,
            "commits": int,
            "created_at": str,
            "deletions": int,
            "draft": bool,
            "head": {
              "ref": str,
              "sha": str
            },
            "html_url": str,
            "id": int,
            "merged_at": str,
            "number": int,
            "state": str,
            "title": str,
            "updated_at": str
          },
          "reviews": [
            {
              "body": str,
              "html_url": str,
              "id": int,
              "state": str,
              "submitted_at": str,
              "user": {
                "avatar_url": str,
                "id": int,
                "login": str,
                "type": str
              }
            }
          ],
          "title": str,
          "url": str
        }
      ]
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.sessions.git("session_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.sessions.git("session_example");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/git" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "repos": {
      "items": {
        "properties": {
          "commits": {
            "items": {
              "properties": {
                "committed_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "pushed": {
                  "type": "boolean"
                },
                "sha": {
                  "type": "string"
                },
                "subject": {
                  "type": "string"
                }
              },
              "required": [
                "committed_at",
                "pushed",
                "sha",
                "subject"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "commits_total": {
            "type": "integer"
          },
          "full_name": {
            "type": "string"
          },
          "prs": {
            "items": {
              "properties": {
                "number": {
                  "type": "integer"
                },
                "pull_request": {
                  "anyOf": [
                    {
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "reviews": {
                  "items": {
                    "type": "object"
                  },
                  "type": "array"
                },
                "title": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "number",
                "url",
                "title",
                "pull_request",
                "reviews"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "full_name",
          "commits",
          "commits_total",
          "prs"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "repos"
  ],
  "type": "object"
}
```

---

# Get structured output

> Read the validated JSON result of a session with an output schema.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-output

## GET /v1/sessions/{session_id}/output

Read the validated JSON result of a session with an output schema.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "[str]": any
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.sessions.output("session_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.sessions.output("session_example");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/output" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "type": "object"
}
```

---

# List records

> Read complete platform and native harness records. Partial text deltas are live-only.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-records

## GET /v1/sessions/{session_id}/records

Read complete platform and native harness records. Partial text deltas are live-only.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "earliest_feed_seq": int,
  "has_more": bool,
  "messages": [
    {
      "author": str,
      "body": str,
      "created_at": str,
      "delivered_at": str,
      "delivered_turn_id": str,
      "feed_seq": int,
      "id": str,
      "images": [
        {
          "index": int,
          "media_type": str,
          "size_bytes": int
        }
      ],
      "sender_attribution_id": str,
      "sender_attribution_type": str,
      "session_id": str,
      "status": str
    }
  ],
  "next_cursor": str,
  "records": [ # list[ClaudeSessionRecord | ClaudeNativeSessionRecord |
  # CodexSessionRecord | CodexAppServerSessionRecord | SessionScheduledRecord |
  # SessionStartingRecord | SessionRetryingRecord | SessionResumedRecord |
  # SessionIdleRecord | SessionClosedRecord | SessionCancelledRecord |
  # MessageReceivedRecord | MessageDeliveredRecord | MessageRequeuedRecord |
  # TurnStartedRecord | TurnCompletedRecord | TurnFailedRecord |
  # SandboxStartingRecord | SandboxPhaseRecord | SandboxOutputRecord |
  # SandboxReadyRecord | OutboxCollectedRecord | UnknownSessionRecord]
    {
      "cost": int,
      "created_at": str,
      "duration": int,
      "feed_seq": int,
      "id": str,
      "kind": "codex_app_server",
      "model": str,
      "payload": { # CodexThreadStarted | CodexTurnStarted | CodexTurnCompleted
      # | CodexItemStarted | CodexItemCompleted | CodexTokenUsageUpdated |
      # CodexAppServerError
        "method": "thread/started",
        "params": {
          "thread": {
            "cliVersion": str,
            "cwd": str,
            "id": str,
            "modelProvider": str,
            "turns": [
              {
                "error": {
                  "additionalDetails": str,
                  "codexErrorInfo": { # str | null
                    "[str]": any
                  },
                  "message": str,
                  "[str]": any
                },
                "id": str,
                "items": [ # list[CodexUserMessage | CodexAgentMessage |
                # CodexReasoning | CodexPlan | CodexCommandExecution |
                # CodexFileChange | CodexWebSearch | CodexMcpToolCall |
                # CodexContextCompaction]
                  {
                    "clientId": str,
                    "content": [ # list[CodexTextInput | CodexLocalImageInput]
                      {
                        "text": str,
                        "text_elements": [
                          {
                            "[str]": any
                          }
                        ],
                        "type": "text",
                        "[str]": any
                      }
                    ],
                    "id": str,
                    "type": "userMessage",
                    "[str]": any
                  }
                ],
                "status": str,
                "[str]": any
              }
            ],
            "[str]": any
          },
          "[str]": any
        },
        "[str]": any
      },
      "record_format": "codex_app_server@1",
      "record_type": str,
      "sandbox_id": str,
      "session_execution_id": str,
      "session_id": str,
      "session_message_id": str,
      "source": "codex",
      "stream_seq": int,
      "tokens_info": {
        "cache_creation_input_tokens": int,
        "cache_read_input_tokens": int,
        "cost_usd": float,
        "input_tokens": int,
        "num_turns": int,
        "output_tokens": int
      },
      "tools": [
        str
      ],
      "turn_id": str
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

for item in client.sessions.records("session_example"):
    print(item)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

for await (const item of await client.sessions.records("session_example")) {
  console.log(item);
}
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/records" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "earliest_feed_seq": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "has_more": {
      "default": false,
      "type": "boolean"
    },
    "messages": {
      "default": [],
      "items": {
        "properties": {
          "author": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "body": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "delivered_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "delivered_turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "feed_seq": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string"
          },
          "images": {
            "items": {
              "properties": {
                "index": {
                  "type": "integer"
                },
                "media_type": {
                  "type": "string"
                },
                "size_bytes": {
                  "type": "integer"
                }
              },
              "required": [
                "index",
                "media_type",
                "size_bytes"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "sender_attribution_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "sender_attribution_type": {
            "anyOf": [
              {
                "enum": [
                  "github_user",
                  "linear_user",
                  "slack_user",
                  "api_key"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "session_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "delivered"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "session_id",
          "status",
          "body",
          "created_at"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "records": {
      "items": {
        "anyOf": [
          {
            "properties": {
              "cost": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "duration": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "feed_seq": {
                "type": "integer"
              },
              "id": {
                "type": "string"
              },
              "kind": {
                "const": "claude_sdk",
                "default": "claude_sdk",
                "type": "string"
              },
              "model": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "payload": {
                "oneOf": [
                  {
                    "additionalProperties": true,
                    "properties": {
                      "cache_creation": {
                        "type": "object"
                      },
                      "content": {
                        "type": "array"
                      },
                      "error": {
                        "type": "object"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "message_id": {
                        "type": "object"
                      },
                      "model": {
                        "type": "string"
                      },
                      "parent_tool_use_id": {
                        "type": "object"
                      },
                      "session_id": {
                        "type": "object"
                      },
                      "stop_reason": {
                        "type": "object"
                      },
                      "usage": {
                        "type": "object"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "kind",
                      "model"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "content": {
                        "type": "object"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "parent_tool_use_id": {
                        "type": "object"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "content",
                      "kind"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "data": {
                        "type": "object"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "session_id": {
                        "type": "object"
                      },
                      "subtype": {
                        "type": "string"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "kind",
                      "subtype"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "api_error_status": {
                        "type": "object"
                      },
                      "cost_usd": {
                        "type": "object"
                      },
                      "duration_api_ms": {
                        "type": "integer"
                      },
                      "duration_ms": {
                        "type": "integer"
                      },
                      "errors": {
                        "type": "object"
                      },
                      "is_error": {
                        "type": "boolean"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "model_usage": {
                        "type": "object"
                      },
                      "num_turns": {
                        "type": "integer"
                      },
                      "result": {
                        "type": "object"
                      },
                      "session_id": {
                        "type": "object"
                      },
                      "stop_reason": {
                        "type": "object"
                      },
                      "structured_output": {
                        "type": "object"
                      },
                      "subtype": {
                        "type": "string"
                      },
                      "usage": {
                        "type": "object"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "duration_api_ms",
                      "duration_ms",
                      "is_error",
                      "kind",
                      "num_turns",
                      "subtype"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "kind": {
                        "type": "string"
                      },
                      "rate_limit_type": {
                        "type": "object"
                      },
                      "resets_at": {
                        "type": "object"
                      },
                      "session_id": {
                        "type": "object"
                      },
                      "status": {
                        "type": "string"
                      },
                      "utilization": {
                        "type": "object"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "kind",
                      "status"
                    ],
                    "type": "object"
                  }
                ]
              },
              "record_format": {
                "const": "claude_sdk@1",
                "default": "claude_sdk@1",
                "type": "string"
              },
              "record_type": {
                "type": "string"
              },
              "sandbox_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_execution_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "const": "claude_code",
                "default": "claude_code",
                "type": "string"
              },
              "stream_seq": {
                "type": "integer"
              },
              "tokens_info": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "cache_creation_input_tokens": {
                        "type": "integer"
                      },
                      "cache_read_input_tokens": {
                        "type": "integer"
                      },
                      "cost_usd": {
                        "type": "number"
                      },
                      "input_tokens": {
                        "type": "integer"
                      },
                      "num_turns": {
                        "type": "integer"
                      },
                      "output_tokens": {
                        "type": "integer"
                      }
                    },
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tools": {
                "anyOf": [
                  {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "turn_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "id",
              "session_id",
              "session_execution_id",
              "turn_id",
              "session_message_id",
              "sandbox_id",
              "feed_seq",
              "stream_seq",
              "source",
              "record_type",
              "record_format",
              "payload",
              "tools",
              "tokens_info",
              "cost",
              "duration",
              "model",
              "created_at",
              "kind"
            ],
            "type": "object",
            "x-ellipsis-preserve-payload": true
          },
          {
            "properties": {
              "cost": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "duration": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "feed_seq": {
                "type": "integer"
              },
              "id": {
                "type": "string"
              },
              "kind": {
                "const": "claude_code",
                "default": "claude_code",
                "type": "string"
              },
              "model": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "payload": {
                "oneOf": [
                  {
                    "additionalProperties": true,
                    "properties": {
                      "error": {
                        "type": "object"
                      },
                      "message": {
                        "type": "object"
                      },
                      "parent_tool_use_id": {
                        "type": "object"
                      },
                      "session_id": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "message",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "isReplay": {
                        "type": "object"
                      },
                      "message": {
                        "type": "object"
                      },
                      "parent_tool_use_id": {
                        "type": "object"
                      },
                      "session_id": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "message",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "session_id": {
                        "type": "object"
                      },
                      "subtype": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "subtype",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "duration_api_ms": {
                        "type": "integer"
                      },
                      "duration_ms": {
                        "type": "integer"
                      },
                      "errors": {
                        "type": "object"
                      },
                      "is_error": {
                        "type": "boolean"
                      },
                      "modelUsage": {
                        "type": "object"
                      },
                      "num_turns": {
                        "type": "integer"
                      },
                      "result": {
                        "type": "object"
                      },
                      "session_id": {
                        "type": "object"
                      },
                      "stop_reason": {
                        "type": "object"
                      },
                      "structured_output": {
                        "type": "object"
                      },
                      "subtype": {
                        "type": "string"
                      },
                      "total_cost_usd": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      },
                      "usage": {
                        "type": "object"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "duration_api_ms",
                      "duration_ms",
                      "is_error",
                      "num_turns",
                      "subtype",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "rate_limit_info": {
                        "type": "object"
                      },
                      "session_id": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "rate_limit_info",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "new_conversation_id": {
                        "type": "string"
                      },
                      "session_id": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      },
                      "uuid": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "new_conversation_id",
                      "type"
                    ],
                    "type": "object"
                  }
                ]
              },
              "record_format": {
                "const": "claude_jsonl@1",
                "default": "claude_jsonl@1",
                "type": "string"
              },
              "record_type": {
                "type": "string"
              },
              "sandbox_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_execution_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "const": "claude_code",
                "default": "claude_code",
                "type": "string"
              },
              "stream_seq": {
                "type": "integer"
              },
              "tokens_info": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "cache_creation_input_tokens": {
                        "type": "integer"
                      },
                      "cache_read_input_tokens": {
                        "type": "integer"
                      },
                      "cost_usd": {
                        "type": "number"
                      },
                      "input_tokens": {
                        "type": "integer"
                      },
                      "num_turns": {
                        "type": "integer"
                      },
                      "output_tokens": {
                        "type": "integer"
                      }
                    },
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tools": {
                "anyOf": [
                  {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "turn_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "id",
              "session_id",
              "session_execution_id",
              "turn_id",
              "session_message_id",
              "sandbox_id",
              "feed_seq",
              "stream_seq",
              "source",
              "record_type",
              "record_format",
              "payload",
              "tools",
              "tokens_info",
              "cost",
              "duration",
              "model",
              "created_at",
              "kind"
            ],
            "type": "object",
            "x-ellipsis-preserve-payload": true
          },
          {
            "properties": {
              "cost": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "duration": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "feed_seq": {
                "type": "integer"
              },
              "id": {
                "type": "string"
              },
              "kind": {
                "const": "codex",
                "default": "codex",
                "type": "string"
              },
              "model": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "payload": {
                "oneOf": [
                  {
                    "additionalProperties": true,
                    "properties": {
                      "thread_id": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "type": {
                        "type": "string"
                      },
                      "usage": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "error": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "message": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "item": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "item",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "item": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "item",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "item": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "item",
                      "type"
                    ],
                    "type": "object"
                  }
                ]
              },
              "record_format": {
                "const": "codex_jsonl@1",
                "default": "codex_jsonl@1",
                "type": "string"
              },
              "record_type": {
                "type": "string"
              },
              "sandbox_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_execution_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "const": "codex",
                "default": "codex",
                "type": "string"
              },
              "stream_seq": {
                "type": "integer"
              },
              "tokens_info": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "cache_creation_input_tokens": {
                        "type": "integer"
                      },
                      "cache_read_input_tokens": {
                        "type": "integer"
                      },
                      "cost_usd": {
                        "type": "number"
                      },
                      "input_tokens": {
                        "type": "integer"
                      },
                      "num_turns": {
                        "type": "integer"
                      },
                      "output_tokens": {
                        "type": "integer"
                      }
                    },
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tools": {
                "anyOf": [
                  {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "turn_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "id",
              "session_id",
              "session_execution_id",
              "turn_id",
              "session_message_id",
              "sandbox_id",
              "feed_seq",
              "stream_seq",
              "source",
              "record_type",
              "record_format",
              "payload",
              "tools",
              "tokens_info",
              "cost",
              "duration",
              "model",
              "created_at",
              "kind"
            ],
            "type": "object",
            "x-ellipsis-preserve-payload": true
          },
          {
            "properties": {
              "cost": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "duration": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "feed_seq": {
                "type": "integer"
              },
              "id": {
                "type": "string"
              },
              "kind": {
                "const": "codex_app_server",
                "default": "codex_app_server",
                "type": "string"
              },
              "model": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "payload": {
                "oneOf": [
                  {
                    "additionalProperties": true,
                    "properties": {
                      "method": {
                        "type": "string"
                      },
                      "params": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "method",
                      "params"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "method": {
                        "type": "string"
                      },
                      "params": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "method",
                      "params"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "method": {
                        "type": "string"
                      },
                      "params": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "method",
                      "params"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "method": {
                        "type": "string"
                      },
                      "params": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "method",
                      "params"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "method": {
                        "type": "string"
                      },
                      "params": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "method",
                      "params"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "method": {
                        "type": "string"
                      },
                      "params": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "method",
                      "params"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": true,
                    "properties": {
                      "method": {
                        "type": "string"
                      },
                      "params": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "method",
                      "params"
                    ],
                    "type": "object"
                  }
                ]
              },
              "record_format": {
                "const": "codex_app_server@1",
                "default": "codex_app_server@1",
                "type": "string"
              },
              "record_type": {
                "type": "string"
              },
              "sandbox_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_execution_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "const": "codex",
                "default": "codex",
                "type": "string"
              },
              "stream_seq": {
                "type": "integer"
              },
              "tokens_info": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "cache_creation_input_tokens": {
                        "type": "integer"
                      },
                      "cache_read_input_tokens": {
                        "type": "integer"
                      },
                      "cost_usd": {
                        "type": "number"
                      },
                      "input_tokens": {
                        "type": "integer"
                      },
                      "num_turns": {
                        "type": "integer"
                      },
                      "output_tokens": {
                        "type": "integer"
                      }
                    },
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tools": {
                "anyOf": [
                  {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "turn_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "id",
              "session_id",
              "session_execution_id",
              "turn_id",
              "session_message_id",
              "sandbox_id",
              "feed_seq",
              "stream_seq",
              "source",
              "record_type",
              "record_format",
              "payload",
              "tools",
              "tokens_info",
              "cost",
              "duration",
              "model",
              "created_at",
              "kind"
            ],
            "type": "object",
            "x-ellipsis-preserve-payload": true
          },
          {
            "oneOf": [
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "config_commit_sha": {
                        "type": "object"
                      },
                      "config_name": {
                        "type": "object"
                      },
                      "source": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "source"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "session_scheduled",
                    "default": "session_scheduled",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "attempt": {
                        "type": "integer"
                      },
                      "wake_index": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "attempt",
                      "wake_index"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "session_starting",
                    "default": "session_starting",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "attempt": {
                        "type": "integer"
                      },
                      "reason": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "reason",
                      "attempt"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "session_retrying",
                    "default": "session_retrying",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "wake_index": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "wake_index"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "session_resumed",
                    "default": "session_resumed",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {},
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "session_idle",
                    "default": "session_idle",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {},
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "session_closed",
                    "default": "session_closed",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "reason": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "reason"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "session_cancelled",
                    "default": "session_cancelled",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "author": {
                        "type": "object"
                      },
                      "body": {
                        "type": "string"
                      },
                      "closes_session": {
                        "type": "boolean"
                      },
                      "message_id": {
                        "type": "string"
                      },
                      "sender_attribution_id": {
                        "type": "object"
                      },
                      "sender_attribution_type": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "message_id",
                      "body"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "message_received",
                    "default": "message_received",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "message_id": {
                        "type": "string"
                      },
                      "turn_id": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "message_id",
                      "turn_id"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "message_delivered",
                    "default": "message_delivered",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "message_id": {
                        "type": "string"
                      },
                      "turn_id": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "message_id",
                      "turn_id"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "message_requeued",
                    "default": "message_requeued",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "turn_id": {
                        "type": "string"
                      },
                      "turn_index": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "turn_id",
                      "turn_index"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "turn_started",
                    "default": "turn_started",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "duration_ms": {
                        "type": "object"
                      },
                      "turn_id": {
                        "type": "string"
                      },
                      "turn_index": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "turn_id",
                      "turn_index"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "turn_completed",
                    "default": "turn_completed",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "turn_id": {
                        "type": "string"
                      },
                      "turn_index": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "turn_id",
                      "turn_index"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "turn_failed",
                    "default": "turn_failed",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "repositories": {
                        "type": "array"
                      }
                    },
                    "required": [
                      "repositories"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "sandbox_starting",
                    "default": "sandbox_starting",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "detail": {
                        "type": "object"
                      },
                      "duration_ms": {
                        "type": "object"
                      },
                      "phase": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string"
                      },
                      "step": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "phase",
                      "status"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "sandbox_phase",
                    "default": "sandbox_phase",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "chunk": {
                        "type": "integer"
                      },
                      "lines": {
                        "type": "array"
                      },
                      "phase": {
                        "type": "string"
                      },
                      "step": {
                        "type": "object"
                      },
                      "stream": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "phase",
                      "chunk",
                      "lines"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "sandbox_output",
                    "default": "sandbox_output",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "cache_tier": {
                        "type": "object"
                      },
                      "phase_timings": {
                        "type": "object"
                      },
                      "repositories": {
                        "type": "array"
                      }
                    },
                    "required": [
                      "repositories"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "sandbox_ready",
                    "default": "sandbox_ready",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              },
              {
                "properties": {
                  "cost": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "duration": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "feed_seq": {
                    "type": "integer"
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "platform",
                    "default": "platform",
                    "type": "string"
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "payload": {
                    "additionalProperties": true,
                    "properties": {
                      "findings": {
                        "type": "array"
                      },
                      "parse_errors": {
                        "type": "array"
                      },
                      "parser_version": {
                        "type": "string"
                      },
                      "raw": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "parser_version"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "outbox_collected",
                    "default": "outbox_collected",
                    "type": "string"
                  },
                  "sandbox_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_execution_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "stream_seq": {
                    "type": "integer"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "session_execution_id",
                  "turn_id",
                  "session_message_id",
                  "sandbox_id",
                  "feed_seq",
                  "stream_seq",
                  "source",
                  "record_type",
                  "record_format",
                  "payload",
                  "tools",
                  "tokens_info",
                  "cost",
                  "duration",
                  "model",
                  "created_at",
                  "kind"
                ],
                "type": "object",
                "x-ellipsis-preserve-payload": true
              }
            ]
          },
          {
            "properties": {
              "cost": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "duration": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "feed_seq": {
                "type": "integer"
              },
              "id": {
                "type": "string"
              },
              "kind": {
                "const": "unknown",
                "default": "unknown",
                "type": "string"
              },
              "model": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "payload": {
                "additionalProperties": true,
                "type": "object"
              },
              "record_format": {
                "type": "string"
              },
              "record_type": {
                "type": "string"
              },
              "sandbox_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_execution_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "type": "string"
              },
              "stream_seq": {
                "type": "integer"
              },
              "tokens_info": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "cache_creation_input_tokens": {
                        "type": "integer"
                      },
                      "cache_read_input_tokens": {
                        "type": "integer"
                      },
                      "cost_usd": {
                        "type": "number"
                      },
                      "input_tokens": {
                        "type": "integer"
                      },
                      "num_turns": {
                        "type": "integer"
                      },
                      "output_tokens": {
                        "type": "integer"
                      }
                    },
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tools": {
                "anyOf": [
                  {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "turn_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "id",
              "session_id",
              "session_execution_id",
              "turn_id",
              "session_message_id",
              "sandbox_id",
              "feed_seq",
              "stream_seq",
              "source",
              "record_type",
              "record_format",
              "payload",
              "tools",
              "tokens_info",
              "cost",
              "duration",
              "model",
              "created_at",
              "kind"
            ],
            "type": "object",
            "x-ellipsis-preserve-payload": true
          }
        ]
      },
      "type": "array"
    }
  },
  "required": [
    "records"
  ],
  "type": "object"
}
```

---

# Get a session

> Read a session status, cost, and settings.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id

## GET /v1/sessions/{session_id}

Read a session status, cost, and settings.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "session": {
    "agent": {
      "config": {
        "ellipsis": {
          "description": str,
          "enabled": bool,
          "kind": "agent",
          "metadata": {
            "annotations": {
              "[str]": str
            },
            "labels": [
              str
            ]
          },
          "name": str,
          "version": str
        },
        "input": {
          "json_schema": {
            "[str]": any
          },
          "message": str
        },
        "session": {
          "budget": {
            "day": float,
            "month": float,
            "session": float,
            "week": float
          },
          "claude_code": {
            "effort": str,
            "fallback_model": str,
            "max_turns": int,
            "model": str,
            "prompt": str,
            "settings": {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          },
          "codex": {
            "effort": str,
            "model": str,
            "prompt": str
          },
          "environment": { # str
            "compute": {
              "cpu": int,
              "memory": { # str | null
                "gb": int,
                "mb": int
              },
              "timeout": { # str | null
                "hours": int,
                "minutes": int,
                "seconds": int
              }
            },
            "hooks": {
              "after_checkout": { # str | null
                "run": str
              },
              "before_start": { # str | null
                "run": str
              },
              "build_base": { # str | null
                "inputs": [
                  str
                ],
                "run": str
              },
              "post_clone": str,
              "post_start": str
            },
            "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
            # McpRemoteServer]
              {
                "args": [
                  str
                ],
                "command": str,
                "env": {
                  "[str]": str
                },
                "name": str
              }
            ],
            "repositories": [
              {
                "name": str,
                "owner": str,
                "ref": str
              }
            ],
            "variables": [
              {
                "name": str,
                "value": str
              }
            ]
          },
          "output": {
            "json_schema": {
              "[str]": any
            }
          },
          "permissions": {
            "ellipsis": { # bool | str
              "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                {
                  "level": str,
                  "match": [
                    str
                  ]
                }
              ]
            },
            "github": {
              "permissions": { # "read_only" | null
                "[str]": str
              },
              "repositories": [
                str
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "linear_issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ]
          },
          "pull_request": {
            "base": [
              str
            ],
            "draft": bool,
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "head": [
              str
            ],
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "push": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "type": "react"
        }
      },
      "id": str
    },
    "attribution": {
      "id": str,
      "type": str,
      "user": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "type": str
      }
    },
    "budget": float,
    "claude_code": {
      "effort": str,
      "fallback_model": str,
      "max_turns": int,
      "model": str,
      "prompt": str,
      "settings": {
        "path": str,
        "repository": {
          "name": str,
          "owner": str,
          "ref": str
        }
      }
    },
    "codex": {
      "effort": str,
      "model": str,
      "prompt": str
    },
    "cost": {
      "cpu": int,
      "fee": int,
      "llm": int,
      "memory": int,
      "total": int
    },
    "environment": {
      "compute": {
        "cpu": int,
        "memory": { # str | null
          "gb": int,
          "mb": int
        },
        "timeout": { # str | null
          "hours": int,
          "minutes": int,
          "seconds": int
        }
      },
      "hooks": {
        "after_checkout": { # str | null
          "run": str
        },
        "before_start": { # str | null
          "run": str
        },
        "build_base": { # str | null
          "inputs": [
            str
          ],
          "run": str
        },
        "post_clone": str,
        "post_start": str
      },
      "id": str,
      "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
      # McpRemoteServer]
        {
          "args": [
            str
          ],
          "command": str,
          "env": {
            "[str]": str
          },
          "name": str
        }
      ],
      "repositories": [
        {
          "name": str,
          "owner": str,
          "ref": str
        }
      ],
      "source": str,
      "variables": [
        {
          "name": str,
          "value": str
        }
      ]
    },
    "event": { # null | GithubPullRequestEvent | GithubIssueEvent |
    # GithubPushEvent | LinearIssueEvent | SlackMessageEvent |
    # SlackChannelCreatedEvent | SentryAlertEvent
      "action": str, # "review_commented"
      "actor": {
        "avatar_url": str,
        "is_bot": bool,
        "name": str
      },
      "branch": str,
      "number": int,
      "repository": str,
      "title": str,
      "type": "github.pull_request",
      "url": str
    },
    "git": {
      "repos": [
        {
          "commits": [
            {
              "committed_at": str,
              "pushed": bool,
              "sha": str,
              "subject": str
            }
          ],
          "commits_total": int,
          "full_name": str,
          "local_commit": str,
          "local_uncommitted_files": [
            {
              "additions": int,
              "deletions": int,
              "path": str,
              "status": str
            }
          ],
          "prs": [
            {
              "gh_pr_id": int,
              "number": int,
              "title": str,
              "url": str
            }
          ],
          "remote_branch": str,
          "remote_commit": str
        }
      ]
    },
    "handler": {
      "agent_name": str,
      "id": str,
      "service": str,
      "sha": str
    },
    "id": str,
    "lifecycle": {
      "archived": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        }
      },
      "conversation": str,
      "detail": str,
      "interactive": bool,
      "last_execution_result": {
        "completion_reason": str,
        "detail": str
      },
      "prompting": {
        "blocked_reason": str,
        "detail": str,
        "enabled": bool,
        "surface_name": str
      },
      "status": str,
      "stopped": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        }
      },
      "timestamps": {
        "created_at": str,
        "last_activity_at": str,
        "last_message_at": str,
        "updated_at": str
      }
    },
    "metadata": {
      "[str]": str
    },
    "output": {
      "json_schema": {
        "[str]": any
      }
    },
    "parent": {
      "session_id": str
    },
    "permissions": {
      "ellipsis": { # bool | str
        "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
          {
            "level": str,
            "match": [
              str
            ]
          }
        ]
      },
      "github": {
        "permissions": { # "read_only" | null
          "[str]": str
        },
        "repositories": [
          str
        ]
      }
    },
    "skills": [
      {
        "path": str,
        "repository": {
          "name": str,
          "owner": str,
          "ref": str
        }
      }
    ],
    "source": str,
    "summary": {
      "created_at": str,
      "description": str
    },
    "tokens": {
      "cache_creation": int,
      "cache_read": int,
      "input": int,
      "model": str,
      "output": int,
      "total": int
    }
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.sessions.get("session_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.sessions.get("session_example");
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{session_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "session": {
      "additionalProperties": false,
      "allOf": [
        {
          "oneOf": [
            {
              "properties": {
                "claude_code": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "codex": {
                  "type": "null"
                }
              },
              "required": [
                "claude_code",
                "codex"
              ]
            },
            {
              "properties": {
                "claude_code": {
                  "type": "null"
                },
                "codex": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "required": [
                "claude_code",
                "codex"
              ]
            }
          ]
        }
      ],
      "properties": {
        "agent": {
          "anyOf": [
            {
              "properties": {
                "config": {
                  "additionalProperties": false,
                  "properties": {
                    "ellipsis": {
                      "additionalProperties": false,
                      "properties": {
                        "description": {
                          "type": "object"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "kind": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "name": {
                          "type": "object"
                        },
                        "version": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "description",
                        "enabled",
                        "kind",
                        "metadata",
                        "name",
                        "version"
                      ],
                      "type": "object"
                    },
                    "input": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "session": {
                      "additionalProperties": false,
                      "allOf": [
                        {
                          "type": "object"
                        }
                      ],
                      "properties": {
                        "budget": {
                          "type": "object"
                        },
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "budget",
                        "claude_code",
                        "codex",
                        "environment",
                        "output",
                        "permissions",
                        "skills"
                      ],
                      "type": "object"
                    },
                    "trigger": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "ellipsis",
                    "input",
                    "session",
                    "trigger"
                  ],
                  "type": "object"
                },
                "id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "config",
                "id"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "attribution": {
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "type": {
              "anyOf": [
                {
                  "enum": [
                    "github_user",
                    "linear_user",
                    "slack_user",
                    "api_key"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "user": {
              "anyOf": [
                {
                  "properties": {
                    "avatar_url": {
                      "type": "string"
                    },
                    "id": {
                      "type": "integer"
                    },
                    "login": {
                      "type": "string"
                    },
                    "type": {
                      "enum": [
                        "User",
                        "Organization",
                        "Bot",
                        "Mannequin"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "avatar_url",
                    "id",
                    "login",
                    "type"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "type",
            "user"
          ],
          "type": "object"
        },
        "budget": {
          "default": 0,
          "type": "number"
        },
        "claude_code": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "effort": {
                  "anyOf": [
                    {
                      "enum": [
                        "low",
                        "medium",
                        "high",
                        "xhigh",
                        "max"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "fallback_model": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "max_turns": {
                  "anyOf": [
                    {
                      "exclusiveMinimum": 0,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "model": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "settings": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "path": {
                          "type": "string"
                        },
                        "repository": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "path",
                        "repository"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "fallback_model",
                "max_turns",
                "model",
                "prompt",
                "settings"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "codex": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "effort": {
                  "anyOf": [
                    {
                      "enum": [
                        "none",
                        "low",
                        "medium",
                        "high",
                        "xhigh",
                        "max"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "model": {
                  "default": "gpt-5.6-terra",
                  "type": "string"
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "model",
                "prompt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "cost": {
          "properties": {
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "default": 0,
              "type": "integer"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "environment": {
          "additionalProperties": false,
          "properties": {
            "compute": {
              "additionalProperties": false,
              "properties": {
                "cpu": {
                  "anyOf": [
                    {
                      "maximum": 32,
                      "minimum": 2,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "memory": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "gb": {
                          "type": "object"
                        },
                        "mb": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "gb",
                        "mb"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "timeout": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "hours": {
                          "type": "object"
                        },
                        "minutes": {
                          "type": "object"
                        },
                        "seconds": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "hours",
                        "minutes",
                        "seconds"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "cpu",
                "memory",
                "timeout"
              ],
              "type": "object"
            },
            "hooks": {
              "additionalProperties": false,
              "properties": {
                "after_checkout": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "before_start": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "build_base": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "inputs": {
                          "type": "object"
                        },
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "inputs",
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_clone": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_start": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "after_checkout",
                "before_start",
                "build_base",
                "post_clone",
                "post_start"
              ],
              "type": "object"
            },
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "mcp_servers": {
              "default": [],
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "args": {
                        "type": "array"
                      },
                      "command": {
                        "type": "string"
                      },
                      "env": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "args",
                      "command",
                      "env",
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "headers": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "headers",
                      "name",
                      "url"
                    ],
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            },
            "repositories": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "ref": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "owner",
                  "ref"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "source": {
              "anyOf": [
                {
                  "enum": [
                    "request",
                    "agent",
                    "repo_default",
                    "account_default",
                    "platform_default"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "variables": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "value"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "compute",
            "hooks",
            "id",
            "mcp_servers",
            "repositories",
            "source",
            "variables"
          ],
          "type": "object"
        },
        "event": {
          "anyOf": [
            {
              "oneOf": [
                {
                  "properties": {
                    "action": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "type": "string"
                    },
                    "number": {
                      "type": "integer"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.pull_request",
                      "default": "github.pull_request",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "number",
                    "repository",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "opened",
                        "closed",
                        "commented"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "number": {
                      "type": "integer"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.issue",
                      "default": "github.issue",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "number",
                    "repository",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "after": {
                      "type": "string"
                    },
                    "before": {
                      "type": "string"
                    },
                    "branch": {
                      "type": "string"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.push",
                      "default": "github.push",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "actor",
                    "after",
                    "before",
                    "branch",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "identifier": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "number": {
                      "type": "integer"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "linear.issue",
                      "default": "linear.issue",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "identifier",
                    "number",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "message",
                        "app_mention"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "channel_id": {
                      "type": "string"
                    },
                    "channel_name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "message_ts": {
                      "type": "string"
                    },
                    "thread_ts": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "slack.message",
                      "default": "slack.message",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "channel_id",
                    "channel_name",
                    "message_ts",
                    "thread_ts",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "channel_id": {
                      "type": "string"
                    },
                    "channel_name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "slack.channel_created",
                      "default": "slack.channel_created",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "actor",
                    "channel_id",
                    "channel_name",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "issue_alert",
                        "metric_alert"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "organization_slug": {
                      "type": "string"
                    },
                    "project_slug": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "title": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "sentry.alert",
                      "default": "sentry.alert",
                      "type": "string"
                    },
                    "url": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "organization_slug",
                    "project_slug",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "git": {
          "anyOf": [
            {
              "properties": {
                "repos": {
                  "default": [],
                  "items": {
                    "properties": {
                      "commits": {
                        "type": "array"
                      },
                      "commits_total": {
                        "type": "integer"
                      },
                      "full_name": {
                        "type": "string"
                      },
                      "local_commit": {
                        "type": "object"
                      },
                      "local_uncommitted_files": {
                        "type": "array"
                      },
                      "prs": {
                        "type": "array"
                      },
                      "remote_branch": {
                        "type": "object"
                      },
                      "remote_commit": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "commits",
                      "commits_total",
                      "full_name",
                      "local_commit",
                      "local_uncommitted_files",
                      "prs",
                      "remote_branch",
                      "remote_commit"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "repos"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "handler": {
          "anyOf": [
            {
              "properties": {
                "agent_name": {
                  "minLength": 1,
                  "type": "string"
                },
                "id": {
                  "minLength": 1,
                  "type": "string"
                },
                "service": {
                  "enum": [
                    "slack",
                    "github",
                    "linear",
                    "sentry"
                  ],
                  "type": "string"
                },
                "sha": {
                  "minLength": 1,
                  "type": "string"
                }
              },
              "required": [
                "agent_name",
                "id",
                "service",
                "sha"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "lifecycle": {
          "properties": {
            "archived": {
              "anyOf": [
                {
                  "properties": {
                    "at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "by": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "at",
                    "by"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "conversation": {
              "enum": [
                "open",
                "closed"
              ],
              "type": "string"
            },
            "detail": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "interactive": {
              "type": "boolean"
            },
            "last_execution_result": {
              "anyOf": [
                {
                  "properties": {
                    "completion_reason": {
                      "enum": [
                        "completed",
                        "budget_hit",
                        "payment_required",
                        "tool_call_failed",
                        "lifecycle_hook_failed",
                        "missing_repo_access",
                        "missing_token_permissions",
                        "missing_sandbox_variables",
                        "blocked",
                        "contact_email_required",
                        "cancelled",
                        "interrupted",
                        "error",
                        "stopped"
                      ],
                      "type": "string"
                    },
                    "detail": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "completion_reason",
                    "detail"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "prompting": {
              "properties": {
                "blocked_reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "mention_surface",
                        "ephemeral_trigger",
                        "non_interactive",
                        "harness_single_turn",
                        "closed"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "detail": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "enabled": {
                  "type": "boolean"
                },
                "surface_name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "blocked_reason",
                "detail",
                "enabled",
                "surface_name"
              ],
              "type": "object"
            },
            "status": {
              "enum": [
                "scheduled",
                "starting",
                "working",
                "waiting",
                "retrying",
                "idle",
                "closed",
                "failed",
                "stopped",
                "cancelled"
              ],
              "type": "string"
            },
            "stopped": {
              "anyOf": [
                {
                  "properties": {
                    "at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "by": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "at",
                    "by"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "timestamps": {
              "properties": {
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "last_activity_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "last_message_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "updated_at": {
                  "format": "date-time",
                  "type": "string"
                }
              },
              "required": [
                "created_at",
                "last_activity_at",
                "last_message_at",
                "updated_at"
              ],
              "type": "object"
            }
          },
          "required": [
            "archived",
            "conversation",
            "detail",
            "interactive",
            "last_execution_result",
            "prompting",
            "status",
            "stopped",
            "timestamps"
          ],
          "type": "object"
        },
        "metadata": {
          "items": {
            "type": "string"
          },
          "default": {},
          "type": "object"
        },
        "output": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "json_schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "required": [
                "json_schema"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "parent": {
          "anyOf": [
            {
              "properties": {
                "session_id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "session_id"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "permissions": {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "anyOf": [
                {
                  "enum": [
                    true,
                    "all"
                  ]
                },
                {
                  "items": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "array"
                      }
                    ]
                  },
                  "propertyNames": {
                    "$ref": "#/components/schemas/Resource"
                  },
                  "type": "object"
                }
              ],
              "default": true
            },
            "github": {
              "additionalProperties": false,
              "properties": {
                "permissions": {
                  "anyOf": [
                    {
                      "const": "read_only",
                      "type": "string"
                    },
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "repositories": {
                  "anyOf": [
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "permissions",
                "repositories"
              ],
              "type": "object"
            }
          },
          "required": [
            "ellipsis",
            "github"
          ],
          "type": "object"
        },
        "skills": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "path": {
                "type": "string"
              },
              "repository": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "owner": {
                        "type": "object"
                      },
                      "ref": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "name",
                      "owner",
                      "ref"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "path",
              "repository"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "source": {
          "enum": [
            "react",
            "web",
            "api",
            "cli",
            "mention",
            "cron"
          ],
          "type": "string"
        },
        "summary": {
          "anyOf": [
            {
              "properties": {
                "created_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "description": {
                  "type": "string"
                }
              },
              "required": [
                "created_at",
                "description"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "tokens": {
          "properties": {
            "cache_creation": {
              "default": 0,
              "type": "integer"
            },
            "cache_read": {
              "default": 0,
              "type": "integer"
            },
            "input": {
              "default": 0,
              "type": "integer"
            },
            "model": {
              "default": "",
              "type": "string"
            },
            "output": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cache_creation",
            "cache_read",
            "input",
            "model",
            "output",
            "total"
          ],
          "type": "object"
        }
      },
      "required": [
        "agent",
        "attribution",
        "budget",
        "claude_code",
        "codex",
        "cost",
        "environment",
        "event",
        "git",
        "handler",
        "id",
        "lifecycle",
        "metadata",
        "output",
        "parent",
        "permissions",
        "skills",
        "source",
        "summary",
        "tokens"
      ],
      "type": "object"
    }
  },
  "required": [
    "session"
  ],
  "type": "object"
}
```

---

# List sessions

> List sessions with filters for time, source, service, handler, agent, and attribution.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions

## GET /v1/sessions

List sessions with filters for time, source, service, handler, agent, and attribution.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "has_more": bool,
  "next_cursor": str,
  "pull_requests": {
    "[str]": {
      "additions": int,
      "changed_files": int,
      "commits": int,
      "deletions": int,
      "id": int,
      "status": str
    }
  },
  "sessions": [
    {
      "agent": {
        "config": {
          "ellipsis": {
            "description": str,
            "enabled": bool,
            "kind": "agent",
            "metadata": {
              "annotations": {
                "[str]": str
              },
              "labels": [
                str
              ]
            },
            "name": str,
            "version": str
          },
          "input": {
            "json_schema": {
              "[str]": any
            },
            "message": str
          },
          "session": {
            "budget": {
              "day": float,
              "month": float,
              "session": float,
              "week": float
            },
            "claude_code": {
              "effort": str,
              "fallback_model": str,
              "max_turns": int,
              "model": str,
              "prompt": str,
              "settings": {
                "path": str,
                "repository": {
                  "name": str,
                  "owner": str,
                  "ref": str
                }
              }
            },
            "codex": {
              "effort": str,
              "model": str,
              "prompt": str
            },
            "environment": { # str
              "compute": {
                "cpu": int,
                "memory": { # str | null
                  "gb": int,
                  "mb": int
                },
                "timeout": { # str | null
                  "hours": int,
                  "minutes": int,
                  "seconds": int
                }
              },
              "hooks": {
                "after_checkout": { # str | null
                  "run": str
                },
                "before_start": { # str | null
                  "run": str
                },
                "build_base": { # str | null
                  "inputs": [
                    str
                  ],
                  "run": str
                },
                "post_clone": str,
                "post_start": str
              },
              "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
              # McpRemoteServer]
                {
                  "args": [
                    str
                  ],
                  "command": str,
                  "env": {
                    "[str]": str
                  },
                  "name": str
                }
              ],
              "repositories": [
                {
                  "name": str,
                  "owner": str,
                  "ref": str
                }
              ],
              "variables": [
                {
                  "name": str,
                  "value": str
                }
              ]
            },
            "output": {
              "json_schema": {
                "[str]": any
              }
            },
            "permissions": {
              "ellipsis": { # bool | str
                "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                  {
                    "level": str,
                    "match": [
                      str
                    ]
                  }
                ]
              },
              "github": {
                "permissions": { # "read_only" | null
                  "[str]": str
                },
                "repositories": [
                  str
                ]
              }
            },
            "skills": [
              {
                "path": str,
                "repository": {
                  "name": str,
                  "owner": str,
                  "ref": str
                }
              }
            ]
          },
          "trigger": { # null | ReactTrigger | CronTrigger
            "issue": {
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "labels": [
                str
              ],
              "on": [
                str
              ],
              "repositories": { # list[str]
                "exclude": [
                  str
                ],
                "include": [
                  str
                ]
              }
            },
            "linear_issue": {
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "on": [
                str
              ]
            },
            "pull_request": {
              "base": [
                str
              ],
              "draft": bool,
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "head": [
                str
              ],
              "labels": [
                str
              ],
              "on": [
                str
              ],
              "paths": [
                str
              ],
              "repositories": { # list[str]
                "exclude": [
                  str
                ],
                "include": [
                  str
                ]
              }
            },
            "push": {
              "branch": [
                str
              ],
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "paths": [
                str
              ],
              "repositories": { # list[str]
                "exclude": [
                  str
                ],
                "include": [
                  str
                ]
              }
            },
            "sentry": {
              "on": [
                str
              ],
              "projects": [
                str
              ]
            },
            "slack_channel": {},
            "type": "react"
          }
        },
        "id": str
      },
      "attribution": {
        "id": str,
        "type": str,
        "user": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        }
      },
      "budget": float,
      "claude_code": {
        "effort": str,
        "fallback_model": str,
        "max_turns": int,
        "model": str,
        "prompt": str,
        "settings": {
          "path": str,
          "repository": {
            "name": str,
            "owner": str,
            "ref": str
          }
        }
      },
      "codex": {
        "effort": str,
        "model": str,
        "prompt": str
      },
      "cost": {
        "cpu": int,
        "fee": int,
        "llm": int,
        "memory": int,
        "total": int
      },
      "environment": {
        "compute": {
          "cpu": int,
          "memory": { # str | null
            "gb": int,
            "mb": int
          },
          "timeout": { # str | null
            "hours": int,
            "minutes": int,
            "seconds": int
          }
        },
        "hooks": {
          "after_checkout": { # str | null
            "run": str
          },
          "before_start": { # str | null
            "run": str
          },
          "build_base": { # str | null
            "inputs": [
              str
            ],
            "run": str
          },
          "post_clone": str,
          "post_start": str
        },
        "id": str,
        "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
        # McpRemoteServer]
          {
            "args": [
              str
            ],
            "command": str,
            "env": {
              "[str]": str
            },
            "name": str
          }
        ],
        "repositories": [
          {
            "name": str,
            "owner": str,
            "ref": str
          }
        ],
        "source": str,
        "variables": [
          {
            "name": str,
            "value": str
          }
        ]
      },
      "event": { # null | GithubPullRequestEvent | GithubIssueEvent |
      # GithubPushEvent | LinearIssueEvent | SlackMessageEvent |
      # SlackChannelCreatedEvent | SentryAlertEvent
        "action": str, # "review_commented"
        "actor": {
          "avatar_url": str,
          "is_bot": bool,
          "name": str
        },
        "branch": str,
        "number": int,
        "repository": str,
        "title": str,
        "type": "github.pull_request",
        "url": str
      },
      "git": {
        "repos": [
          {
            "commits": [
              {
                "committed_at": str,
                "pushed": bool,
                "sha": str,
                "subject": str
              }
            ],
            "commits_total": int,
            "full_name": str,
            "local_commit": str,
            "local_uncommitted_files": [
              {
                "additions": int,
                "deletions": int,
                "path": str,
                "status": str
              }
            ],
            "prs": [
              {
                "gh_pr_id": int,
                "number": int,
                "title": str,
                "url": str
              }
            ],
            "remote_branch": str,
            "remote_commit": str
          }
        ]
      },
      "handler": {
        "agent_name": str,
        "id": str,
        "service": str,
        "sha": str
      },
      "id": str,
      "lifecycle": {
        "archived": {
          "at": str,
          "by": {
            "avatar_url": str,
            "id": int,
            "login": str,
            "type": str
          }
        },
        "conversation": str,
        "detail": str,
        "interactive": bool,
        "last_execution_result": {
          "completion_reason": str,
          "detail": str
        },
        "prompting": {
          "blocked_reason": str,
          "detail": str,
          "enabled": bool,
          "surface_name": str
        },
        "status": str,
        "stopped": {
          "at": str,
          "by": {
            "avatar_url": str,
            "id": int,
            "login": str,
            "type": str
          }
        },
        "timestamps": {
          "created_at": str,
          "last_activity_at": str,
          "last_message_at": str,
          "updated_at": str
        }
      },
      "metadata": {
        "[str]": str
      },
      "output": {
        "json_schema": {
          "[str]": any
        }
      },
      "parent": {
        "session_id": str
      },
      "permissions": {
        "ellipsis": { # bool | str
          "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
            {
              "level": str,
              "match": [
                str
              ]
            }
          ]
        },
        "github": {
          "permissions": { # "read_only" | null
            "[str]": str
          },
          "repositories": [
            str
          ]
        }
      },
      "skills": [
        {
          "path": str,
          "repository": {
            "name": str,
            "owner": str,
            "ref": str
          }
        }
      ],
      "source": str,
      "summary": {
        "created_at": str,
        "description": str
      },
      "tokens": {
        "cache_creation": int,
        "cache_read": int,
        "input": int,
        "model": str,
        "output": int,
        "total": int
      }
    }
  ],
  "turn_counts": {
    "[str]": int
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

for item in client.sessions.list():
    print(item)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

for await (const item of await client.sessions.list()) {
  console.log(item);
}
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "has_more": {
      "default": false,
      "type": "boolean"
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "pull_requests": {
      "items": {
        "properties": {
          "additions": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "changed_files": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "commits": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "deletions": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "integer"
          },
          "status": {
            "enum": [
              "open",
              "draft",
              "merged",
              "closed"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "commits",
          "changed_files",
          "additions",
          "deletions"
        ],
        "type": "object"
      },
      "type": "object"
    },
    "sessions": {
      "items": {
        "additionalProperties": false,
        "allOf": [
          {
            "oneOf": [
              {
                "properties": {
                  "claude_code": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "codex": {
                    "type": "null"
                  }
                },
                "required": [
                  "claude_code",
                  "codex"
                ]
              },
              {
                "properties": {
                  "claude_code": {
                    "type": "null"
                  },
                  "codex": {
                    "additionalProperties": true,
                    "type": "object"
                  }
                },
                "required": [
                  "claude_code",
                  "codex"
                ]
              }
            ]
          }
        ],
        "properties": {
          "agent": {
            "anyOf": [
              {
                "properties": {
                  "config": {
                    "additionalProperties": false,
                    "properties": {
                      "ellipsis": {
                        "type": "object"
                      },
                      "input": {
                        "type": "object"
                      },
                      "session": {
                        "type": "object"
                      },
                      "trigger": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "ellipsis",
                      "input",
                      "session",
                      "trigger"
                    ],
                    "type": "object"
                  },
                  "id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "config",
                  "id"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "attribution": {
            "properties": {
              "id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "type": {
                "anyOf": [
                  {
                    "enum": [
                      "github_user",
                      "linear_user",
                      "slack_user",
                      "api_key"
                    ],
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "user": {
                "anyOf": [
                  {
                    "properties": {
                      "avatar_url": {
                        "type": "string"
                      },
                      "id": {
                        "type": "integer"
                      },
                      "login": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "id",
              "type",
              "user"
            ],
            "type": "object"
          },
          "budget": {
            "default": 0,
            "type": "number"
          },
          "claude_code": {
            "anyOf": [
              {
                "additionalProperties": false,
                "properties": {
                  "effort": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "fallback_model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "max_turns": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "model": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "prompt": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "settings": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "effort",
                  "fallback_model",
                  "max_turns",
                  "model",
                  "prompt",
                  "settings"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "codex": {
            "anyOf": [
              {
                "additionalProperties": false,
                "properties": {
                  "effort": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "model": {
                    "default": "gpt-5.6-terra",
                    "type": "string"
                  },
                  "prompt": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "effort",
                  "model",
                  "prompt"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "cost": {
            "properties": {
              "cpu": {
                "default": 0,
                "type": "integer"
              },
              "fee": {
                "default": 0,
                "type": "integer"
              },
              "llm": {
                "default": 0,
                "type": "integer"
              },
              "memory": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "cpu",
              "fee",
              "llm",
              "memory",
              "total"
            ],
            "type": "object"
          },
          "environment": {
            "additionalProperties": false,
            "properties": {
              "compute": {
                "additionalProperties": false,
                "properties": {
                  "cpu": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "memory": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "timeout": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "cpu",
                  "memory",
                  "timeout"
                ],
                "type": "object"
              },
              "hooks": {
                "additionalProperties": false,
                "properties": {
                  "after_checkout": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "before_start": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "build_base": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "post_clone": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "post_start": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "after_checkout",
                  "before_start",
                  "build_base",
                  "post_clone",
                  "post_start"
                ],
                "type": "object"
              },
              "id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "mcp_servers": {
                "default": [],
                "items": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "object"
                    },
                    {
                      "type": "object"
                    },
                    {
                      "type": "object"
                    }
                  ]
                },
                "type": "array"
              },
              "repositories": {
                "default": [],
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "owner": {
                      "type": "object"
                    },
                    "ref": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "name",
                    "owner",
                    "ref"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "source": {
                "anyOf": [
                  {
                    "enum": [
                      "request",
                      "agent",
                      "repo_default",
                      "account_default",
                      "platform_default"
                    ],
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "variables": {
                "default": [],
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "value": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "name",
                    "value"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "compute",
              "hooks",
              "id",
              "mcp_servers",
              "repositories",
              "source",
              "variables"
            ],
            "type": "object"
          },
          "event": {
            "anyOf": [
              {
                "oneOf": [
                  {
                    "properties": {
                      "action": {
                        "type": "object"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "branch": {
                        "type": "string"
                      },
                      "number": {
                        "type": "integer"
                      },
                      "repository": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "branch",
                      "number",
                      "repository",
                      "title",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "action": {
                        "type": "string"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "number": {
                        "type": "integer"
                      },
                      "repository": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "number",
                      "repository",
                      "title",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "actor": {
                        "type": "object"
                      },
                      "after": {
                        "type": "string"
                      },
                      "before": {
                        "type": "string"
                      },
                      "branch": {
                        "type": "string"
                      },
                      "repository": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "actor",
                      "after",
                      "before",
                      "branch",
                      "repository",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "action": {
                        "type": "object"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "identifier": {
                        "type": "object"
                      },
                      "number": {
                        "type": "integer"
                      },
                      "title": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "identifier",
                      "number",
                      "title",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "action": {
                        "type": "string"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "channel_id": {
                        "type": "string"
                      },
                      "channel_name": {
                        "type": "object"
                      },
                      "message_ts": {
                        "type": "string"
                      },
                      "thread_ts": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "channel_id",
                      "channel_name",
                      "message_ts",
                      "thread_ts",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "actor": {
                        "type": "object"
                      },
                      "channel_id": {
                        "type": "string"
                      },
                      "channel_name": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "actor",
                      "channel_id",
                      "channel_name",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "action": {
                        "type": "string"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "organization_slug": {
                        "type": "string"
                      },
                      "project_slug": {
                        "type": "object"
                      },
                      "title": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "organization_slug",
                      "project_slug",
                      "title",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "git": {
            "anyOf": [
              {
                "properties": {
                  "repos": {
                    "default": [],
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "repos"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "handler": {
            "anyOf": [
              {
                "properties": {
                  "agent_name": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "id": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "service": {
                    "enum": [
                      "slack",
                      "github",
                      "linear",
                      "sentry"
                    ],
                    "type": "string"
                  },
                  "sha": {
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "agent_name",
                  "id",
                  "service",
                  "sha"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string"
          },
          "lifecycle": {
            "properties": {
              "archived": {
                "anyOf": [
                  {
                    "properties": {
                      "at": {
                        "type": "string"
                      },
                      "by": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "at",
                      "by"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "conversation": {
                "enum": [
                  "open",
                  "closed"
                ],
                "type": "string"
              },
              "detail": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "interactive": {
                "type": "boolean"
              },
              "last_execution_result": {
                "anyOf": [
                  {
                    "properties": {
                      "completion_reason": {
                        "type": "string"
                      },
                      "detail": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "completion_reason",
                      "detail"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "prompting": {
                "properties": {
                  "blocked_reason": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "detail": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "surface_name": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "blocked_reason",
                  "detail",
                  "enabled",
                  "surface_name"
                ],
                "type": "object"
              },
              "status": {
                "enum": [
                  "scheduled",
                  "starting",
                  "working",
                  "waiting",
                  "retrying",
                  "idle",
                  "closed",
                  "failed",
                  "stopped",
                  "cancelled"
                ],
                "type": "string"
              },
              "stopped": {
                "anyOf": [
                  {
                    "properties": {
                      "at": {
                        "type": "string"
                      },
                      "by": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "at",
                      "by"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "timestamps": {
                "properties": {
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "last_activity_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "last_message_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "updated_at": {
                    "format": "date-time",
                    "type": "string"
                  }
                },
                "required": [
                  "created_at",
                  "last_activity_at",
                  "last_message_at",
                  "updated_at"
                ],
                "type": "object"
              }
            },
            "required": [
              "archived",
              "conversation",
              "detail",
              "interactive",
              "last_execution_result",
              "prompting",
              "status",
              "stopped",
              "timestamps"
            ],
            "type": "object"
          },
          "metadata": {
            "items": {
              "type": "string"
            },
            "default": {},
            "type": "object"
          },
          "output": {
            "anyOf": [
              {
                "additionalProperties": false,
                "properties": {
                  "json_schema": {
                    "additionalProperties": true,
                    "type": "object"
                  }
                },
                "required": [
                  "json_schema"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "parent": {
            "anyOf": [
              {
                "properties": {
                  "session_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "session_id"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "permissions": {
            "additionalProperties": false,
            "properties": {
              "ellipsis": {
                "anyOf": [
                  {
                    "enum": [
                      true,
                      "all"
                    ]
                  },
                  {
                    "items": {
                      "type": "object"
                    },
                    "propertyNames": {
                      "$ref": "#/components/schemas/Resource"
                    },
                    "type": "object"
                  }
                ],
                "default": true
              },
              "github": {
                "additionalProperties": false,
                "properties": {
                  "permissions": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "repositories": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "permissions",
                  "repositories"
                ],
                "type": "object"
              }
            },
            "required": [
              "ellipsis",
              "github"
            ],
            "type": "object"
          },
          "skills": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "path": {
                  "type": "string"
                },
                "repository": {
                  "anyOf": [
                    {
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "path",
                "repository"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "source": {
            "enum": [
              "react",
              "web",
              "api",
              "cli",
              "mention",
              "cron"
            ],
            "type": "string"
          },
          "summary": {
            "anyOf": [
              {
                "properties": {
                  "created_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "description": {
                    "type": "string"
                  }
                },
                "required": [
                  "created_at",
                  "description"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "tokens": {
            "properties": {
              "cache_creation": {
                "default": 0,
                "type": "integer"
              },
              "cache_read": {
                "default": 0,
                "type": "integer"
              },
              "input": {
                "default": 0,
                "type": "integer"
              },
              "model": {
                "default": "",
                "type": "string"
              },
              "output": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "cache_creation",
              "cache_read",
              "input",
              "model",
              "output",
              "total"
            ],
            "type": "object"
          }
        },
        "required": [
          "agent",
          "attribution",
          "budget",
          "claude_code",
          "codex",
          "cost",
          "environment",
          "event",
          "git",
          "handler",
          "id",
          "lifecycle",
          "metadata",
          "output",
          "parent",
          "permissions",
          "skills",
          "source",
          "summary",
          "tokens"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "turn_counts": {
      "items": {
        "type": "integer"
      },
      "type": "object"
    }
  },
  "required": [
    "sessions"
  ],
  "type": "object"
}
```

---

# Sessions

> Sessions run agents in the cloud. Start work, send follow-up messages, inspect progress, and retrieve transcripts, changes, and structured output.

Source: https://www.ellipsis.dev/docs/api/sessions

## Manage

- [`POST /v1/sessions`](https://www.ellipsis.dev/docs/api/sessions/post-sessions): Start a session
- [`POST /v1/sessions/{session_id}/messages`](https://www.ellipsis.dev/docs/api/sessions/post-sessions-session_id-messages): Send a message
- [`POST /v1/sessions/{session_id}/stop`](https://www.ellipsis.dev/docs/api/sessions/post-sessions-session_id-stop): Stop a session

## Find

- [`GET /v1/sessions`](https://www.ellipsis.dev/docs/api/sessions/get-sessions): List sessions
- [`GET /v1/sessions/search`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-search): Search sessions
- [`GET /v1/sessions/{session_id}`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id): Get a session

## Activity and transcripts

- [`GET /v1/sessions/{session_id}/executions`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-executions): List executions
- [`GET /v1/sessions/{session_id}/records`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-records): List records
- [`GET /v1/sessions/{session_id}/download`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-download): Download a transcript

## Results and changes

- [`GET /v1/sessions/{session_id}/output`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-output): Get structured output
- [`GET /v1/sessions/{session_id}/diff`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-diff): Get changes
- [`GET /v1/sessions/{session_id}/git`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-git): Get commits and pull requests

---

# Send a message

> Send a follow-up to a conversation. Messages received during a turn wait for the next turn. Reuse an idempotency key when retrying the same message.

Source: https://www.ellipsis.dev/docs/api/sessions/post-sessions-session_id-messages

## POST /v1/sessions/{session_id}/messages

Send a follow-up to a conversation. Messages received during a turn wait for the next turn. Reuse an idempotency key when retrying the same message.

Required permissions: write:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Request

```text
{
  "idempotency_key": str,
  "images": [
    {
      "data": str,
      "media_type": str
    }
  ],
  "message": str
}
```

### Response

```text
{
  "message": {
    "author": str,
    "body": str,
    "created_at": str,
    "delivered_at": str,
    "delivered_turn_id": str,
    "feed_seq": int,
    "id": str,
    "images": [
      {
        "index": int,
        "media_type": str,
        "size_bytes": int
      }
    ],
    "sender_attribution_id": str,
    "sender_attribution_type": str,
    "session_id": str,
    "status": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.SendSessionMessageRequest.model_validate(
    {
      "message": "Add a regression test.",
      "idempotency_key": "add-test"
    }
)

result = client.sessions.send_message(
    "session_example",
    request.message,
    idempotency_key=request.idempotency_key,
)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.sessions.sendMessage>[1] = {
  "message": "Add a regression test.",
  "idempotency_key": "add-test"
};

const result = await client.sessions.sendMessage("session_example", request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/sessions/{session_id}/messages" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Add a regression test.",
  "idempotency_key": "add-test"
}'
```

### Request schema

```json
{
  "properties": {
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "images": {
      "items": {
        "properties": {
          "data": {
            "type": "string"
          },
          "media_type": {
            "enum": [
              "image/png",
              "image/jpeg",
              "image/gif",
              "image/webp"
            ],
            "type": "string"
          }
        },
        "required": [
          "media_type",
          "data"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "message"
  ],
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "message": {
      "properties": {
        "author": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "body": {
          "type": "string"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "delivered_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "delivered_turn_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "feed_seq": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "images": {
          "items": {
            "properties": {
              "index": {
                "type": "integer"
              },
              "media_type": {
                "type": "string"
              },
              "size_bytes": {
                "type": "integer"
              }
            },
            "required": [
              "index",
              "media_type",
              "size_bytes"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "sender_attribution_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "sender_attribution_type": {
          "anyOf": [
            {
              "enum": [
                "github_user",
                "linear_user",
                "slack_user",
                "api_key"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "session_id": {
          "type": "string"
        },
        "status": {
          "enum": [
            "pending",
            "delivered"
          ],
          "type": "string"
        }
      },
      "required": [
        "id",
        "session_id",
        "status",
        "body",
        "created_at"
      ],
      "type": "object"
    }
  },
  "required": [
    "message"
  ],
  "type": "object"
}
```

---

# Stop a session

> Stop a session. Its recorded history remains available.

Source: https://www.ellipsis.dev/docs/api/sessions/post-sessions-session_id-stop

## POST /v1/sessions/{session_id}/stop

Stop a session. Its recorded history remains available.

Required permissions: write:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Response

```text
{
  "session": {
    "agent": {
      "config": {
        "ellipsis": {
          "description": str,
          "enabled": bool,
          "kind": "agent",
          "metadata": {
            "annotations": {
              "[str]": str
            },
            "labels": [
              str
            ]
          },
          "name": str,
          "version": str
        },
        "input": {
          "json_schema": {
            "[str]": any
          },
          "message": str
        },
        "session": {
          "budget": {
            "day": float,
            "month": float,
            "session": float,
            "week": float
          },
          "claude_code": {
            "effort": str,
            "fallback_model": str,
            "max_turns": int,
            "model": str,
            "prompt": str,
            "settings": {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          },
          "codex": {
            "effort": str,
            "model": str,
            "prompt": str
          },
          "environment": { # str
            "compute": {
              "cpu": int,
              "memory": { # str | null
                "gb": int,
                "mb": int
              },
              "timeout": { # str | null
                "hours": int,
                "minutes": int,
                "seconds": int
              }
            },
            "hooks": {
              "after_checkout": { # str | null
                "run": str
              },
              "before_start": { # str | null
                "run": str
              },
              "build_base": { # str | null
                "inputs": [
                  str
                ],
                "run": str
              },
              "post_clone": str,
              "post_start": str
            },
            "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
            # McpRemoteServer]
              {
                "args": [
                  str
                ],
                "command": str,
                "env": {
                  "[str]": str
                },
                "name": str
              }
            ],
            "repositories": [
              {
                "name": str,
                "owner": str,
                "ref": str
              }
            ],
            "variables": [
              {
                "name": str,
                "value": str
              }
            ]
          },
          "output": {
            "json_schema": {
              "[str]": any
            }
          },
          "permissions": {
            "ellipsis": { # bool | str
              "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                {
                  "level": str,
                  "match": [
                    str
                  ]
                }
              ]
            },
            "github": {
              "permissions": { # "read_only" | null
                "[str]": str
              },
              "repositories": [
                str
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "linear_issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ]
          },
          "pull_request": {
            "base": [
              str
            ],
            "draft": bool,
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "head": [
              str
            ],
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "push": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "type": "react"
        }
      },
      "id": str
    },
    "attribution": {
      "id": str,
      "type": str,
      "user": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "type": str
      }
    },
    "budget": float,
    "claude_code": {
      "effort": str,
      "fallback_model": str,
      "max_turns": int,
      "model": str,
      "prompt": str,
      "settings": {
        "path": str,
        "repository": {
          "name": str,
          "owner": str,
          "ref": str
        }
      }
    },
    "codex": {
      "effort": str,
      "model": str,
      "prompt": str
    },
    "cost": {
      "cpu": int,
      "fee": int,
      "llm": int,
      "memory": int,
      "total": int
    },
    "environment": {
      "compute": {
        "cpu": int,
        "memory": { # str | null
          "gb": int,
          "mb": int
        },
        "timeout": { # str | null
          "hours": int,
          "minutes": int,
          "seconds": int
        }
      },
      "hooks": {
        "after_checkout": { # str | null
          "run": str
        },
        "before_start": { # str | null
          "run": str
        },
        "build_base": { # str | null
          "inputs": [
            str
          ],
          "run": str
        },
        "post_clone": str,
        "post_start": str
      },
      "id": str,
      "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
      # McpRemoteServer]
        {
          "args": [
            str
          ],
          "command": str,
          "env": {
            "[str]": str
          },
          "name": str
        }
      ],
      "repositories": [
        {
          "name": str,
          "owner": str,
          "ref": str
        }
      ],
      "source": str,
      "variables": [
        {
          "name": str,
          "value": str
        }
      ]
    },
    "event": { # null | GithubPullRequestEvent | GithubIssueEvent |
    # GithubPushEvent | LinearIssueEvent | SlackMessageEvent |
    # SlackChannelCreatedEvent | SentryAlertEvent
      "action": str, # "review_commented"
      "actor": {
        "avatar_url": str,
        "is_bot": bool,
        "name": str
      },
      "branch": str,
      "number": int,
      "repository": str,
      "title": str,
      "type": "github.pull_request",
      "url": str
    },
    "git": {
      "repos": [
        {
          "commits": [
            {
              "committed_at": str,
              "pushed": bool,
              "sha": str,
              "subject": str
            }
          ],
          "commits_total": int,
          "full_name": str,
          "local_commit": str,
          "local_uncommitted_files": [
            {
              "additions": int,
              "deletions": int,
              "path": str,
              "status": str
            }
          ],
          "prs": [
            {
              "gh_pr_id": int,
              "number": int,
              "title": str,
              "url": str
            }
          ],
          "remote_branch": str,
          "remote_commit": str
        }
      ]
    },
    "handler": {
      "agent_name": str,
      "id": str,
      "service": str,
      "sha": str
    },
    "id": str,
    "lifecycle": {
      "archived": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        }
      },
      "conversation": str,
      "detail": str,
      "interactive": bool,
      "last_execution_result": {
        "completion_reason": str,
        "detail": str
      },
      "prompting": {
        "blocked_reason": str,
        "detail": str,
        "enabled": bool,
        "surface_name": str
      },
      "status": str,
      "stopped": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        }
      },
      "timestamps": {
        "created_at": str,
        "last_activity_at": str,
        "last_message_at": str,
        "updated_at": str
      }
    },
    "metadata": {
      "[str]": str
    },
    "output": {
      "json_schema": {
        "[str]": any
      }
    },
    "parent": {
      "session_id": str
    },
    "permissions": {
      "ellipsis": { # bool | str
        "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
          {
            "level": str,
            "match": [
              str
            ]
          }
        ]
      },
      "github": {
        "permissions": { # "read_only" | null
          "[str]": str
        },
        "repositories": [
          str
        ]
      }
    },
    "skills": [
      {
        "path": str,
        "repository": {
          "name": str,
          "owner": str,
          "ref": str
        }
      }
    ],
    "source": str,
    "summary": {
      "created_at": str,
      "description": str
    },
    "tokens": {
      "cache_creation": int,
      "cache_read": int,
      "input": int,
      "model": str,
      "output": int,
      "total": int
    }
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

result = client.sessions.stop("session_example")
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const result = await client.sessions.stop("session_example");
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/sessions/{session_id}/stop" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "session": {
      "additionalProperties": false,
      "allOf": [
        {
          "oneOf": [
            {
              "properties": {
                "claude_code": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "codex": {
                  "type": "null"
                }
              },
              "required": [
                "claude_code",
                "codex"
              ]
            },
            {
              "properties": {
                "claude_code": {
                  "type": "null"
                },
                "codex": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "required": [
                "claude_code",
                "codex"
              ]
            }
          ]
        }
      ],
      "properties": {
        "agent": {
          "anyOf": [
            {
              "properties": {
                "config": {
                  "additionalProperties": false,
                  "properties": {
                    "ellipsis": {
                      "additionalProperties": false,
                      "properties": {
                        "description": {
                          "type": "object"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "kind": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "name": {
                          "type": "object"
                        },
                        "version": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "description",
                        "enabled",
                        "kind",
                        "metadata",
                        "name",
                        "version"
                      ],
                      "type": "object"
                    },
                    "input": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "session": {
                      "additionalProperties": false,
                      "allOf": [
                        {
                          "type": "object"
                        }
                      ],
                      "properties": {
                        "budget": {
                          "type": "object"
                        },
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "budget",
                        "claude_code",
                        "codex",
                        "environment",
                        "output",
                        "permissions",
                        "skills"
                      ],
                      "type": "object"
                    },
                    "trigger": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "ellipsis",
                    "input",
                    "session",
                    "trigger"
                  ],
                  "type": "object"
                },
                "id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "config",
                "id"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "attribution": {
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "type": {
              "anyOf": [
                {
                  "enum": [
                    "github_user",
                    "linear_user",
                    "slack_user",
                    "api_key"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "user": {
              "anyOf": [
                {
                  "properties": {
                    "avatar_url": {
                      "type": "string"
                    },
                    "id": {
                      "type": "integer"
                    },
                    "login": {
                      "type": "string"
                    },
                    "type": {
                      "enum": [
                        "User",
                        "Organization",
                        "Bot",
                        "Mannequin"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "avatar_url",
                    "id",
                    "login",
                    "type"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "type",
            "user"
          ],
          "type": "object"
        },
        "budget": {
          "default": 0,
          "type": "number"
        },
        "claude_code": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "effort": {
                  "anyOf": [
                    {
                      "enum": [
                        "low",
                        "medium",
                        "high",
                        "xhigh",
                        "max"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "fallback_model": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "max_turns": {
                  "anyOf": [
                    {
                      "exclusiveMinimum": 0,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "model": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "settings": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "path": {
                          "type": "string"
                        },
                        "repository": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "path",
                        "repository"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "fallback_model",
                "max_turns",
                "model",
                "prompt",
                "settings"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "codex": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "effort": {
                  "anyOf": [
                    {
                      "enum": [
                        "none",
                        "low",
                        "medium",
                        "high",
                        "xhigh",
                        "max"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "model": {
                  "default": "gpt-5.6-terra",
                  "type": "string"
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "model",
                "prompt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "cost": {
          "properties": {
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "default": 0,
              "type": "integer"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "environment": {
          "additionalProperties": false,
          "properties": {
            "compute": {
              "additionalProperties": false,
              "properties": {
                "cpu": {
                  "anyOf": [
                    {
                      "maximum": 32,
                      "minimum": 2,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "memory": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "gb": {
                          "type": "object"
                        },
                        "mb": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "gb",
                        "mb"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "timeout": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "hours": {
                          "type": "object"
                        },
                        "minutes": {
                          "type": "object"
                        },
                        "seconds": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "hours",
                        "minutes",
                        "seconds"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "cpu",
                "memory",
                "timeout"
              ],
              "type": "object"
            },
            "hooks": {
              "additionalProperties": false,
              "properties": {
                "after_checkout": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "before_start": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "build_base": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "inputs": {
                          "type": "object"
                        },
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "inputs",
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_clone": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_start": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "after_checkout",
                "before_start",
                "build_base",
                "post_clone",
                "post_start"
              ],
              "type": "object"
            },
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "mcp_servers": {
              "default": [],
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "args": {
                        "type": "array"
                      },
                      "command": {
                        "type": "string"
                      },
                      "env": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "args",
                      "command",
                      "env",
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "headers": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "headers",
                      "name",
                      "url"
                    ],
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            },
            "repositories": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "ref": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "owner",
                  "ref"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "source": {
              "anyOf": [
                {
                  "enum": [
                    "request",
                    "agent",
                    "repo_default",
                    "account_default",
                    "platform_default"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "variables": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "value"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "compute",
            "hooks",
            "id",
            "mcp_servers",
            "repositories",
            "source",
            "variables"
          ],
          "type": "object"
        },
        "event": {
          "anyOf": [
            {
              "oneOf": [
                {
                  "properties": {
                    "action": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "type": "string"
                    },
                    "number": {
                      "type": "integer"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.pull_request",
                      "default": "github.pull_request",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "number",
                    "repository",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "opened",
                        "closed",
                        "commented"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "number": {
                      "type": "integer"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.issue",
                      "default": "github.issue",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "number",
                    "repository",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "after": {
                      "type": "string"
                    },
                    "before": {
                      "type": "string"
                    },
                    "branch": {
                      "type": "string"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.push",
                      "default": "github.push",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "actor",
                    "after",
                    "before",
                    "branch",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "identifier": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "number": {
                      "type": "integer"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "linear.issue",
                      "default": "linear.issue",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "identifier",
                    "number",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "message",
                        "app_mention"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "channel_id": {
                      "type": "string"
                    },
                    "channel_name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "message_ts": {
                      "type": "string"
                    },
                    "thread_ts": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "slack.message",
                      "default": "slack.message",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "channel_id",
                    "channel_name",
                    "message_ts",
                    "thread_ts",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "channel_id": {
                      "type": "string"
                    },
                    "channel_name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "slack.channel_created",
                      "default": "slack.channel_created",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "actor",
                    "channel_id",
                    "channel_name",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "issue_alert",
                        "metric_alert"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "organization_slug": {
                      "type": "string"
                    },
                    "project_slug": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "title": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "sentry.alert",
                      "default": "sentry.alert",
                      "type": "string"
                    },
                    "url": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "organization_slug",
                    "project_slug",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "git": {
          "anyOf": [
            {
              "properties": {
                "repos": {
                  "default": [],
                  "items": {
                    "properties": {
                      "commits": {
                        "type": "array"
                      },
                      "commits_total": {
                        "type": "integer"
                      },
                      "full_name": {
                        "type": "string"
                      },
                      "local_commit": {
                        "type": "object"
                      },
                      "local_uncommitted_files": {
                        "type": "array"
                      },
                      "prs": {
                        "type": "array"
                      },
                      "remote_branch": {
                        "type": "object"
                      },
                      "remote_commit": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "commits",
                      "commits_total",
                      "full_name",
                      "local_commit",
                      "local_uncommitted_files",
                      "prs",
                      "remote_branch",
                      "remote_commit"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "repos"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "handler": {
          "anyOf": [
            {
              "properties": {
                "agent_name": {
                  "minLength": 1,
                  "type": "string"
                },
                "id": {
                  "minLength": 1,
                  "type": "string"
                },
                "service": {
                  "enum": [
                    "slack",
                    "github",
                    "linear",
                    "sentry"
                  ],
                  "type": "string"
                },
                "sha": {
                  "minLength": 1,
                  "type": "string"
                }
              },
              "required": [
                "agent_name",
                "id",
                "service",
                "sha"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "lifecycle": {
          "properties": {
            "archived": {
              "anyOf": [
                {
                  "properties": {
                    "at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "by": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "at",
                    "by"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "conversation": {
              "enum": [
                "open",
                "closed"
              ],
              "type": "string"
            },
            "detail": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "interactive": {
              "type": "boolean"
            },
            "last_execution_result": {
              "anyOf": [
                {
                  "properties": {
                    "completion_reason": {
                      "enum": [
                        "completed",
                        "budget_hit",
                        "payment_required",
                        "tool_call_failed",
                        "lifecycle_hook_failed",
                        "missing_repo_access",
                        "missing_token_permissions",
                        "missing_sandbox_variables",
                        "blocked",
                        "contact_email_required",
                        "cancelled",
                        "interrupted",
                        "error",
                        "stopped"
                      ],
                      "type": "string"
                    },
                    "detail": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "completion_reason",
                    "detail"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "prompting": {
              "properties": {
                "blocked_reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "mention_surface",
                        "ephemeral_trigger",
                        "non_interactive",
                        "harness_single_turn",
                        "closed"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "detail": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "enabled": {
                  "type": "boolean"
                },
                "surface_name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "blocked_reason",
                "detail",
                "enabled",
                "surface_name"
              ],
              "type": "object"
            },
            "status": {
              "enum": [
                "scheduled",
                "starting",
                "working",
                "waiting",
                "retrying",
                "idle",
                "closed",
                "failed",
                "stopped",
                "cancelled"
              ],
              "type": "string"
            },
            "stopped": {
              "anyOf": [
                {
                  "properties": {
                    "at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "by": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "at",
                    "by"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "timestamps": {
              "properties": {
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "last_activity_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "last_message_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "updated_at": {
                  "format": "date-time",
                  "type": "string"
                }
              },
              "required": [
                "created_at",
                "last_activity_at",
                "last_message_at",
                "updated_at"
              ],
              "type": "object"
            }
          },
          "required": [
            "archived",
            "conversation",
            "detail",
            "interactive",
            "last_execution_result",
            "prompting",
            "status",
            "stopped",
            "timestamps"
          ],
          "type": "object"
        },
        "metadata": {
          "items": {
            "type": "string"
          },
          "default": {},
          "type": "object"
        },
        "output": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "json_schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "required": [
                "json_schema"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "parent": {
          "anyOf": [
            {
              "properties": {
                "session_id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "session_id"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "permissions": {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "anyOf": [
                {
                  "enum": [
                    true,
                    "all"
                  ]
                },
                {
                  "items": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "array"
                      }
                    ]
                  },
                  "propertyNames": {
                    "$ref": "#/components/schemas/Resource"
                  },
                  "type": "object"
                }
              ],
              "default": true
            },
            "github": {
              "additionalProperties": false,
              "properties": {
                "permissions": {
                  "anyOf": [
                    {
                      "const": "read_only",
                      "type": "string"
                    },
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "repositories": {
                  "anyOf": [
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "permissions",
                "repositories"
              ],
              "type": "object"
            }
          },
          "required": [
            "ellipsis",
            "github"
          ],
          "type": "object"
        },
        "skills": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "path": {
                "type": "string"
              },
              "repository": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "owner": {
                        "type": "object"
                      },
                      "ref": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "name",
                      "owner",
                      "ref"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "path",
              "repository"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "source": {
          "enum": [
            "react",
            "web",
            "api",
            "cli",
            "mention",
            "cron"
          ],
          "type": "string"
        },
        "summary": {
          "anyOf": [
            {
              "properties": {
                "created_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "description": {
                  "type": "string"
                }
              },
              "required": [
                "created_at",
                "description"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "tokens": {
          "properties": {
            "cache_creation": {
              "default": 0,
              "type": "integer"
            },
            "cache_read": {
              "default": 0,
              "type": "integer"
            },
            "input": {
              "default": 0,
              "type": "integer"
            },
            "model": {
              "default": "",
              "type": "string"
            },
            "output": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cache_creation",
            "cache_read",
            "input",
            "model",
            "output",
            "total"
          ],
          "type": "object"
        }
      },
      "required": [
        "agent",
        "attribution",
        "budget",
        "claude_code",
        "codex",
        "cost",
        "environment",
        "event",
        "git",
        "handler",
        "id",
        "lifecycle",
        "metadata",
        "output",
        "parent",
        "permissions",
        "skills",
        "source",
        "summary",
        "tokens"
      ],
      "type": "object"
    }
  },
  "required": [
    "session"
  ],
  "type": "object"
}
```

---

# Start a session

> Start a cloud session. Select a harness explicitly. Provide an inline environment, reference a saved environment, or omit it to use the basic sandbox. Set lifecycle.interactive to false for one-shot work.

Source: https://www.ellipsis.dev/docs/api/sessions/post-sessions

## POST /v1/sessions

Start a cloud session. Select a harness explicitly. Provide an inline environment, reference a saved environment, or omit it to use the basic sandbox. Set lifecycle.interactive to false for one-shot work.

Required permissions: write:sessions.
API key: Supported.
CLI user token: Supported.
Sandbox token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.

### Request

```text
{
  "budget": float,
  "claude_code": {
    "effort": str,
    "fallback_model": str,
    "max_turns": int,
    "model": str,
    "prompt": str,
    "settings": {
      "path": str,
      "repository": {
        "name": str,
        "owner": str,
        "ref": str
      }
    }
  },
  "codex": {
    "effort": str,
    "model": str,
    "prompt": str
  },
  "environment": { # str | null
    "compute": {
      "cpu": int,
      "memory": { # str | null
        "gb": int,
        "mb": int
      },
      "timeout": { # str | null
        "hours": int,
        "minutes": int,
        "seconds": int
      }
    },
    "hooks": {
      "after_checkout": { # str | null
        "run": str
      },
      "before_start": { # str | null
        "run": str
      },
      "build_base": { # str | null
        "inputs": [
          str
        ],
        "run": str
      },
      "post_clone": str,
      "post_start": str
    },
    "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
    # McpRemoteServer]
      {
        "args": [
          str
        ],
        "command": str,
        "env": {
          "[str]": str
        },
        "name": str
      }
    ],
    "repositories": [
      {
        "name": str,
        "owner": str,
        "ref": str
      }
    ],
    "variables": [
      {
        "name": str,
        "value": str
      }
    ]
  },
  "force_rebuild": bool,
  "images": [
    {
      "data": str,
      "media_type": str
    }
  ],
  "lifecycle": {
    "interactive": bool
  },
  "metadata": {
    "[str]": str
  },
  "output": {
    "json_schema": {
      "[str]": any
    }
  },
  "permissions": {
    "ellipsis": { # bool | str
      "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
        {
          "level": str,
          "match": [
            str
          ]
        }
      ]
    },
    "github": {
      "permissions": { # "read_only" | null
        "[str]": str
      },
      "repositories": [
        str
      ]
    }
  },
  "repositories": [
    str
  ],
  "skills": [
    {
      "path": str,
      "repository": {
        "name": str,
        "owner": str,
        "ref": str
      }
    }
  ]
}
```

### Response

```text
{
  "session": {
    "agent": {
      "config": {
        "ellipsis": {
          "description": str,
          "enabled": bool,
          "kind": "agent",
          "metadata": {
            "annotations": {
              "[str]": str
            },
            "labels": [
              str
            ]
          },
          "name": str,
          "version": str
        },
        "input": {
          "json_schema": {
            "[str]": any
          },
          "message": str
        },
        "session": {
          "budget": {
            "day": float,
            "month": float,
            "session": float,
            "week": float
          },
          "claude_code": {
            "effort": str,
            "fallback_model": str,
            "max_turns": int,
            "model": str,
            "prompt": str,
            "settings": {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          },
          "codex": {
            "effort": str,
            "model": str,
            "prompt": str
          },
          "environment": { # str
            "compute": {
              "cpu": int,
              "memory": { # str | null
                "gb": int,
                "mb": int
              },
              "timeout": { # str | null
                "hours": int,
                "minutes": int,
                "seconds": int
              }
            },
            "hooks": {
              "after_checkout": { # str | null
                "run": str
              },
              "before_start": { # str | null
                "run": str
              },
              "build_base": { # str | null
                "inputs": [
                  str
                ],
                "run": str
              },
              "post_clone": str,
              "post_start": str
            },
            "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
            # McpRemoteServer]
              {
                "args": [
                  str
                ],
                "command": str,
                "env": {
                  "[str]": str
                },
                "name": str
              }
            ],
            "repositories": [
              {
                "name": str,
                "owner": str,
                "ref": str
              }
            ],
            "variables": [
              {
                "name": str,
                "value": str
              }
            ]
          },
          "output": {
            "json_schema": {
              "[str]": any
            }
          },
          "permissions": {
            "ellipsis": { # bool | str
              "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
                {
                  "level": str,
                  "match": [
                    str
                  ]
                }
              ]
            },
            "github": {
              "permissions": { # "read_only" | null
                "[str]": str
              },
              "repositories": [
                str
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "linear_issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ]
          },
          "pull_request": {
            "base": [
              str
            ],
            "draft": bool,
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "head": [
              str
            ],
            "labels": [
              str
            ],
            "on": [
              str
            ],
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "push": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "type": "react"
        }
      },
      "id": str
    },
    "attribution": {
      "id": str,
      "type": str,
      "user": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "type": str
      }
    },
    "budget": float,
    "claude_code": {
      "effort": str,
      "fallback_model": str,
      "max_turns": int,
      "model": str,
      "prompt": str,
      "settings": {
        "path": str,
        "repository": {
          "name": str,
          "owner": str,
          "ref": str
        }
      }
    },
    "codex": {
      "effort": str,
      "model": str,
      "prompt": str
    },
    "cost": {
      "cpu": int,
      "fee": int,
      "llm": int,
      "memory": int,
      "total": int
    },
    "environment": {
      "compute": {
        "cpu": int,
        "memory": { # str | null
          "gb": int,
          "mb": int
        },
        "timeout": { # str | null
          "hours": int,
          "minutes": int,
          "seconds": int
        }
      },
      "hooks": {
        "after_checkout": { # str | null
          "run": str
        },
        "before_start": { # str | null
          "run": str
        },
        "build_base": { # str | null
          "inputs": [
            str
          ],
          "run": str
        },
        "post_clone": str,
        "post_start": str
      },
      "id": str,
      "mcp_servers": [ # list[str | McpServerRef | McpStdioServer |
      # McpRemoteServer]
        {
          "args": [
            str
          ],
          "command": str,
          "env": {
            "[str]": str
          },
          "name": str
        }
      ],
      "repositories": [
        {
          "name": str,
          "owner": str,
          "ref": str
        }
      ],
      "source": str,
      "variables": [
        {
          "name": str,
          "value": str
        }
      ]
    },
    "event": { # null | GithubPullRequestEvent | GithubIssueEvent |
    # GithubPushEvent | LinearIssueEvent | SlackMessageEvent |
    # SlackChannelCreatedEvent | SentryAlertEvent
      "action": str, # "review_commented"
      "actor": {
        "avatar_url": str,
        "is_bot": bool,
        "name": str
      },
      "branch": str,
      "number": int,
      "repository": str,
      "title": str,
      "type": "github.pull_request",
      "url": str
    },
    "git": {
      "repos": [
        {
          "commits": [
            {
              "committed_at": str,
              "pushed": bool,
              "sha": str,
              "subject": str
            }
          ],
          "commits_total": int,
          "full_name": str,
          "local_commit": str,
          "local_uncommitted_files": [
            {
              "additions": int,
              "deletions": int,
              "path": str,
              "status": str
            }
          ],
          "prs": [
            {
              "gh_pr_id": int,
              "number": int,
              "title": str,
              "url": str
            }
          ],
          "remote_branch": str,
          "remote_commit": str
        }
      ]
    },
    "handler": {
      "agent_name": str,
      "id": str,
      "service": str,
      "sha": str
    },
    "id": str,
    "lifecycle": {
      "archived": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        }
      },
      "conversation": str,
      "detail": str,
      "interactive": bool,
      "last_execution_result": {
        "completion_reason": str,
        "detail": str
      },
      "prompting": {
        "blocked_reason": str,
        "detail": str,
        "enabled": bool,
        "surface_name": str
      },
      "status": str,
      "stopped": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        }
      },
      "timestamps": {
        "created_at": str,
        "last_activity_at": str,
        "last_message_at": str,
        "updated_at": str
      }
    },
    "metadata": {
      "[str]": str
    },
    "output": {
      "json_schema": {
        "[str]": any
      }
    },
    "parent": {
      "session_id": str
    },
    "permissions": {
      "ellipsis": { # bool | str
        "[str]": [ # str | EllipsisGrant | list[str | EllipsisGrant]
          {
            "level": str,
            "match": [
              str
            ]
          }
        ]
      },
      "github": {
        "permissions": { # "read_only" | null
          "[str]": str
        },
        "repositories": [
          str
        ]
      }
    },
    "skills": [
      {
        "path": str,
        "repository": {
          "name": str,
          "owner": str,
          "ref": str
        }
      }
    ],
    "source": str,
    "summary": {
      "created_at": str,
      "description": str
    },
    "tokens": {
      "cache_creation": int,
      "cache_read": int,
      "input": int,
      "model": str,
      "output": int,
      "total": int
    }
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.StartSessionRequest.model_validate(
    {
      "claude_code": {
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "lifecycle": {
        "interactive": False
      },
      "budget": 3
    }
)

result = client.sessions.start(
    budget=request.budget,
    claude_code=request.claude_code,
    environment=request.environment,
    lifecycle=request.lifecycle,
)
print(result)
```

### TypeScript

```typescript
import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.sessions.start>[0] = {
  "claude_code": {
    "prompt": "Run the tests and report failures."
  },
  "environment": "api-environment",
  "lifecycle": {
    "interactive": false
  },
  "budget": 3
};

const result = await client.sessions.start(request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/sessions" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "claude_code": {
    "prompt": "Run the tests and report failures."
  },
  "environment": "api-environment",
  "lifecycle": {
    "interactive": false
  },
  "budget": 3
}'
```

### Request schema

```json
{
  "additionalProperties": false,
  "allOf": [
    {
      "oneOf": [
        {
          "properties": {
            "claude_code": {
              "additionalProperties": true,
              "type": "object"
            },
            "codex": {
              "type": "null"
            }
          },
          "required": [
            "claude_code"
          ]
        },
        {
          "properties": {
            "claude_code": {
              "type": "null"
            },
            "codex": {
              "additionalProperties": true,
              "type": "object"
            }
          },
          "required": [
            "codex"
          ]
        }
      ]
    }
  ],
  "properties": {
    "budget": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "claude_code": {
      "anyOf": [
        {
          "additionalProperties": false,
          "properties": {
            "effort": {
              "anyOf": [
                {
                  "enum": [
                    "low",
                    "medium",
                    "high",
                    "xhigh",
                    "max"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "fallback_model": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "max_turns": {
              "anyOf": [
                {
                  "exclusiveMinimum": 0,
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "model": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "prompt": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "settings": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "path": {
                      "type": "string"
                    },
                    "repository": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "path"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "codex": {
      "anyOf": [
        {
          "additionalProperties": false,
          "properties": {
            "effort": {
              "anyOf": [
                {
                  "enum": [
                    "none",
                    "low",
                    "medium",
                    "high",
                    "xhigh",
                    "max"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "model": {
              "default": "gpt-5.6-terra",
              "type": "string"
            },
            "prompt": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "environment": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "additionalProperties": false,
          "properties": {
            "compute": {
              "additionalProperties": false,
              "properties": {
                "cpu": {
                  "anyOf": [
                    {
                      "maximum": 32,
                      "minimum": 2,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "memory": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "gb": {
                          "type": "object"
                        },
                        "mb": {
                          "type": "object"
                        }
                      },
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "timeout": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "hours": {
                          "type": "object"
                        },
                        "minutes": {
                          "type": "object"
                        },
                        "seconds": {
                          "type": "object"
                        }
                      },
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "type": "object"
            },
            "hooks": {
              "additionalProperties": false,
              "properties": {
                "after_checkout": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "before_start": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "build_base": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "inputs": {
                          "type": "object"
                        },
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_clone": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_start": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "type": "object"
            },
            "mcp_servers": {
              "default": [],
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "args": {
                        "type": "array"
                      },
                      "command": {
                        "type": "string"
                      },
                      "env": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name",
                      "command"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "headers": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name",
                      "url"
                    ],
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            },
            "repositories": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "ref": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "variables": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "force_rebuild": {
      "default": false,
      "type": "boolean"
    },
    "images": {
      "items": {
        "properties": {
          "data": {
            "type": "string"
          },
          "media_type": {
            "enum": [
              "image/png",
              "image/jpeg",
              "image/gif",
              "image/webp"
            ],
            "type": "string"
          }
        },
        "required": [
          "media_type",
          "data"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "lifecycle": {
      "additionalProperties": false,
      "properties": {
        "interactive": {
          "default": true,
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "metadata": {
      "items": {
        "type": "string"
      },
      "default": {},
      "type": "object"
    },
    "output": {
      "anyOf": [
        {
          "additionalProperties": false,
          "properties": {
            "json_schema": {
              "additionalProperties": true,
              "type": "object"
            }
          },
          "required": [
            "json_schema"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "permissions": {
      "anyOf": [
        {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "anyOf": [
                {
                  "enum": [
                    true,
                    "all"
                  ]
                },
                {
                  "items": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "array"
                      }
                    ]
                  },
                  "propertyNames": {
                    "$ref": "#/components/schemas/Resource"
                  },
                  "type": "object"
                }
              ],
              "default": true
            },
            "github": {
              "additionalProperties": false,
              "properties": {
                "permissions": {
                  "anyOf": [
                    {
                      "const": "read_only",
                      "type": "string"
                    },
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "repositories": {
                  "anyOf": [
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "type": "object"
            }
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "repositories": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ]
    },
    "skills": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": false,
            "properties": {
              "path": {
                "type": "string"
              },
              "repository": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "owner": {
                        "type": "object"
                      },
                      "ref": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "path"
            ],
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "type": "object"
}
```

### Response schema

```json
{
  "properties": {
    "session": {
      "additionalProperties": false,
      "allOf": [
        {
          "oneOf": [
            {
              "properties": {
                "claude_code": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "codex": {
                  "type": "null"
                }
              },
              "required": [
                "claude_code",
                "codex"
              ]
            },
            {
              "properties": {
                "claude_code": {
                  "type": "null"
                },
                "codex": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "required": [
                "claude_code",
                "codex"
              ]
            }
          ]
        }
      ],
      "properties": {
        "agent": {
          "anyOf": [
            {
              "properties": {
                "config": {
                  "additionalProperties": false,
                  "properties": {
                    "ellipsis": {
                      "additionalProperties": false,
                      "properties": {
                        "description": {
                          "type": "object"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "kind": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "name": {
                          "type": "object"
                        },
                        "version": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "description",
                        "enabled",
                        "kind",
                        "metadata",
                        "name",
                        "version"
                      ],
                      "type": "object"
                    },
                    "input": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "session": {
                      "additionalProperties": false,
                      "allOf": [
                        {
                          "type": "object"
                        }
                      ],
                      "properties": {
                        "budget": {
                          "type": "object"
                        },
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "budget",
                        "claude_code",
                        "codex",
                        "environment",
                        "output",
                        "permissions",
                        "skills"
                      ],
                      "type": "object"
                    },
                    "trigger": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "ellipsis",
                    "input",
                    "session",
                    "trigger"
                  ],
                  "type": "object"
                },
                "id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "config",
                "id"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "attribution": {
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "type": {
              "anyOf": [
                {
                  "enum": [
                    "github_user",
                    "linear_user",
                    "slack_user",
                    "api_key"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "user": {
              "anyOf": [
                {
                  "properties": {
                    "avatar_url": {
                      "type": "string"
                    },
                    "id": {
                      "type": "integer"
                    },
                    "login": {
                      "type": "string"
                    },
                    "type": {
                      "enum": [
                        "User",
                        "Organization",
                        "Bot",
                        "Mannequin"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "avatar_url",
                    "id",
                    "login",
                    "type"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "type",
            "user"
          ],
          "type": "object"
        },
        "budget": {
          "default": 0,
          "type": "number"
        },
        "claude_code": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "effort": {
                  "anyOf": [
                    {
                      "enum": [
                        "low",
                        "medium",
                        "high",
                        "xhigh",
                        "max"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "fallback_model": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "max_turns": {
                  "anyOf": [
                    {
                      "exclusiveMinimum": 0,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "model": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "settings": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "path": {
                          "type": "string"
                        },
                        "repository": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "path",
                        "repository"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "fallback_model",
                "max_turns",
                "model",
                "prompt",
                "settings"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "codex": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "effort": {
                  "anyOf": [
                    {
                      "enum": [
                        "none",
                        "low",
                        "medium",
                        "high",
                        "xhigh",
                        "max"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "model": {
                  "default": "gpt-5.6-terra",
                  "type": "string"
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "model",
                "prompt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "cost": {
          "properties": {
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "default": 0,
              "type": "integer"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "environment": {
          "additionalProperties": false,
          "properties": {
            "compute": {
              "additionalProperties": false,
              "properties": {
                "cpu": {
                  "anyOf": [
                    {
                      "maximum": 32,
                      "minimum": 2,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "memory": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "gb": {
                          "type": "object"
                        },
                        "mb": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "gb",
                        "mb"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "timeout": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "hours": {
                          "type": "object"
                        },
                        "minutes": {
                          "type": "object"
                        },
                        "seconds": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "hours",
                        "minutes",
                        "seconds"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "cpu",
                "memory",
                "timeout"
              ],
              "type": "object"
            },
            "hooks": {
              "additionalProperties": false,
              "properties": {
                "after_checkout": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "before_start": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "build_base": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "inputs": {
                          "type": "object"
                        },
                        "run": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "inputs",
                        "run"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_clone": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "post_start": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "after_checkout",
                "before_start",
                "build_base",
                "post_clone",
                "post_start"
              ],
              "type": "object"
            },
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "mcp_servers": {
              "default": [],
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "args": {
                        "type": "array"
                      },
                      "command": {
                        "type": "string"
                      },
                      "env": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "args",
                      "command",
                      "env",
                      "name"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "headers": {
                        "type": "object"
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "headers",
                      "name",
                      "url"
                    ],
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            },
            "repositories": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "ref": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "owner",
                  "ref"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "source": {
              "anyOf": [
                {
                  "enum": [
                    "request",
                    "agent",
                    "repo_default",
                    "account_default",
                    "platform_default"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "variables": {
              "default": [],
              "items": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "name",
                  "value"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "compute",
            "hooks",
            "id",
            "mcp_servers",
            "repositories",
            "source",
            "variables"
          ],
          "type": "object"
        },
        "event": {
          "anyOf": [
            {
              "oneOf": [
                {
                  "properties": {
                    "action": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "type": "string"
                    },
                    "number": {
                      "type": "integer"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.pull_request",
                      "default": "github.pull_request",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "number",
                    "repository",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "opened",
                        "closed",
                        "commented"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "number": {
                      "type": "integer"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.issue",
                      "default": "github.issue",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "number",
                    "repository",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "after": {
                      "type": "string"
                    },
                    "before": {
                      "type": "string"
                    },
                    "branch": {
                      "type": "string"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.push",
                      "default": "github.push",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "actor",
                    "after",
                    "before",
                    "branch",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "identifier": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "number": {
                      "type": "integer"
                    },
                    "title": {
                      "type": "string"
                    },
                    "type": {
                      "const": "linear.issue",
                      "default": "linear.issue",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "identifier",
                    "number",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "message",
                        "app_mention"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "channel_id": {
                      "type": "string"
                    },
                    "channel_name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "message_ts": {
                      "type": "string"
                    },
                    "thread_ts": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "slack.message",
                      "default": "slack.message",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "channel_id",
                    "channel_name",
                    "message_ts",
                    "thread_ts",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "channel_id": {
                      "type": "string"
                    },
                    "channel_name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "slack.channel_created",
                      "default": "slack.channel_created",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "actor",
                    "channel_id",
                    "channel_name",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "issue_alert",
                        "metric_alert"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "organization_slug": {
                      "type": "string"
                    },
                    "project_slug": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "title": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "sentry.alert",
                      "default": "sentry.alert",
                      "type": "string"
                    },
                    "url": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "organization_slug",
                    "project_slug",
                    "title",
                    "type",
                    "url"
                  ],
                  "type": "object"
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "git": {
          "anyOf": [
            {
              "properties": {
                "repos": {
                  "default": [],
                  "items": {
                    "properties": {
                      "commits": {
                        "type": "array"
                      },
                      "commits_total": {
                        "type": "integer"
                      },
                      "full_name": {
                        "type": "string"
                      },
                      "local_commit": {
                        "type": "object"
                      },
                      "local_uncommitted_files": {
                        "type": "array"
                      },
                      "prs": {
                        "type": "array"
                      },
                      "remote_branch": {
                        "type": "object"
                      },
                      "remote_commit": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "commits",
                      "commits_total",
                      "full_name",
                      "local_commit",
                      "local_uncommitted_files",
                      "prs",
                      "remote_branch",
                      "remote_commit"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "repos"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "handler": {
          "anyOf": [
            {
              "properties": {
                "agent_name": {
                  "minLength": 1,
                  "type": "string"
                },
                "id": {
                  "minLength": 1,
                  "type": "string"
                },
                "service": {
                  "enum": [
                    "slack",
                    "github",
                    "linear",
                    "sentry"
                  ],
                  "type": "string"
                },
                "sha": {
                  "minLength": 1,
                  "type": "string"
                }
              },
              "required": [
                "agent_name",
                "id",
                "service",
                "sha"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "lifecycle": {
          "properties": {
            "archived": {
              "anyOf": [
                {
                  "properties": {
                    "at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "by": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "at",
                    "by"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "conversation": {
              "enum": [
                "open",
                "closed"
              ],
              "type": "string"
            },
            "detail": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "interactive": {
              "type": "boolean"
            },
            "last_execution_result": {
              "anyOf": [
                {
                  "properties": {
                    "completion_reason": {
                      "enum": [
                        "completed",
                        "budget_hit",
                        "payment_required",
                        "tool_call_failed",
                        "lifecycle_hook_failed",
                        "missing_repo_access",
                        "missing_token_permissions",
                        "missing_sandbox_variables",
                        "blocked",
                        "contact_email_required",
                        "cancelled",
                        "interrupted",
                        "error",
                        "stopped"
                      ],
                      "type": "string"
                    },
                    "detail": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "completion_reason",
                    "detail"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "prompting": {
              "properties": {
                "blocked_reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "mention_surface",
                        "ephemeral_trigger",
                        "non_interactive",
                        "harness_single_turn",
                        "closed"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "detail": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "enabled": {
                  "type": "boolean"
                },
                "surface_name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "blocked_reason",
                "detail",
                "enabled",
                "surface_name"
              ],
              "type": "object"
            },
            "status": {
              "enum": [
                "scheduled",
                "starting",
                "working",
                "waiting",
                "retrying",
                "idle",
                "closed",
                "failed",
                "stopped",
                "cancelled"
              ],
              "type": "string"
            },
            "stopped": {
              "anyOf": [
                {
                  "properties": {
                    "at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "by": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "at",
                    "by"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "timestamps": {
              "properties": {
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "last_activity_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "last_message_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "updated_at": {
                  "format": "date-time",
                  "type": "string"
                }
              },
              "required": [
                "created_at",
                "last_activity_at",
                "last_message_at",
                "updated_at"
              ],
              "type": "object"
            }
          },
          "required": [
            "archived",
            "conversation",
            "detail",
            "interactive",
            "last_execution_result",
            "prompting",
            "status",
            "stopped",
            "timestamps"
          ],
          "type": "object"
        },
        "metadata": {
          "items": {
            "type": "string"
          },
          "default": {},
          "type": "object"
        },
        "output": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "json_schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "required": [
                "json_schema"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "parent": {
          "anyOf": [
            {
              "properties": {
                "session_id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "session_id"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "permissions": {
          "additionalProperties": false,
          "properties": {
            "ellipsis": {
              "anyOf": [
                {
                  "enum": [
                    true,
                    "all"
                  ]
                },
                {
                  "items": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      },
                      {
                        "type": "array"
                      }
                    ]
                  },
                  "propertyNames": {
                    "$ref": "#/components/schemas/Resource"
                  },
                  "type": "object"
                }
              ],
              "default": true
            },
            "github": {
              "additionalProperties": false,
              "properties": {
                "permissions": {
                  "anyOf": [
                    {
                      "const": "read_only",
                      "type": "string"
                    },
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "repositories": {
                  "anyOf": [
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "permissions",
                "repositories"
              ],
              "type": "object"
            }
          },
          "required": [
            "ellipsis",
            "github"
          ],
          "type": "object"
        },
        "skills": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "path": {
                "type": "string"
              },
              "repository": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "owner": {
                        "type": "object"
                      },
                      "ref": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "name",
                      "owner",
                      "ref"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "path",
              "repository"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "source": {
          "enum": [
            "react",
            "web",
            "api",
            "cli",
            "mention",
            "cron"
          ],
          "type": "string"
        },
        "summary": {
          "anyOf": [
            {
              "properties": {
                "created_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "description": {
                  "type": "string"
                }
              },
              "required": [
                "created_at",
                "description"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "tokens": {
          "properties": {
            "cache_creation": {
              "default": 0,
              "type": "integer"
            },
            "cache_read": {
              "default": 0,
              "type": "integer"
            },
            "input": {
              "default": 0,
              "type": "integer"
            },
            "model": {
              "default": "",
              "type": "string"
            },
            "output": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cache_creation",
            "cache_read",
            "input",
            "model",
            "output",
            "total"
          ],
          "type": "object"
        }
      },
      "required": [
        "agent",
        "attribution",
        "budget",
        "claude_code",
        "codex",
        "cost",
        "environment",
        "event",
        "git",
        "handler",
        "id",
        "lifecycle",
        "metadata",
        "output",
        "parent",
        "permissions",
        "skills",
        "source",
        "summary",
        "tokens"
      ],
      "type": "object"
    }
  },
  "required": [
    "session"
  ],
  "type": "object"
}
```

---

# Blog

- [Introducing the Ellipsis Agent Cloud](https://www.ellipsis.dev/blog/the-ellipsis-agent-cloud): Ellipsis started in 2023 reviewing code and fixing bugs. Today we run managed coding agents: defined in your repo, deployed with git push, governed with permissions, transcripts, and hard spend caps.
- [The Future of Software Is the Agent](https://www.ellipsis.dev/blog/the-future-of-software-is-the-agent): The future of software is agents defined in code: versioned behavior, isolated cloud sessions, scoped permissions, and human judgment at the checkpoints that matter.
- [Lessons from 15 Months of Building LLM Agents](https://www.ellipsis.dev/blog/lessons-from-building-llm-agents): What we learned shipping autonomous coding agents to hundreds of engineering teams. Sandboxing, context management, cost control, and the things that actually matter.
- [🚨 Launch Alert: Codebase Reports](https://www.ellipsis.dev/blog/launch-alert-codebase-reports): Select a repository and a delivery window to get a daily, weekly, or monthly digest of what changed in your codebase, delivered via Slack or email.
- [🚨 Launch Alert: Implementation Plans for GitHub/Linear Issues](https://www.ellipsis.dev/blog/launch-alert-implementation-plans): Tag @ellipsis-dev on any GitHub or Linear issue to get an implementation plan grounded in your codebase and past pull requests.
- [How to Move Your GitHub App to GitLab](https://www.ellipsis.dev/blog/how-to-move-your-github-app-to-gitlab): GitHub bundles authentication, webhooks, and UI into one Application concept. GitLab splits them apart. What we learned bringing Ellipsis to GitLab.
- [Ellipsis Is Now SOC 2 Type I Certified](https://www.ellipsis.dev/blog/ellipsis-is-now-soc-ii-type-i-certified): Ellipsis has achieved SOC 2 Type I certification. Reach out for the report, and read about our no-data-persistence policy.
- [Ellipsis Raises a $2M Seed Round](https://www.ellipsis.dev/blog/ellipsis-raises-a-2m-seed-round): Ellipsis gets a LGTM from investors, including Y Combinator. $2M to automate the tedious parts of software engineering.
- [Ellipsis Joins Y Combinator](https://www.ellipsis.dev/blog/ellipsis-joins-y-combinator-w24): Ellipsis is joining Y Combinator's Winter 2024 batch. We are building an AI software engineer that reviews code and fixes bugs on every pull request.