# 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 agent sessions and manage agents with the CLI, Python, TypeScript, or curl.

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

## Guides

<span id="sdks" />
  - [Quick start](/docs/api/quick-start): Start your first agent session
  - [Authentication](/docs/api/authentication): Create and use an API key
  - [Python SDK](/docs/api/python-sdk): Handles, streaming, and typed errors
  - [TypeScript SDK](/docs/api/typescript-sdk): Handles, streaming, and typed errors
  - [CLI](https://github.com/ellipsis-dev/cli#readme): Commands and flags
  - [Session events](/docs/api/session-events): Every event a session emits

## Reference

<span id="choose-a-resource" />
  - [Agents](/docs/api/agents): Create, edit, and start agents
  - [Sessions](/docs/api/sessions): Follow sessions and read their output
  - [Environments](/docs/api/environments): Define where agents run
  - [Secrets](/docs/api/secrets): Store credentials for environments
  - [Account](/docs/api/account): Check budgets, usage, and models
  - [Integrations](/docs/api/integrations): List connected services and repositories
  - [OpenAPI](/openapi.v1.json): Full schema, including dashboard endpoints

---

# Python SDK

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

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

The Python SDK is a client for the `/v1` API with session handles, streaming, pagination, and typed errors.

## 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

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
handle = client.sessions.run(
    claude_code={
        "model": "claude-opus-5-5",
        "prompt": "Run the tests and report failures.",
    },
    environment="api-environment",
    conversation={"interactive": False},
    budget={"session": 3},
)
session = handle.wait(timeout=900)
print(session.turn.status, session.turn.reason, session.turn.detail)
```

`run` returns a handle while work continues. `wait` polls until the turn that answers the prompt reaches a final status (`completed`, `failed`, `stopped`, or `cancelled`) and returns the session; `session.turn` is that turn. A timeout stops waiting and leaves the session running.

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

## Continue a conversation

Leave `conversation.interactive` enabled to accept messages:

```python
handle = client.sessions.run(
    claude_code={
        "model": "claude-opus-5-5",
        "prompt": "Investigate the failing validation test.",
    },
    environment="api-environment",
    budget={"session": 5},
)
handle.wait(timeout=900)
message = handle.send("Add a regression test.", idempotency_key="add-test")
session = handle.wait(timeout=900)
print(message.turn_id, session.turn.status)
```

`send` returns the message with the `turn_id` of the turn that answers it, and `wait` then waits on that turn. The same message key is accepted once per session. A message sent while a turn is running is answered after it. `handle.stop()` ends the running turn with `stopped`; it fails with `409` when no turn is pending or running.

## Start an agent session

Start an agent session as written:

```python
response = client.agents.start("test-repair")
session = client.sessions.handle(response.session.id).wait()
print(session.turn.status, session.turn.detail)
```

Send any field of a session start to replace the agent's value for that session:

```python
response = client.agents.start("test-repair", budget={"session": 5})
```

For an agent with an input schema, pass `input`:

```python
response = client.agents.start(
    "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

async def main():
    async with AsyncEllipsis(
        api_key=os.environ["ELLIPSIS_API_TOKEN"]
    ) as client:
        handle = await client.sessions.run(
            claude_code={
                "model": "claude-opus-5-5",
                "prompt": "Explain how to test a request validator.",
            },
            conversation={"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
turns = client.sessions.turns.list(handle.id)
for turn in turns.turns:
    print(turn.index, turn.status, turn.reason, turn.cost.total)
for message in turns.messages:
    print(message.turn_id, message.status, message.body)

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

`turns.list` returns every turn and message of a session, oldest first; `turns.get(session_id, turn_id)` returns one turn. 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 2 retries for transport errors, `429`, `502`, `503`, and `504`. Configure `timeout` and `max_retries` when creating it.

---

# Quick start

> Start your first agent session from the CLI, Python, TypeScript, or curl.

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

## Get started

Install the CLI or an SDK:

```bash title="CLI"
curl -fsSL https://ellipsis.dev/install.sh | sh
```

```bash title="Python"
pip install ellipsis-dev
```

```bash title="TypeScript"
npm install @ellipsis-dev/sdk
```

Sign in with device auth. The CLI opens your browser to approve the login:

```bash
el auth login
```

For CI, the SDKs, and curl, export an API key from **API > API keys** in the dashboard:

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

## Start an agent session

Start the `classify-change` agent:

```bash title="CLI"
el agent start classify-change --input '{"description": "Reject expired reset tokens"}'
```

```python
import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
change = {"description": "Reject expired reset tokens"}
response = client.agents.start("classify-change", input=change)
print(response.session.id)
```

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

const apiKey = process.env.ELLIPSIS_API_TOKEN!;
const client = new Ellipsis({ apiKey });
const input = { description: 'Reject expired reset tokens' };
const { session } = await client.agents.start('classify-change', { input });
console.log(session.id);
```

```bash title="cURL"
curl https://api.ellipsis.dev/v1/agents/classify-change/sessions -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" -H "Content-Type: application/json" -d '{"input": {"description": "Reject expired reset tokens"}}'
```

[Typed input and output](/docs/agents/schema#typed-input-and-output) defines it. An agent with no input schema takes `prompt` instead of `input`.

Wait for it to finish:

```bash title="CLI"
el session get <session-id> --watch
```

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

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

```bash title="cURL"
# Repeat until session.turn.status is final
curl https://api.ellipsis.dev/v1/sessions/your-session-id -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

`wait` and `--watch` return when `status` is `completed`, `failed`, `stopped`, or `cancelled`. `--watch` exits `0` only for `completed`.

Read the output:

```python
print(client.sessions.get("your-session-id").session.output.result)
```

```typescript
console.log((await client.sessions.get('your-session-id')).session.output?.result);
```

```bash title="cURL"
curl https://api.ellipsis.dev/v1/sessions/your-session-id -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" | jq .session.output.result
```

It matches the agent's `output.json_schema` and is `null` until the turn ends:

```json
{
  "category": "bugfix",
  "reason": "Rejecting expired reset tokens closes a validation gap."
}
```

## Errors and retries

- Errors return `{"error": {"code": "...", "message": "..."}}`. Branch on `code`, not `message`.
- Retry `429` after `Retry-After`, and `5xx` with backoff.
- A start that times out can still succeed. Tag sessions with `metadata` and list recent sessions before you retry.

## Pagination

- Paginated routes take `limit` and `cursor`.
- Pass `next_cursor` until `has_more` is `false`.
- SDK iterators fetch every page.

---

# 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-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 a message's receipt through environment preparation to the end of its turn.

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): message, environment, turn, and conversation 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 how the conversation and its turns report progress, and how to know when your message is answered, start with [Lifecycle](/docs/sessions/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.                                            |
| `turn_id`              | Correlate records with the turn they belong to; environment records carry the turn they prepare for.                 |
| `session_message_id`   | Correlate message 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. Every record that belongs to a turn carries its `turn_id`; environment records carry the turn they prepare for. Older sessions can contain platform record types that are no longer produced; they arrive as [unknown records](#unknown-records).

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

### message_received

A message entered the session and its turn was created; `turn_id` is the turn that will answer it, and `closes_session` marks a final message.

Use `session_message_id` to match the message with its native user echo so it renders once. The message is answered when its turn reaches a final status; see [Lifecycle](/docs/sessions/lifecycle#wait-for-the-answer).

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "message_received",
  "id": "record_example",
  "session_id": "session_example",
  "turn_id": "turn_example",
  "session_message_id": "message_example",
  "feed_seq": 1,
  "payload": {
    "message_id": "message_example",
    "turn_id": "turn_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 |  |
| `payload.turn_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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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="environment_phase"></a>

### environment_phase

A phase of environment preparation started, completed, or failed, with an optional `step`, timing, and details.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "environment_phase",
  "id": "record_example",
  "session_id": "session_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 2,
  "payload": {
    "phase": "setup",
    "status": "completed",
    "step": "after_checkout",
    "duration_ms": 2400,
    "detail": null
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:03Z"
}
```

**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 "environment_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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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="environment_output"></a>

### environment_output

A chunk of output from environment preparation, including your hooks; many arrive per turn, and `chunk` orders them within a step.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "environment_output",
  "id": "record_example",
  "session_id": "session_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 3,
  "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:01Z"
}
```

**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 "environment_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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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="environment_ready"></a>

### environment_ready

The environment is prepared for the listed repositories and the agent is about to start.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "environment_ready",
  "id": "record_example",
  "session_id": "session_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 4,
  "payload": {
    "repositories": ["your-org/api-repo"],
    "duration_ms": 8400
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:08Z"
}
```

**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 "environment_ready". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.duration_ms` | `integer \| null` | Optional |  |
| `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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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_queued"></a>

### turn_queued

The turn waits because your account already has `limit` sessions alive. It starts when one of them ends.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "turn_queued",
  "id": "record_example",
  "session_id": "session_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 2,
  "payload": {
    "turn_id": "turn_example",
    "sessions_alive": 32,
    "limit": 32
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:01Z"
}
```

**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_queued". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.limit` | `integer` | Required |  |
| `payload.sessions_alive` | `integer` | 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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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

The agent started on the turn's message; the turn is now `running`.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "turn_started",
  "id": "record_example",
  "session_id": "session_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 5,
  "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:09Z"
}
```

**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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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

The agent started on the message, on 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",
  "turn_id": "turn_example",
  "session_message_id": "message_example",
  "feed_seq": 6,
  "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:09Z"
}
```

**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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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_ended"></a>

### turn_ended

The turn reached its final status; `status`, `reason`, and `detail` match the turn on the session object.

**Example JSON**

```json
{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "turn_ended",
  "id": "record_example",
  "session_id": "session_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 7,
  "payload": {
    "turn_id": "turn_example",
    "turn_index": 0,
    "status": "completed",
    "reason": null,
    "detail": null,
    "duration_ms": 4200
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:13Z"
}
```

**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_ended". |
| `payload` | `object` | Required | Additional properties are allowed. |
| `payload.detail` | `string \| null` | Optional |  |
| `payload.duration_ms` | `integer \| null` | Optional |  |
| `payload.reason` | `string \| null` | Optional |  |
| `payload.status` | `string` | Required |  |
| `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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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

The turn ended before answering the message, so the message was queued again with a new queued turn, `requeued_turn_id`.

**Example JSON**

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

**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.requeued_turn_id` | `string \| null` | Optional |  |
| `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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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 the turn of a session that runs once or after a closing message's turn.

**Example JSON**

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

**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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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. |

`environment_phase.phase` names a stage of preparation: `image` (the base image), `clone` (the repositories), `setup` (the environment's `build_base` and `after_checkout` hooks, named in `step`), `snapshot` (saving the prepared environment for reuse), `restore` (bringing a saved environment back for a later turn), and `hooks` (the `before_start` hook, which runs each time an environment is prepared, before the agent starts). `status` is `started`, `completed`, or `failed`. Phases, steps, and statuses are open vocabularies, so render values you don't recognize as they are. `environment_output` carries the same `phase` and `step`; a `clone` chunk names the repository in `step`. A reused environment skips its build steps.

A turn's `status`, `reason`, and `detail` also arrive on the [`session` frame](#session); `turn_ended` is the record of the same change. There are no separate session-level success, failure, or stop records: the conversation reports only `session_closed`.

## 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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "payload": {
    "type": "system",
    "subtype": "init",
    "model": "claude-opus-5-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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "payload": {
    "type": "assistant",
    "message": {
      "type": "message",
      "role": "assistant",
      "id": "message_native",
      "model": "claude-opus-5-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-opus-5-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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": null,
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "payload": {
    "method": "thread/started",
    "params": {
      "thread": {
        "id": "thread_example",
        "cliVersion": "0.161.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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": null,
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": null,
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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_ended`](#turn_ended) record. 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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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/{id}/stream?protocol=7`; 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",
    "conversation": {
      "state": "open",
      "interactive": true,
      "warm": true,
      "prompting": {
        "enabled": true,
        "blocked_reason": null,
        "detail": null,
        "surface_name": null
      }
    },
    "turn": {
      "id": "turn_example",
      "index": 0,
      "status": "running",
      "reason": null,
      "detail": null,
      "stopped": null,
      "created_at": "2026-09-10T14:00:00Z",
      "started_at": "2026-09-10T14:00:09Z",
      "ended_at": null,
      "cost": {
        "llm": {
          "all": {
            "platform": 0,
            "claude_subscription": 0,
            "codex_subscription": 0,
            "total": 0
          },
          "by_model": []
        },
        "cpu": 0,
        "memory": 0,
        "fee": 0,
        "charged": 0,
        "total": 0
      },
      "tokens": {
        "all": {
          "input": 0,
          "output": 0,
          "cache_read": 0,
          "cache_creation": 0,
          "total": 0
        },
        "by_model": []
      }
    },
    "archived": null,
    "created_at": "2026-09-10T14:00:00Z",
    "updated_at": "2026-09-10T14:00:09Z",
    "source": "api",
    "event": null,
    "cost": {
      "llm": {
        "all": {
          "platform": 0,
          "claude_subscription": 0,
          "codex_subscription": 0,
          "total": 0
        },
        "by_model": []
      },
      "cpu": 0,
      "memory": 0,
      "fee": 0,
      "charged": 0,
      "total": 0
    },
    "tokens": {
      "all": {
        "input": 0,
        "output": 0,
        "cache_read": 0,
        "cache_creation": 0,
        "total": 0
      },
      "by_model": []
    },
    "parent": null,
    "attribution": {
      "type": "api_key",
      "id": "key_example",
      "user": null
    },
    "budget": 300000,
    "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,
    "claude_code": {
      "model": "claude-opus-5-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.[].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". |
| `messages.[].turn_id` | `string \| null` | Required | The turn created to answer this message. Wait on it: the message is answered when that turn reaches a final status. |
| `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", "code_review", "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 | The most the agent may spend over the last day, in US dollars. |
| `session.agent.config.session.budget.month` | `number \| null` | Required | The most the agent may spend over the last 28 days, in US dollars. |
| `session.agent.config.session.budget.session` | `number \| null` | Required | The most one session may spend, in US dollars. Greater than: 0. |
| `session.agent.config.session.budget.week` | `number \| null` | Required | The most the agent may spend over the last 7 days, in US dollars. |
| `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` | Required | The model the session runs on: an alias or canonical id from the models table. Required. |
| `session.agent.config.session.claude_code.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message. |
| `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 | The model the session runs on: a Responses-capable id from the models table. Required. |
| `session.agent.config.session.codex.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message. |
| `session.agent.config.session.conversation` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.conversation.interactive` | `boolean` | Required | Whether the session stays open after its first turn. Defaults to true; false runs once and requires a prompt. Requires the model's interactive capability when true. Direct message acceptance is reported separately in conversation.prompting. |
| `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 environment. Skipped when that prepared environment 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 the workspace directory `/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 environment 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 the workspace directory `/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 the workspace directory `/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 the workspace directory `/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.metadata` | `object` | Required | Arbitrary string key/value metadata stored on every session. Additional properties are allowed. |
| `session.agent.config.session.metadata.[key]` | `string` |  |  |
| `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", "configs", "defaults", "environments", "secrets", "templates", "integrations", "reviews", "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".enabled` | `boolean` | Required |  |
| `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".check_run` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".check_run.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".check_run.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.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".check_run.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.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".check_run.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.names` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.names.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.on.[]` | `string` |  | Allowed values: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale". |
| `session.agent.config.trigger.type = "react".check_run.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.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".check_run.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".check_suite.apps` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.apps.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".check_suite.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.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".check_suite.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.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".check_suite.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.on.[]` | `string` |  | Allowed values: "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure". |
| `session.agent.config.trigger.type = "react".check_suite.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.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".check_suite.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".enabled` | `boolean` | Required |  |
| `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.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.for.teams.[]` | `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.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.teams.[]` | `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.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.for.teams.[]` | `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.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.for.teams.[]` | `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".release` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".release.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".release.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.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".release.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.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".release.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.on.[]` | `string` |  | Allowed values: "published". |
| `session.agent.config.trigger.type = "react".release.prerelease` | `boolean \| null` | Required |  |
| `session.agent.config.trigger.type = "react".release.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.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".release.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.tag` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.tag.[]` | `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.config.trigger.type = "react".status` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".status.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".status.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.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".status.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.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".status.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.names` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.names.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.on.[]` | `string` |  | Allowed values: "pending", "passed", "failed", "errored". |
| `session.agent.config.trigger.type = "react".status.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.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".status.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".workflow_run.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.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".workflow_run.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.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".workflow_run.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.names` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.names.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.on.[]` | `string` |  | Allowed values: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure". |
| `session.agent.config.trigger.type = "react".workflow_run.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.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".workflow_run.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.id` | `string \| null` | Required | Identifier of the saved agent this session's snapshot was taken from. Null for a routing-file 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.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.archived.at` | `string` | Required | When the session was archived. Format: date-time. |
| `session.archived.by` | `object \| null` | Required | The GitHub user who archived the session; null if unknown or unavailable. Additional properties are allowed. |
| `session.archived.by.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.archived.by.avatar_url` | `string` | Required |  |
| `session.archived.by.id` | `integer` | Required |  |
| `session.archived.by.login` | `string` | Required |  |
| `session.archived.by.name` | `string \| null` | Required |  |
| `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.attribution.user.name` | `string \| null` | Required |  |
| `session.budget` | `integer` | Required | The spend budget enforced for this session, in millicents, 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` | Required | The model the session runs on: an alias or canonical id from the models table. Required. |
| `session.claude_code.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message. |
| `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 | The model the session runs on: a Responses-capable id from the models table. Required. |
| `session.codex.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message. |
| `session.conversation` | `object` | Required | Whether the session can take more messages, and whether an agent is warm to answer one. Additional properties are allowed. |
| `session.conversation.interactive` | `boolean` | Required | Whether the session stays open after its first turn. |
| `session.conversation.prompting` | `object` | Required | The session's policy for direct messages. Caller authorization and message validation are checked separately. Additional properties are allowed. |
| `session.conversation.prompting.blocked_reason` | `string \| null` | Required | Allowed values: "mention_surface", "non_interactive", "harness_single_turn", "budget_exhausted", "closed". |
| `session.conversation.prompting.detail` | `string \| null` | Required |  |
| `session.conversation.prompting.enabled` | `boolean` | Required |  |
| `session.conversation.prompting.surface_name` | `string \| null` | Required |  |
| `session.conversation.state` | `string` | Required | `open` while the session can take messages; `closed` is permanent. Allowed values: "open", "closed". |
| `session.conversation.warm` | `boolean` | Required | Whether an agent is ready to answer the next message right away. When false, the next message first prepares an environment, which takes longer. A hint only; clients need no logic on it. |
| `session.cost` | `object` | Required | What the session has cost so far. Additional properties are allowed. |
| `session.cost.charged` | `integer` | Required | What Ellipsis charged to credit, in millicents. It is everything except subscription tokens, and it is what the budget caps. |
| `session.cost.cpu` | `integer` | Required | CPU spend in millicents. |
| `session.cost.fee` | `integer` | Required | Platform fee in millicents. |
| `session.cost.llm` | `object` | Required | LLM token cost, in total and by model, split by who paid. Additional properties are allowed. |
| `session.cost.llm.all` | `object` | Required | Token cost across every model. Additional properties are allowed. |
| `session.cost.llm.all.claude_subscription` | `integer` | Required | Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. |
| `session.cost.llm.all.codex_subscription` | `integer` | Required | Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. |
| `session.cost.llm.all.platform` | `integer` | Required | Token cost charged to Ellipsis credit, in millicents. |
| `session.cost.llm.all.total` | `integer` | Required | All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. |
| `session.cost.llm.by_model` | `array<object>` | Required | Token cost for each model that used tokens. |
| `session.cost.llm.by_model.[]` | `object` |  | Additional properties are allowed. |
| `session.cost.llm.by_model.[].claude_subscription` | `integer` | Required | Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. |
| `session.cost.llm.by_model.[].codex_subscription` | `integer` | Required | Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. |
| `session.cost.llm.by_model.[].model` | `string` | Required | The model that used these tokens. |
| `session.cost.llm.by_model.[].platform` | `integer` | Required | Token cost charged to Ellipsis credit, in millicents. |
| `session.cost.llm.by_model.[].total` | `integer` | Required | All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. |
| `session.cost.memory` | `integer` | Required | Memory spend in millicents. |
| `session.cost.total` | `integer` | Required | Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee. |
| `session.created_at` | `string` | Required | When the session was created. Format: date-time. |
| `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 environment. Skipped when that prepared environment 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 the workspace directory `/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 environment 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 the workspace directory `/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 the workspace directory `/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 the workspace directory `/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 environment. |
| `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 = "github.check_run"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.check_run".type` | `string` | Required | Must be "github.check_run". |
| `session.event.type = "github.check_run".action` | `string` | Required | Allowed values: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale". |
| `session.event.type = "github.check_run".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.check_run".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.check_run".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.check_run".actor.name` | `string` | Required |  |
| `session.event.type = "github.check_run".branch` | `string \| null` | Required |  |
| `session.event.type = "github.check_run".conclusion` | `string \| null` | Required |  |
| `session.event.type = "github.check_run".head_sha` | `string` | Required |  |
| `session.event.type = "github.check_run".name` | `string` | Required |  |
| `session.event.type = "github.check_run".pull_request_number` | `integer \| null` | Required |  |
| `session.event.type = "github.check_run".repository` | `string` | Required |  |
| `session.event.type = "github.check_run".url` | `string` | Required |  |
| `session.event.type = "github.check_suite"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.check_suite".type` | `string` | Required | Must be "github.check_suite". |
| `session.event.type = "github.check_suite".action` | `string` | Required | Allowed values: "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure". |
| `session.event.type = "github.check_suite".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.check_suite".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.check_suite".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.check_suite".actor.name` | `string` | Required |  |
| `session.event.type = "github.check_suite".app` | `string \| null` | Required |  |
| `session.event.type = "github.check_suite".branch` | `string \| null` | Required |  |
| `session.event.type = "github.check_suite".conclusion` | `string \| null` | Required |  |
| `session.event.type = "github.check_suite".head_sha` | `string` | Required |  |
| `session.event.type = "github.check_suite".pull_request_number` | `integer \| null` | Required |  |
| `session.event.type = "github.check_suite".repository` | `string` | Required |  |
| `session.event.type = "github.check_suite".url` | `string` | Required |  |
| `session.event.type = "github.workflow_run"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.workflow_run".type` | `string` | Required | Must be "github.workflow_run". |
| `session.event.type = "github.workflow_run".action` | `string` | Required | Allowed values: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure". |
| `session.event.type = "github.workflow_run".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.workflow_run".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.workflow_run".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.workflow_run".actor.name` | `string` | Required |  |
| `session.event.type = "github.workflow_run".branch` | `string \| null` | Required |  |
| `session.event.type = "github.workflow_run".conclusion` | `string \| null` | Required |  |
| `session.event.type = "github.workflow_run".head_sha` | `string` | Required |  |
| `session.event.type = "github.workflow_run".name` | `string` | Required |  |
| `session.event.type = "github.workflow_run".pull_request_number` | `integer \| null` | Required |  |
| `session.event.type = "github.workflow_run".repository` | `string` | Required |  |
| `session.event.type = "github.workflow_run".run_number` | `integer` | Required |  |
| `session.event.type = "github.workflow_run".url` | `string` | Required |  |
| `session.event.type = "github.status"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.status".type` | `string` | Required | Must be "github.status". |
| `session.event.type = "github.status".action` | `string` | Required | Allowed values: "pending", "passed", "failed", "errored". |
| `session.event.type = "github.status".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.status".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.status".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.status".actor.name` | `string` | Required |  |
| `session.event.type = "github.status".branch` | `string \| null` | Required |  |
| `session.event.type = "github.status".context` | `string` | Required |  |
| `session.event.type = "github.status".head_sha` | `string` | Required |  |
| `session.event.type = "github.status".pull_request_number` | `integer \| null` | Required |  |
| `session.event.type = "github.status".repository` | `string` | Required |  |
| `session.event.type = "github.status".state` | `string` | Required |  |
| `session.event.type = "github.status".url` | `string` | Required |  |
| `session.event.type = "github.release"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.release".type` | `string` | Required | Must be "github.release". |
| `session.event.type = "github.release".action` | `string` | Required | Allowed values: "published". |
| `session.event.type = "github.release".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.release".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.release".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.release".actor.name` | `string` | Required |  |
| `session.event.type = "github.release".name` | `string \| null` | Required |  |
| `session.event.type = "github.release".prerelease` | `boolean` | Required |  |
| `session.event.type = "github.release".repository` | `string` | Required |  |
| `session.event.type = "github.release".tag` | `string` | Required |  |
| `session.event.type = "github.release".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` |  | Allowed values: "commented", "delegated". |
| `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.metadata` | `object` | Required | Caller-supplied metadata key-value pairs. Additional properties are allowed. |
| `session.metadata.[key]` | `string` |  |  |
| `session.output` | `object \| null` | Required | The session's structured output: the `json_schema` the agent must satisfy and, once a turn has submitted it, the `result`. Additional properties are allowed. |
| `session.output.json_schema` | `object` | Required | JSON Schema the agent's result must satisfy. Additional properties are allowed. |
| `session.output.result` | `object \| null` | Required | The payload the agent submitted, or null until a turn submits one. 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", "configs", "defaults", "environments", "secrets", "templates", "integrations", "reviews", "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 doing. |
| `session.tokens` | `object` | Required | The tokens the session has used so far. Additional properties are allowed. |
| `session.tokens.all` | `object` | Required | Token counts across every model. Additional properties are allowed. |
| `session.tokens.all.cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.tokens.all.cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.tokens.all.input` | `integer` | Required | Input tokens used. |
| `session.tokens.all.output` | `integer` | Required | Output tokens used. |
| `session.tokens.all.total` | `integer` | Required | All tokens used, including prompt cache reads and writes. Token cost is priced on this. |
| `session.tokens.by_model` | `array<object>` | Required | Token counts for each model that used tokens. |
| `session.tokens.by_model.[]` | `object` |  | Additional properties are allowed. |
| `session.tokens.by_model.[].cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.tokens.by_model.[].cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.tokens.by_model.[].input` | `integer` | Required | Input tokens used. |
| `session.tokens.by_model.[].model` | `string` | Required | The model that used these tokens. |
| `session.tokens.by_model.[].output` | `integer` | Required | Output tokens used. |
| `session.tokens.by_model.[].total` | `integer` | Required | All tokens used, including prompt cache reads and writes. Token cost is priced on this. |
| `session.turn` | `object \| null` | Required | The turn in progress, or the latest one when none is running. Null until the session has a message. Wait on it: the message you sent is answered when the turn with your message's `turn_id` reaches a final status. Additional properties are allowed. |
| `session.turn.cost` | `object` | Required | What the turn cost so far, in millicents, broken down by leg. Additional properties are allowed. |
| `session.turn.cost.charged` | `integer` | Required | What Ellipsis charged to credit, in millicents. It is everything except subscription tokens, and it is what the budget caps. |
| `session.turn.cost.cpu` | `integer` | Required | CPU spend in millicents. |
| `session.turn.cost.fee` | `integer` | Required | Platform fee in millicents. |
| `session.turn.cost.llm` | `object` | Required | LLM token cost, in total and by model, split by who paid. Additional properties are allowed. |
| `session.turn.cost.llm.all` | `object` | Required | Token cost across every model. Additional properties are allowed. |
| `session.turn.cost.llm.all.claude_subscription` | `integer` | Required | Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. |
| `session.turn.cost.llm.all.codex_subscription` | `integer` | Required | Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. |
| `session.turn.cost.llm.all.platform` | `integer` | Required | Token cost charged to Ellipsis credit, in millicents. |
| `session.turn.cost.llm.all.total` | `integer` | Required | All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. |
| `session.turn.cost.llm.by_model` | `array<object>` | Required | Token cost for each model that used tokens. |
| `session.turn.cost.llm.by_model.[]` | `object` |  | Additional properties are allowed. |
| `session.turn.cost.llm.by_model.[].claude_subscription` | `integer` | Required | Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. |
| `session.turn.cost.llm.by_model.[].codex_subscription` | `integer` | Required | Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. |
| `session.turn.cost.llm.by_model.[].model` | `string` | Required | The model that used these tokens. |
| `session.turn.cost.llm.by_model.[].platform` | `integer` | Required | Token cost charged to Ellipsis credit, in millicents. |
| `session.turn.cost.llm.by_model.[].total` | `integer` | Required | All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. |
| `session.turn.cost.memory` | `integer` | Required | Memory spend in millicents. |
| `session.turn.cost.total` | `integer` | Required | Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee. |
| `session.turn.created_at` | `string` | Required | When the turn's message was received. Format: date-time. |
| `session.turn.detail` | `string \| null` | Required | A human-readable explanation of a failed, stopped, or cancelled turn, or of why a queued turn waits. |
| `session.turn.ended_at` | `string \| null` | Required | When the turn reached its final status. Format: date-time. |
| `session.turn.id` | `string` | Required | Unique identifier of the turn. |
| `session.turn.index` | `integer` | Required | Position in the session, starting at 0. |
| `session.turn.reason` | `string \| null` | Required | Why the turn failed or was cancelled; null on every other status. Allowed values: "error", "tool_call_failed", "budget_hit", "payment_required", "blocked", "contact_email_required", "lifecycle_hook_failed", "missing_repo_access", "missing_token_permissions", "missing_environment_variables", "missing_github_integration", "agent_unavailable", "upstream_unavailable", "unsupported_configuration", "execution_disabled", "interrupted". |
| `session.turn.started_at` | `string \| null` | Required | When the agent started on the message. Format: date-time. |
| `session.turn.status` | `string` | Required | Where the turn is. Allowed values: "queued", "preparing", "running", "completed", "failed", "stopped", "cancelled". |
| `session.turn.stopped` | `object \| null` | Required | When and by whom a stop was requested; null when none was. Additional properties are allowed. |
| `session.turn.stopped.at` | `string` | Required | When a stop was requested. Format: date-time. |
| `session.turn.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.turn.stopped.by.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.turn.stopped.by.avatar_url` | `string` | Required |  |
| `session.turn.stopped.by.id` | `integer` | Required |  |
| `session.turn.stopped.by.login` | `string` | Required |  |
| `session.turn.stopped.by.name` | `string \| null` | Required |  |
| `session.turn.tokens` | `object` | Required | The tokens the turn spent and the model they went to. Additional properties are allowed. |
| `session.turn.tokens.all` | `object` | Required | Token counts across every model. Additional properties are allowed. |
| `session.turn.tokens.all.cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.turn.tokens.all.cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.turn.tokens.all.input` | `integer` | Required | Input tokens used. |
| `session.turn.tokens.all.output` | `integer` | Required | Output tokens used. |
| `session.turn.tokens.all.total` | `integer` | Required | All tokens used, including prompt cache reads and writes. Token cost is priced on this. |
| `session.turn.tokens.by_model` | `array<object>` | Required | Token counts for each model that used tokens. |
| `session.turn.tokens.by_model.[]` | `object` |  | Additional properties are allowed. |
| `session.turn.tokens.by_model.[].cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.turn.tokens.by_model.[].cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.turn.tokens.by_model.[].input` | `integer` | Required | Input tokens used. |
| `session.turn.tokens.by_model.[].model` | `string` | Required | The model that used these tokens. |
| `session.turn.tokens.by_model.[].output` | `integer` | Required | Output tokens used. |
| `session.turn.tokens.by_model.[].total` | `integer` | Required | All tokens used, including prompt cache reads and writes. Token cost is priced on this. |
| `session.updated_at` | `string` | Required | When the session was last updated. Format: date-time. |

<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",
      "turn_id": "turn_example",
      "session_message_id": null,
      "feed_seq": 12,
      "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 the turn, the conversation, and cost.

**Example JSON**

```json
{
  "type": "session",
  "session": {
    "id": "session_example",
    "conversation": {
      "state": "open",
      "interactive": true,
      "warm": true,
      "prompting": {
        "enabled": true,
        "blocked_reason": null,
        "detail": null,
        "surface_name": null
      }
    },
    "turn": {
      "id": "turn_example",
      "index": 0,
      "status": "running",
      "reason": null,
      "detail": null,
      "stopped": null,
      "created_at": "2026-09-10T14:00:00Z",
      "started_at": "2026-09-10T14:00:09Z",
      "ended_at": null,
      "cost": {
        "llm": {
          "all": {
            "platform": 0,
            "claude_subscription": 0,
            "codex_subscription": 0,
            "total": 0
          },
          "by_model": []
        },
        "cpu": 0,
        "memory": 0,
        "fee": 0,
        "charged": 0,
        "total": 0
      },
      "tokens": {
        "all": {
          "input": 0,
          "output": 0,
          "cache_read": 0,
          "cache_creation": 0,
          "total": 0
        },
        "by_model": []
      }
    },
    "archived": null,
    "created_at": "2026-09-10T14:00:00Z",
    "updated_at": "2026-09-10T14:00:12Z",
    "source": "api",
    "event": null,
    "cost": {
      "llm": {
        "all": {
          "platform": 0,
          "claude_subscription": 0,
          "codex_subscription": 0,
          "total": 0
        },
        "by_model": []
      },
      "cpu": 0,
      "memory": 0,
      "fee": 0,
      "charged": 0,
      "total": 0
    },
    "tokens": {
      "all": {
        "input": 0,
        "output": 0,
        "cache_read": 0,
        "cache_creation": 0,
        "total": 0
      },
      "by_model": []
    },
    "parent": null,
    "attribution": {
      "type": "api_key",
      "id": "key_example",
      "user": null
    },
    "budget": 300000,
    "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:12Z",
      "description": "Running the test suite."
    },
    "permissions": {
      "ellipsis": true,
      "github": {
        "permissions": null,
        "repositories": null
      }
    },
    "skills": [],
    "output": null,
    "claude_code": {
      "model": "claude-opus-5-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", "code_review", "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 | The most the agent may spend over the last day, in US dollars. |
| `session.agent.config.session.budget.month` | `number \| null` | Required | The most the agent may spend over the last 28 days, in US dollars. |
| `session.agent.config.session.budget.session` | `number \| null` | Required | The most one session may spend, in US dollars. Greater than: 0. |
| `session.agent.config.session.budget.week` | `number \| null` | Required | The most the agent may spend over the last 7 days, in US dollars. |
| `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` | Required | The model the session runs on: an alias or canonical id from the models table. Required. |
| `session.agent.config.session.claude_code.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message. |
| `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 | The model the session runs on: a Responses-capable id from the models table. Required. |
| `session.agent.config.session.codex.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message. |
| `session.agent.config.session.conversation` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.session.conversation.interactive` | `boolean` | Required | Whether the session stays open after its first turn. Defaults to true; false runs once and requires a prompt. Requires the model's interactive capability when true. Direct message acceptance is reported separately in conversation.prompting. |
| `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 environment. Skipped when that prepared environment 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 the workspace directory `/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 environment 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 the workspace directory `/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 the workspace directory `/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 the workspace directory `/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.metadata` | `object` | Required | Arbitrary string key/value metadata stored on every session. Additional properties are allowed. |
| `session.agent.config.session.metadata.[key]` | `string` |  |  |
| `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", "configs", "defaults", "environments", "secrets", "templates", "integrations", "reviews", "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".enabled` | `boolean` | Required |  |
| `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".check_run` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".check_run.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".check_run.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.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".check_run.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.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".check_run.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.names` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.names.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.on.[]` | `string` |  | Allowed values: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale". |
| `session.agent.config.trigger.type = "react".check_run.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_run.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".check_run.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_run.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".check_suite.apps` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.apps.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".check_suite.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.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".check_suite.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.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".check_suite.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.on.[]` | `string` |  | Allowed values: "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure". |
| `session.agent.config.trigger.type = "react".check_suite.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".check_suite.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".check_suite.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".check_suite.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".enabled` | `boolean` | Required |  |
| `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.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".issue.for.teams.[]` | `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.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".linear_issue.for.teams.[]` | `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.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".pull_request.for.teams.[]` | `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.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".push.for.teams.[]` | `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".release` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".release.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".release.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.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".release.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.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".release.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.on.[]` | `string` |  | Allowed values: "published". |
| `session.agent.config.trigger.type = "react".release.prerelease` | `boolean \| null` | Required |  |
| `session.agent.config.trigger.type = "react".release.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".release.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".release.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".release.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".release.tag` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".release.tag.[]` | `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.config.trigger.type = "react".status` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".status.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".status.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.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".status.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.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".status.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.names` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.names.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.on.[]` | `string` |  | Allowed values: "pending", "passed", "failed", "errored". |
| `session.agent.config.trigger.type = "react".status.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".status.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".status.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".status.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run` | `object \| null` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".workflow_run.branch` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.branch.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for` | `object` | Required | Additional properties are not allowed. |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.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".workflow_run.for.bots.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.bots.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.teams` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.teams.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users` | `object \| boolean \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.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".workflow_run.for.users.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.include` | `array<string> \| boolean` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.include.variant 1` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.include.variant 1.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 1.include.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 2` | `boolean` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 3` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.for.users.variant 3.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.names` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.names.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.on` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.on.[]` | `string` |  | Allowed values: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure". |
| `session.agent.config.trigger.type = "react".workflow_run.repositories` | `object \| array<string>` | Required | Matches at least one variant below. |
| `session.agent.config.trigger.type = "react".workflow_run.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".workflow_run.repositories.variant 1.exclude` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 1.exclude.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 1.include` | `array<string>` | Required |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 1.include.[]` | `string` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 2` | `array<string>` |  |  |
| `session.agent.config.trigger.type = "react".workflow_run.repositories.variant 2.[]` | `string` |  |  |
| `session.agent.id` | `string \| null` | Required | Identifier of the saved agent this session's snapshot was taken from. Null for a routing-file 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.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.archived.at` | `string` | Required | When the session was archived. Format: date-time. |
| `session.archived.by` | `object \| null` | Required | The GitHub user who archived the session; null if unknown or unavailable. Additional properties are allowed. |
| `session.archived.by.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.archived.by.avatar_url` | `string` | Required |  |
| `session.archived.by.id` | `integer` | Required |  |
| `session.archived.by.login` | `string` | Required |  |
| `session.archived.by.name` | `string \| null` | Required |  |
| `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.attribution.user.name` | `string \| null` | Required |  |
| `session.budget` | `integer` | Required | The spend budget enforced for this session, in millicents, 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` | Required | The model the session runs on: an alias or canonical id from the models table. Required. |
| `session.claude_code.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message. |
| `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 | The model the session runs on: a Responses-capable id from the models table. Required. |
| `session.codex.prompt` | `string \| null` | Required | The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message. |
| `session.conversation` | `object` | Required | Whether the session can take more messages, and whether an agent is warm to answer one. Additional properties are allowed. |
| `session.conversation.interactive` | `boolean` | Required | Whether the session stays open after its first turn. |
| `session.conversation.prompting` | `object` | Required | The session's policy for direct messages. Caller authorization and message validation are checked separately. Additional properties are allowed. |
| `session.conversation.prompting.blocked_reason` | `string \| null` | Required | Allowed values: "mention_surface", "non_interactive", "harness_single_turn", "budget_exhausted", "closed". |
| `session.conversation.prompting.detail` | `string \| null` | Required |  |
| `session.conversation.prompting.enabled` | `boolean` | Required |  |
| `session.conversation.prompting.surface_name` | `string \| null` | Required |  |
| `session.conversation.state` | `string` | Required | `open` while the session can take messages; `closed` is permanent. Allowed values: "open", "closed". |
| `session.conversation.warm` | `boolean` | Required | Whether an agent is ready to answer the next message right away. When false, the next message first prepares an environment, which takes longer. A hint only; clients need no logic on it. |
| `session.cost` | `object` | Required | What the session has cost so far. Additional properties are allowed. |
| `session.cost.charged` | `integer` | Required | What Ellipsis charged to credit, in millicents. It is everything except subscription tokens, and it is what the budget caps. |
| `session.cost.cpu` | `integer` | Required | CPU spend in millicents. |
| `session.cost.fee` | `integer` | Required | Platform fee in millicents. |
| `session.cost.llm` | `object` | Required | LLM token cost, in total and by model, split by who paid. Additional properties are allowed. |
| `session.cost.llm.all` | `object` | Required | Token cost across every model. Additional properties are allowed. |
| `session.cost.llm.all.claude_subscription` | `integer` | Required | Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. |
| `session.cost.llm.all.codex_subscription` | `integer` | Required | Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. |
| `session.cost.llm.all.platform` | `integer` | Required | Token cost charged to Ellipsis credit, in millicents. |
| `session.cost.llm.all.total` | `integer` | Required | All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. |
| `session.cost.llm.by_model` | `array<object>` | Required | Token cost for each model that used tokens. |
| `session.cost.llm.by_model.[]` | `object` |  | Additional properties are allowed. |
| `session.cost.llm.by_model.[].claude_subscription` | `integer` | Required | Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. |
| `session.cost.llm.by_model.[].codex_subscription` | `integer` | Required | Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. |
| `session.cost.llm.by_model.[].model` | `string` | Required | The model that used these tokens. |
| `session.cost.llm.by_model.[].platform` | `integer` | Required | Token cost charged to Ellipsis credit, in millicents. |
| `session.cost.llm.by_model.[].total` | `integer` | Required | All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. |
| `session.cost.memory` | `integer` | Required | Memory spend in millicents. |
| `session.cost.total` | `integer` | Required | Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee. |
| `session.created_at` | `string` | Required | When the session was created. Format: date-time. |
| `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 environment. Skipped when that prepared environment 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 the workspace directory `/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 environment 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 the workspace directory `/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 the workspace directory `/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 the workspace directory `/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 environment. |
| `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 = "github.check_run"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.check_run".type` | `string` | Required | Must be "github.check_run". |
| `session.event.type = "github.check_run".action` | `string` | Required | Allowed values: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale". |
| `session.event.type = "github.check_run".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.check_run".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.check_run".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.check_run".actor.name` | `string` | Required |  |
| `session.event.type = "github.check_run".branch` | `string \| null` | Required |  |
| `session.event.type = "github.check_run".conclusion` | `string \| null` | Required |  |
| `session.event.type = "github.check_run".head_sha` | `string` | Required |  |
| `session.event.type = "github.check_run".name` | `string` | Required |  |
| `session.event.type = "github.check_run".pull_request_number` | `integer \| null` | Required |  |
| `session.event.type = "github.check_run".repository` | `string` | Required |  |
| `session.event.type = "github.check_run".url` | `string` | Required |  |
| `session.event.type = "github.check_suite"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.check_suite".type` | `string` | Required | Must be "github.check_suite". |
| `session.event.type = "github.check_suite".action` | `string` | Required | Allowed values: "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure". |
| `session.event.type = "github.check_suite".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.check_suite".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.check_suite".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.check_suite".actor.name` | `string` | Required |  |
| `session.event.type = "github.check_suite".app` | `string \| null` | Required |  |
| `session.event.type = "github.check_suite".branch` | `string \| null` | Required |  |
| `session.event.type = "github.check_suite".conclusion` | `string \| null` | Required |  |
| `session.event.type = "github.check_suite".head_sha` | `string` | Required |  |
| `session.event.type = "github.check_suite".pull_request_number` | `integer \| null` | Required |  |
| `session.event.type = "github.check_suite".repository` | `string` | Required |  |
| `session.event.type = "github.check_suite".url` | `string` | Required |  |
| `session.event.type = "github.workflow_run"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.workflow_run".type` | `string` | Required | Must be "github.workflow_run". |
| `session.event.type = "github.workflow_run".action` | `string` | Required | Allowed values: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure". |
| `session.event.type = "github.workflow_run".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.workflow_run".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.workflow_run".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.workflow_run".actor.name` | `string` | Required |  |
| `session.event.type = "github.workflow_run".branch` | `string \| null` | Required |  |
| `session.event.type = "github.workflow_run".conclusion` | `string \| null` | Required |  |
| `session.event.type = "github.workflow_run".head_sha` | `string` | Required |  |
| `session.event.type = "github.workflow_run".name` | `string` | Required |  |
| `session.event.type = "github.workflow_run".pull_request_number` | `integer \| null` | Required |  |
| `session.event.type = "github.workflow_run".repository` | `string` | Required |  |
| `session.event.type = "github.workflow_run".run_number` | `integer` | Required |  |
| `session.event.type = "github.workflow_run".url` | `string` | Required |  |
| `session.event.type = "github.status"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.status".type` | `string` | Required | Must be "github.status". |
| `session.event.type = "github.status".action` | `string` | Required | Allowed values: "pending", "passed", "failed", "errored". |
| `session.event.type = "github.status".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.status".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.status".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.status".actor.name` | `string` | Required |  |
| `session.event.type = "github.status".branch` | `string \| null` | Required |  |
| `session.event.type = "github.status".context` | `string` | Required |  |
| `session.event.type = "github.status".head_sha` | `string` | Required |  |
| `session.event.type = "github.status".pull_request_number` | `integer \| null` | Required |  |
| `session.event.type = "github.status".repository` | `string` | Required |  |
| `session.event.type = "github.status".state` | `string` | Required |  |
| `session.event.type = "github.status".url` | `string` | Required |  |
| `session.event.type = "github.release"` | `object` |  | Additional properties are allowed. |
| `session.event.type = "github.release".type` | `string` | Required | Must be "github.release". |
| `session.event.type = "github.release".action` | `string` | Required | Allowed values: "published". |
| `session.event.type = "github.release".actor` | `object \| null` | Required | Additional properties are allowed. |
| `session.event.type = "github.release".actor.avatar_url` | `string \| null` | Required |  |
| `session.event.type = "github.release".actor.is_bot` | `boolean \| null` | Required |  |
| `session.event.type = "github.release".actor.name` | `string` | Required |  |
| `session.event.type = "github.release".name` | `string \| null` | Required |  |
| `session.event.type = "github.release".prerelease` | `boolean` | Required |  |
| `session.event.type = "github.release".repository` | `string` | Required |  |
| `session.event.type = "github.release".tag` | `string` | Required |  |
| `session.event.type = "github.release".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` |  | Allowed values: "commented", "delegated". |
| `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.metadata` | `object` | Required | Caller-supplied metadata key-value pairs. Additional properties are allowed. |
| `session.metadata.[key]` | `string` |  |  |
| `session.output` | `object \| null` | Required | The session's structured output: the `json_schema` the agent must satisfy and, once a turn has submitted it, the `result`. Additional properties are allowed. |
| `session.output.json_schema` | `object` | Required | JSON Schema the agent's result must satisfy. Additional properties are allowed. |
| `session.output.result` | `object \| null` | Required | The payload the agent submitted, or null until a turn submits one. 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", "configs", "defaults", "environments", "secrets", "templates", "integrations", "reviews", "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 doing. |
| `session.tokens` | `object` | Required | The tokens the session has used so far. Additional properties are allowed. |
| `session.tokens.all` | `object` | Required | Token counts across every model. Additional properties are allowed. |
| `session.tokens.all.cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.tokens.all.cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.tokens.all.input` | `integer` | Required | Input tokens used. |
| `session.tokens.all.output` | `integer` | Required | Output tokens used. |
| `session.tokens.all.total` | `integer` | Required | All tokens used, including prompt cache reads and writes. Token cost is priced on this. |
| `session.tokens.by_model` | `array<object>` | Required | Token counts for each model that used tokens. |
| `session.tokens.by_model.[]` | `object` |  | Additional properties are allowed. |
| `session.tokens.by_model.[].cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.tokens.by_model.[].cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.tokens.by_model.[].input` | `integer` | Required | Input tokens used. |
| `session.tokens.by_model.[].model` | `string` | Required | The model that used these tokens. |
| `session.tokens.by_model.[].output` | `integer` | Required | Output tokens used. |
| `session.tokens.by_model.[].total` | `integer` | Required | All tokens used, including prompt cache reads and writes. Token cost is priced on this. |
| `session.turn` | `object \| null` | Required | The turn in progress, or the latest one when none is running. Null until the session has a message. Wait on it: the message you sent is answered when the turn with your message's `turn_id` reaches a final status. Additional properties are allowed. |
| `session.turn.cost` | `object` | Required | What the turn cost so far, in millicents, broken down by leg. Additional properties are allowed. |
| `session.turn.cost.charged` | `integer` | Required | What Ellipsis charged to credit, in millicents. It is everything except subscription tokens, and it is what the budget caps. |
| `session.turn.cost.cpu` | `integer` | Required | CPU spend in millicents. |
| `session.turn.cost.fee` | `integer` | Required | Platform fee in millicents. |
| `session.turn.cost.llm` | `object` | Required | LLM token cost, in total and by model, split by who paid. Additional properties are allowed. |
| `session.turn.cost.llm.all` | `object` | Required | Token cost across every model. Additional properties are allowed. |
| `session.turn.cost.llm.all.claude_subscription` | `integer` | Required | Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. |
| `session.turn.cost.llm.all.codex_subscription` | `integer` | Required | Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. |
| `session.turn.cost.llm.all.platform` | `integer` | Required | Token cost charged to Ellipsis credit, in millicents. |
| `session.turn.cost.llm.all.total` | `integer` | Required | All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. |
| `session.turn.cost.llm.by_model` | `array<object>` | Required | Token cost for each model that used tokens. |
| `session.turn.cost.llm.by_model.[]` | `object` |  | Additional properties are allowed. |
| `session.turn.cost.llm.by_model.[].claude_subscription` | `integer` | Required | Token cost paid by a Claude subscription, at Ellipsis rates, in millicents. |
| `session.turn.cost.llm.by_model.[].codex_subscription` | `integer` | Required | Token cost paid by a Codex subscription, at Ellipsis rates, in millicents. |
| `session.turn.cost.llm.by_model.[].model` | `string` | Required | The model that used these tokens. |
| `session.turn.cost.llm.by_model.[].platform` | `integer` | Required | Token cost charged to Ellipsis credit, in millicents. |
| `session.turn.cost.llm.by_model.[].total` | `integer` | Required | All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription. |
| `session.turn.cost.memory` | `integer` | Required | Memory spend in millicents. |
| `session.turn.cost.total` | `integer` | Required | Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee. |
| `session.turn.created_at` | `string` | Required | When the turn's message was received. Format: date-time. |
| `session.turn.detail` | `string \| null` | Required | A human-readable explanation of a failed, stopped, or cancelled turn, or of why a queued turn waits. |
| `session.turn.ended_at` | `string \| null` | Required | When the turn reached its final status. Format: date-time. |
| `session.turn.id` | `string` | Required | Unique identifier of the turn. |
| `session.turn.index` | `integer` | Required | Position in the session, starting at 0. |
| `session.turn.reason` | `string \| null` | Required | Why the turn failed or was cancelled; null on every other status. Allowed values: "error", "tool_call_failed", "budget_hit", "payment_required", "blocked", "contact_email_required", "lifecycle_hook_failed", "missing_repo_access", "missing_token_permissions", "missing_environment_variables", "missing_github_integration", "agent_unavailable", "upstream_unavailable", "unsupported_configuration", "execution_disabled", "interrupted". |
| `session.turn.started_at` | `string \| null` | Required | When the agent started on the message. Format: date-time. |
| `session.turn.status` | `string` | Required | Where the turn is. Allowed values: "queued", "preparing", "running", "completed", "failed", "stopped", "cancelled". |
| `session.turn.stopped` | `object \| null` | Required | When and by whom a stop was requested; null when none was. Additional properties are allowed. |
| `session.turn.stopped.at` | `string` | Required | When a stop was requested. Format: date-time. |
| `session.turn.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.turn.stopped.by.type` | `string` | Required | Allowed values: "User", "Organization", "Bot", "Mannequin". |
| `session.turn.stopped.by.avatar_url` | `string` | Required |  |
| `session.turn.stopped.by.id` | `integer` | Required |  |
| `session.turn.stopped.by.login` | `string` | Required |  |
| `session.turn.stopped.by.name` | `string \| null` | Required |  |
| `session.turn.tokens` | `object` | Required | The tokens the turn spent and the model they went to. Additional properties are allowed. |
| `session.turn.tokens.all` | `object` | Required | Token counts across every model. Additional properties are allowed. |
| `session.turn.tokens.all.cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.turn.tokens.all.cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.turn.tokens.all.input` | `integer` | Required | Input tokens used. |
| `session.turn.tokens.all.output` | `integer` | Required | Output tokens used. |
| `session.turn.tokens.all.total` | `integer` | Required | All tokens used, including prompt cache reads and writes. Token cost is priced on this. |
| `session.turn.tokens.by_model` | `array<object>` | Required | Token counts for each model that used tokens. |
| `session.turn.tokens.by_model.[]` | `object` |  | Additional properties are allowed. |
| `session.turn.tokens.by_model.[].cache_creation` | `integer` | Required | Tokens written to the prompt cache. |
| `session.turn.tokens.by_model.[].cache_read` | `integer` | Required | Tokens read from the prompt cache. |
| `session.turn.tokens.by_model.[].input` | `integer` | Required | Input tokens used. |
| `session.turn.tokens.by_model.[].model` | `string` | Required | The model that used these tokens. |
| `session.turn.tokens.by_model.[].output` | `integer` | Required | Output tokens used. |
| `session.turn.tokens.by_model.[].total` | `integer` | Required | All tokens used, including prompt cache reads and writes. Token cost is priced on this. |
| `session.updated_at` | `string` | Required | When the session was last updated. Format: date-time. |

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

### delta

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

**Example JSON**

```json
{
  "type": "delta",
  "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. |
| `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",
  "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. |
| `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 a quiet 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 ends, 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.

An open conversation stays connected between turns without a `done` frame; `done` follows closure, not the end of each turn. The message you sent is answered when a `session` frame shows the turn with its `turn_id` at a final status; see [Lifecycle](/docs/sessions/lifecycle#wait-for-the-answer).

## Historical formats

Existing history keeps its original payload format. These examples cover compatibility when reading or replaying older sessions; new sessions 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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "payload": {
    "kind": "system",
    "subtype": "init",
    "data": {
      "model": "claude-opus-5-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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "payload": {
    "kind": "assistant",
    "model": "claude-opus-5-5",
    "content": [
      {
        "type": "text",
        "text": "All 12 tests passed."
      }
    ]
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": "claude-opus-5-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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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 error.

**Example JSON**

```json
{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "error",
  "id": "record_example",
  "session_id": "session_example",
  "turn_id": "turn_example",
  "session_message_id": null,
  "feed_seq": 12,
  "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 |  |
| `session_id` | `string` | Required | Session containing this record. |
| `session_message_id` | `string \| null` | Required | Message this record receives, delivers, requeues, or echoes. |
| `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, payloads that the current typed schema cannot interpret, and platform record types from older sessions that are no longer produced. 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 agents from TypeScript.

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

The TypeScript SDK is a client for the `/v1` API with session handles, streaming, pagination, and typed errors.

## 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: {
    model: 'claude-opus-5-5',
    prompt: 'Run the tests and report failures.',
  },
  environment: 'api-environment',
  conversation: { interactive: false },
  budget: { session: 3 },
});
const turn = await handle.wait({ timeoutMs: 900_000 });
console.log(turn?.status, turn?.reason, turn?.detail);
```

`run` returns a handle while work continues. `wait` polls until the turn that answers the prompt reaches a final status (`completed`, `failed`, `stopped`, or `cancelled`) and returns that turn, or `null` when the session has no turn to wait on. A timeout throws and leaves the session running.

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

## Continue a conversation

Leave `conversation.interactive` enabled to accept messages:

```typescript
const conversation = await client.sessions.run({
  claude_code: {
    model: 'claude-opus-5-5',
    prompt: 'Investigate the failing validation test.',
  },
  environment: 'api-environment',
  budget: { session: 5 },
});
await conversation.wait();
const { turn } = await conversation.send('Add a regression test.', {
  idempotencyKey: 'add-test',
});
const answered = await conversation.wait();
console.log(turn.id, answered?.status);
```

`send` returns the message and the turn that answers it, and `wait` then waits on that turn. The same message key is accepted once per session. A message sent while a turn is running is answered after it. `stop()` ends the running turn with `stopped`; it fails with `409` when no turn is pending or running.

## Start an agent session

Start an agent session as written:

```typescript
const { session } = await client.agents.start('test-repair');
const handle = await client.sessions.handle(session.id);
const result = await handle.wait();
console.log(result?.status, result?.detail);
```

Send any field of a session start to replace the agent's value for that session:

```typescript
await client.agents.start('test-repair', { budget: { session: 5 } });
```

For an agent with an input schema, pass `input`:

```typescript
await client.agents.start('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 turns

```typescript
const { turns, messages } = await client.sessions.turns.list(handle.id);
for (const turn of turns) {
  console.log(turn.index, turn.status, turn.reason, turn.cost.total);
}
for (const message of messages) {
  console.log(message.turn_id, message.status, message.body);
}
```

`turns.list` returns every turn and message of a session, oldest first; `turns.get(sessionId, turnId)` returns one turn.

## 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.conversation.state);
  }
} 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 2 retries for transport errors, `429`, `502`, `503`, and `504`. Configure `timeoutMs` and `maxRetries` when creating it.

---

# Budgets

> Cap what each session, agent, and your whole account can spend.

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

3 kinds of limit apply to every paid request. It starts only when all of them have room.

| Limit | Set in | Default |
| --- | --- | --- |
| Session budget | `budget` when starting a session, or `session.budget.session` in YAML | $250 |
| Agent or handler limits | `session.budget.day`, `week`, `month` in YAML | $1,000 a day, $10,000 a week, $40,000 per 28 days |
| Account limits | **Billing > Limits** | $250 a day, $2,500 a week, $10,000 per 28 days |

Values are US dollars.

## Cap a session

```bash
agent --model claude-opus-5-5 --budget 5 -e cloud_agent_environment "Fix the failing test."
```

In the API or SDK, send `"budget": {"session": 5}`. Follow-up messages share the same budget.

A session can't be given more than $250, or less if your account sets a lower ceiling in **Agents > Settings**. A larger request fails with `budget_exceeds_ceiling`.

When a session reaches its budget, its turn ends with `reason` set to `budget_hit`: `failed` when the agent was working, `cancelled` when it hadn't started. The budget can't be raised; `conversation.prompting.blocked_reason` becomes `budget_exhausted` and new messages fail with `409`, so start a new session to continue. See [Lifecycle](/docs/sessions/lifecycle#turn).

## Cap an agent

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  budget:
    session: 5
    day: 20
    week: 100
    month: 300
```

`session` caps each session. `day`, `week`, and `month` cap this agent's total spend over the last 1, 7, and 28 days. [Handlers](/docs/agents#handlers) take the same fields. A request that starts an agent session can send `budget.session` to replace the session cap; `day`, `week`, and `month` can't be sent in a request.

## Cap the account

Open **Billing > Limits** to set the account's 1-day, 7-day, and 28-day limits, up to $1,000, $10,000, and $40,000. The same page sets the default session budget.

Turn on **Limit spend per developer** to give each person and each API key their own limits. A person's limit covers the sessions they start from the dashboard, the CLI, and mentions. Scheduled sessions don't count toward any developer.

Only owners and admins can change these limits.

## When a limit is reached

A reached limit blocks new paid requests. Requests already running can finish, so spend can go slightly past a limit.

Budget alerts, set in **Billing > Limits**, notify you at 80% and 100% of each account limit by default. They go to the Slack [operations channel](/docs/integrations/slack#operations-channel), notification emails, and **Settings > Alerts**.

Check current limits and remaining spend with `agent budget` or `GET /v1/account/budget`.

---

# Getting started

> Run internal agents in the cloud with Claude Code or Codex, and extend them with your own tools, secrets, and MCP servers.

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

## Get started
  - [Quick start](/docs/quick-start): Install the CLI and start an agent session
  - [Code review](/docs/code-review#quick-start): Review each push to a pull request
  - [GitHub](/docs/integrations/github#quick-start): Answer @ellipsis on issues and pull requests
  - [Slack](/docs/integrations/slack#quick-start): Answer @ellipsis mentions in Slack
  - [Linear](/docs/integrations/linear#quick-start): Answer Ellipsis mentions on Linear issues
  - [Sentry](/docs/integrations/sentry#quick-start): Investigate alerts (not generally released)

## Platform
  - [Agents](/docs/agents): Save a task and run it on a schedule or event
  - [Environments](/docs/environments): Install your tools and connect MCP servers
  - [Sessions](/docs/sessions): Start a task, follow it, and send follow-ups
  - [Models](/docs/models): Choose a model or use your subscription
  - [Webhooks](/docs/webhooks): Get notified when sessions change
  - [Secrets](/docs/secrets): Store tokens and keys for your environments
  - [Permissions](/docs/permissions): Limit what sessions can do on GitHub
  - [Budgets](/docs/budgets): Cap spend per session, agent, and account

## Harnesses
  - [Claude Code](/docs/harnesses/claude): Models, options, and features for Claude Code
  - [Codex](/docs/harnesses/codex): Models, options, and features for Codex

## Reference
  - [API](/docs/api): Manage sessions, environments, and agents
  - [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): Start agent sessions from your terminal

---

# Models

> Choose a model and connect your Claude or ChatGPT subscription.

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

Send exactly one `claude_code` or `codex` block to choose [Claude Code](/docs/harnesses/claude) or [Codex](/docs/harnesses/codex), and set its `model`:

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

## Current support

| Model | ID | Runs in |
| --- | --- | --- |
| Claude Fable 5.1 | `claude-fable-5-1` | Claude Code |
| Claude Opus 5.5 | `claude-opus-5-5` | Claude Code |
| Claude Sonnet 5.5 | `claude-sonnet-5-5` | Claude Code |
| Claude Haiku 5.5 | `claude-haiku-5-5` | Claude Code |
| GPT-6.1 Sol | `gpt-6.1-sol` | Codex |
| GPT-6 Astra | `gpt-6-astra` | Codex |
| GPT-6 Sol | `gpt-6-sol` | Codex |
| GPT-6 Luna | `gpt-6-luna` | Codex |
| GPT-5.6 Sol | `gpt-5.6-sol` | Codex |

Claude Code also accepts `claude-fable`, `claude-opus`, `claude-sonnet`, and `claude-haiku` for the newest model in each family. See [Pricing](/docs/pricing#model-pricing) for token prices.

`GET /v1/account/models` returns the same list with each model's features. A session that asks for a feature its model doesn't support fails with `unsupported_session_combination` before it starts.

Every session names its model. In the CLI, `el model use claude-opus-5-5` sets the model a bare `el "..."` runs on when `--model` is absent.

## Use your subscription

Without a subscription, model usage is paid from your Ellipsis credits. To use your own Claude or ChatGPT plan instead:

1. Open **Models > Subscriptions** and choose **Add subscription**.
2. Pick the provider and paste its credential:
   - **Claude:** the token printed by `claude setup-token`. API keys aren't accepted.
   - **Codex:** the contents of `~/.codex/auth.json` after running `codex -c cli_auth_credentials_store="file" login` and signing in with ChatGPT. Treat this file as a password.
3. Choose **Save & verify**.

A Claude subscription pays for Claude models, and a Codex subscription pays for GPT models. A subscription belongs to the person who added it; see [Pricing](/docs/pricing#what-is-charged) for which sessions it covers. A session uses credits if, when it starts, your subscription isn't verified or your Codex login can't be refreshed. After a session starts, a failed subscription request fails the session instead of switching to credits.

---

# Account settings

> Configure spend limits and record retention.

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

Account settings apply to every session and agent. Owners and admins change spending settings while signed in; API keys and session credentials can't change them.

## Session budget ceiling

Set this in **Agents > Settings**.

| Setting | Effect |
| --- | --- |
| Session budget ceiling | The largest session budget a request can ask for |

## Spend limits

Set account limits, the default session budget, and optional per-developer limits in **Billing > Limits**. Account limits cover spend over the last 1, 7, and 28 days. Per-developer limits apply to each person and each API key separately.

A paid request starts only when every limit that applies has room, including agent and handler limits. Lowering a limit can stop paid requests in sessions that are already running. See [Budgets](/docs/budgets) for defaults and what happens at a limit.

## Platform allowances

**API > Limits** shows your account's API request limits, storage quotas, concurrency limits, and spending ceilings. Custom values are marked **Custom**. Every API request counts toward the account total, and some endpoints also have their own cap.

Your account keeps up to 32 sessions alive at once by default. A session counts while its agent runs and for a minute after each turn. More sessions wait as `queued` and start in the order they were created as others end.

To request an increase, ask in your shared Slack channel with the Ellipsis team. To create one, open **Help**.

## Budget alerts

Set alert thresholds in **Billing > Limits**. Alerts go to the Slack [operations channel](/docs/integrations/slack#operations-channel), notification emails, and **Settings > Alerts**. `GET /v1/account/budget` returns current limits and remaining spend.

## Retention

See [Security](/docs/security#data-retention) for how long session data is kept and when it's deleted.

## Shared configuration

A GitHub repository named `.ellipsis` holds configuration for your whole organization:

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

In other repositories, agents and environments go in a `.ellipsis/` directory. Integration files work only in the `.ellipsis` repository, and each defines the [handler](/docs/agents#handlers) for its service. Folder names for agents and environments are up to you.

## 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

Permissions limit what a session's GitHub and Ellipsis credentials can do. The [environment](/docs/environments) decides which repositories are checked out and which secrets are set.

## Read-only GitHub access

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  permissions:
    github:
      repositories: [api-repo]
      permissions: read_only
```

The agent can read `api-repo` on every scope the GitHub App has, such as code, pull requests, CI checks, and GitHub Actions logs. It can't push commits or comment on issues and pull requests, but it can still edit files in its sandbox.

## Allow code and pull request changes

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  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 can't exceed what the GitHub App is installed with.

`permissions.github.repositories` limits the credential; `environment.repositories` decides what is checked out. Set both when you need both.

## Read pull request checks

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  permissions:
    github:
      repositories: [api-repo]
      permissions:
        contents: write
        pull_requests: write
        checks: read
        statuses: read
        actions: read
```

The agent can read check runs, commit statuses, and Actions runs for its pull request. It can't create a check run of its own. These scopes need the GitHub App installation to grant them.

## Limit Ellipsis access

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  permissions:
    ellipsis:
      sessions: read
      environments: read
      secrets: read
```

Anything not listed is denied. `write` includes `read`, and `delete` includes both. Reading secrets returns their names, never their values. The token can always read its own identity, which the CLI uses to print links.

## Secrets

The agent and its tools can read every secret the environment sets, and GitHub permissions don't limit what those credentials can do. Keep secret values out of prompts, committed YAML, and command output; session logs record what tools print.

---

# 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 are paid from your balance.

## What is charged

| Models paid by | Tokens | CPU and memory: personal | CPU and memory: organization |
| --- | --- | --- | --- |
| Ellipsis credits | The model's rate, below | Free | At cost |
| Your Claude subscription | $0 to Ellipsis | Free | At cost |
| Your Codex subscription | $0 to Ellipsis | Free | At cost |

A [subscription](/docs/models#use-your-subscription) covers sessions you start yourself, on personal and organization accounts: from the dashboard, the CLI, the API with your own token, or a mention from a GitHub, Slack, or Linear account linked to your GitHub account. Scheduled and event-triggered agents, sessions started with an API key, and sessions an agent starts use credits.

Organization compute costs $0.141912 per CPU core-hour and $0.024192 per GiB-hour of memory, for the resources allocated while a sandbox runs, including while it waits for your next message.

## Model pricing

Prices in USD per 1 million tokens, for personal and organization accounts.

| Model | Input | Cached input | Output |
| --- | --- | --- | --- |
| Claude Fable 5.1 | $10.00 | $0.25 | $50.00 |
| Claude Opus 5.5 | $4.00 | $0.20 | $20.00 |
| Claude Sonnet 5.5 | $2.00 | $0.20 | $10.00 |
| Claude Haiku 5.5 | $0.10 | $0.01 | $0.50 |
| GPT-6.1 Sol | $2.00 | $0.10 | $10.00 |
| GPT-6 Astra | $10.00 | $1.00 | $50.00 |
| GPT-6 Sol | $2.00 | $0.20 | $10.00 |
| GPT-6 Luna | $0.10 | $0.01 | $0.50 |
| GPT-5.6 Sol | $2.00 | $0.20 | $10.00 |

Cache writes cost 1.25× input for Claude (5-minute) and GPT, or 2× input for Claude (1-hour). A GPT-6 or GPT-6.1 request with more than 272K input tokens, cache reads and writes included, costs 2× input and 1.5× output for the whole request. A Claude Haiku 5.5 request with more than 100K input tokens, cache reads and writes included, costs 5× for the whole request.

## 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.

## 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** shows model and compute usage separately, and each session shows its own cost.

The usage API groups usage by UTC calendar month. For sessions paid by a subscription, it shows what the tokens would have cost; you aren't charged for them.

---

# Quick start

> Set up Ellipsis for your repository.

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

These steps install Ellipsis on your repositories, set up the environment its agents run in, and build your first agent.

## Install on GitHub

[Install on GitHub](https://app.ellipsis.dev)

## Install the CLI

<span id="use-the-cli" />

```sh
curl -fsSL https://ellipsis.dev/install.sh | sh
```

```sh
el auth login
```

## Set up your environment

Paste this into Claude Code or Codex in your repository.

```text
Set up an Ellipsis environment for this repository. An environment is a YAML file that defines the cloud environment Ellipsis agents run in: the repositories checked out, the scripts that install dependencies and build, the environment variables, and the machine size. The `el` CLI is installed and logged in.

1. Learn how this repository installs dependencies, builds, and runs its tests. Read the README, AGENTS.md, CLAUDE.md, package manifests, lockfiles, Dockerfiles, Makefiles, and CI workflows.

2. Run `el environment init .ellipsis/environments/<repo>.yaml`, where <repo> is this repository's GitHub name, then edit the file. Read https://www.ellipsis.dev/docs/environments and https://www.ellipsis.dev/docs/environments/schema first. Follow these rules:
   - Set `ellipsis.name` to <repo> and list <repo> under `repositories`.
   - The repository is checked out at /sandbox/<repo>. Scripts run in /sandbox as the sandbox user, and each must exit 0.
   - Install dependencies in `hooks.build_base`. List every file the install reads in `build_base.inputs`, each path starting with <repo>/ (for example <repo>/package-lock.json). Only listed files exist while build_base runs. Globs fail.
   - Build in `hooks.after_checkout`, written so it is safe to run again on a workspace that already has its output. Start services in the background and wait until they are ready.
   - Remove the starter's example variables and MCP servers unless this repository needs them. List required secrets under `variables` by name only. Never write a secret value into the file.

3. For each secret the tests need, ask me for the value or tell me to run `el variable set NAME=value` myself. Do not continue until they are set.

4. Create the environment: `el environment create -f .ellipsis/environments/<repo>.yaml`

5. Test it: `el session start -e <repo> --model claude-opus-5-5 --budget 2 --watch "Run this repository's tests and report the result. Do not change any files."`

6. If the session fails or the tests do not run, read the output (`el session export <session-id>` prints the full log), fix the file, apply it with `el environment edit <repo> -f .ellipsis/environments/<repo>.yaml`, and test again. Repeat until the tests run. If a session fails because the account has no credits, stop and tell me to add credits under Billing > Credits in the Ellipsis dashboard.

7. Once the tests run, delete the test copy with `el environment delete <repo>` and open a pull request that adds .ellipsis/environments/<repo>.yaml to the default branch. Ellipsis syncs the environment from the default branch when the pull request merges.

8. Reply with the pull request link, the test result, and any secrets I still need to set.
```

## Build an agent

Build an [agent](/docs/agents) that runs in your environment. You can also build agents for [Slack](/docs/integrations/slack), [Linear](/docs/integrations/linear), [Sentry](/docs/integrations/sentry), and [code review](/docs/code-review).

---

# Secrets

> Store tokens and keys once, then use them in environments and MCP servers without putting them in git.

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

A secret is a named value, such as an npm token or an API key, stored in your account. Environments refer to it by name, so the value never appears in git.

## Add a secret

- **Dashboard:** open **Environments > Secrets** and choose **New secrets**.
- **CLI:** `ellipsis variable set NPM_TOKEN=your-token-value`, or `ellipsis variable set -f .env` to load a file.
- **API:** `PUT /v1/secrets`:

```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": "your-token-value"}]}'
```

Setting an existing name replaces its value. Names use letters, digits, and underscores, and can't start with a digit. An account can store up to 500 secrets.

## Use a secret

List its name under `variables` without a `value`:

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

repositories:
  - name: web-repo

variables:
  - name: NPM_TOKEN
```

Setup scripts and the agent get `NPM_TOKEN` as an environment variable. A missing secret fails the session.

To pass a secret to an [MCP server](/docs/environments/schema#add-an-mcp-server), write `${NAME}` in its `headers` or `env`. It doesn't need a `variables` entry.

## Rules

- Secrets belong to the account, so any environment can use them.
- Stored values can't be read back through the dashboard, CLI, or API; you see names only.
- The agent can read every secret its environment sets. Keep values out of prompts and command output; see [Permissions](/docs/permissions#secrets).
- Delete a secret in the dashboard, with `ellipsis variable delete NPM_TOKEN`, or with `DELETE /v1/secrets/{name}`.

---

# 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 |

For example, data that expires at 12:00 UTC is deleted by 16:00 UTC. A TTL of 0 hours means data is deleted within 4 hours. Export records you need before their TTL expires.

## GitHub access

[Choose which repositories the GitHub App can access](/docs/integrations/github#repository-access), then [limit each session's GitHub permissions](/docs/permissions).

## Secrets

Store credentials as [secrets](/docs/secrets); stored values can't be read back through the dashboard or API. See [Permissions](/docs/permissions#secrets) for what a session can do with them.

## API access and webhooks

Keep [API keys](/docs/api/authentication) on your server. [Verify webhook signatures](/docs/webhooks#verify-signatures) before trusting a delivery.

## Contact

For security questions or deletion requests, contact [Support](/docs/support). Don't include secret values.

---

# Support

> Contact Ellipsis and check service status.

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

- [Schedule a demo](https://cal.com/ellipsis/demo): Book a call with the team
- Connect shared Slack: Set up a shared channel with the team
  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): Incidents and uptime

---

# Webhooks

> Get a signed HTTPS request whenever a session is created.

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

A webhook sends a signed `POST` to your HTTPS endpoint whenever a session is created, from any source: the dashboard, the CLI, the API, agents, and handlers.

## Create a webhook

```bash
curl https://api.ellipsis.dev/v1/webhooks -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" -H "Content-Type: application/json" -d '{"url": "https://example.com/hooks/ellipsis", "events": ["session.create"]}'
```

The response includes a `secret` that starts with `whsec_`. Save it: it's shown only once. To change it, delete the webhook and create a new one.

The URL must be public HTTPS on port 443 or 8443. An account can have up to 3 webhooks.

## Activate it

1. Send a test event with `POST /v1/webhooks/{id}/ping`. Your endpoint must answer with HTTP 200.
2. Open **Settings > Webhooks** and choose **Request activation**.

Ellipsis turns the webhook on after reviewing the request. Until then it receives only pings.

## Events

| Event | Sent when |
| --- | --- |
| `session.create` | A session is created |
| `webhook.ping` | You call the ping endpoint; always sent |

Every delivery has the same envelope. For `session.create`, `data.session` is the object `GET /v1/sessions/{id}` returns:

```json
{
  "id": "event_0f8e2c",
  "type": "session.create",
  "created_at": "2026-09-22T17:03:11.482913Z",
  "api_version": "v1",
  "data": {
    "session": {
      "id": "session_4b1d9a",
      "source": "api",
      "budget": 500000,
      "conversation": { "state": "open" },
      "turn": { "id": "turn_8c2f1e", "status": "queued" }
    }
  }
}
```

This example is shortened; real IDs are longer, and `session` has every field.

## Verify signatures

Each request has 3 headers:

| Header | Value |
| --- | --- |
| `webhook-id` | The event ID; the same on every retry |
| `webhook-timestamp` | Unix seconds when this attempt was sent |
| `webhook-signature` | `v1,` followed by a base64 HMAC-SHA256 signature |

To verify, base64-decode your secret without its `whsec_` prefix, and sign `{webhook-id}.{webhook-timestamp}.{raw body}` with it. Use the raw request bytes, not re-serialized JSON:

```python
import base64
import hashlib
import hmac
import time

def verify(secret: str, headers: dict[str, str], body: bytes) -> bool:
    event_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{event_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(
        hmac.compare_digest(expected, signature.removeprefix("v1,"))
        for signature in headers["webhook-signature"].split()
    )
```

```typescript
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret: string, headers: Headers, body: string): boolean {
  const eventId = headers.get('webhook-id') ?? '';
  const timestamp = headers.get('webhook-timestamp') ?? '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key)
    .update(`${eventId}.${timestamp}.${body}`)
    .digest('base64');
  return (headers.get('webhook-signature') ?? '').split(' ').some((signature) => {
    const value = Buffer.from(signature.replace(/^v1,/, ''));
    return value.length === expected.length && timingSafeEqual(value, Buffer.from(expected));
  });
}
```

These examples reject requests older than 5 minutes.

## Delivery

- Any 2xx response within 10 seconds counts as delivered. Pings need exactly 200.
- A failed delivery is retried after 1 minute and again after 10 minutes, then marked failed.
- Events can arrive out of order or more than once; use `webhook-id` to skip duplicates.
- `GET /v1/webhooks/deliveries` lists the last 30 days of deliveries, and `GET /v1/webhooks/deliveries/{id}` shows one with its payload and attempts.

---

# Agents

> Save a task and its session settings, then start it on demand, on a schedule, or from events.

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

An agent saves a prompt, an environment, permissions, and a budget. Each start is a new session. A trigger starts it automatically.

## Define an agent

```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-opus-5-5
  environment:
    repositories:
      - name: api-repo
  budget:
    session: 5
```

This agent fixes one failing test and opens a pull request. It has no trigger, so it runs only when you start it.

## Deploy from git

Commit a `.yaml` or `.yml` file with `ellipsis.kind: agent` anywhere under `.ellipsis/` on the default branch. It appears on the dashboard's **Agents** page. Your organization can also keep these files in a repository named `.ellipsis`.

If an update is invalid, the last valid version keeps running and the agent's page shows the error. Deleting the file disables the agent.

## Create through the API

`POST /v1/agents` creates an agent without a repository file. Send the same fields as JSON under `agent`.

Each agent is edited in one place: its git file or the API. Use `link` to move an API-created agent into git, or `unlink` to edit a git-managed one through the API.

## Start an agent session

Choose **Run** on its dashboard page, or start it through the API:

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

It starts as written, and its session stays open for follow-ups. If it declares `input`, send `input` in the body. To change settings for one session, see [Override settings for a session](/docs/agents#override-settings-for-a-session).

## Override settings for a session

An agent session starts from the agent's `session` settings. Its request body takes the fields of [Start a session](/docs/api/sessions/post-sessions) plus `input`: each field you send replaces the agent's value for that field, and each field you leave out keeps it. `metadata` is merged into the agent's key by key: a key you send sets that key, a `null` value removes it, and the agent's other keys stay. Other lists and maps, and `environment`, are replaced whole.

This agent sets a model, prompt, environment, budget, and metadata:

```yaml title=".ellipsis/agents/repo-summary.yaml"
ellipsis:
  kind: agent
  name: repo-summary

session:
  claude_code:
    model: claude-opus-5-5
    prompt: Summarize api-repo.
  environment: api-environment
  budget:
    session: 2
    day: 10
  metadata:
    team: platform
```

Started with an empty body, `repo-summary` runs Claude Opus 5.5 in `api-environment` with its saved prompt, stops at $2, and sets the session's metadata to `team: platform`. The `day` limit caps the agent's total spend at $10 over the last day, and the session stays open for follow-ups.

Replace the prompt for one session; the model, environment, budget, and metadata stay as the file sets them:

```json
{
  "claude_code": {
    "prompt": "Focus on the tests."
  }
}
```

Set the cap for one session to $5; the `day` limit still applies. A request's `budget` takes only `session`, and `day`, `week`, or `month` returns 422:

```json
{
  "budget": {
    "session": 5
  }
}
```

Add a metadata key; the session gets `team: platform` and `ticket: ENG-42`:

```json
{
  "metadata": {
    "ticket": "ENG-42"
  }
}
```

Remove one of the agent's keys with `null`; the session gets only `ticket: ENG-42`:

```json
{
  "metadata": {
    "team": null,
    "ticket": "ENG-42"
  }
}
```

Start in other repositories by sending a whole environment; `api-environment` is not used, and nothing is merged into it:

```json
{
  "environment": {
    "repositories": [
      {
        "name": "api-repo"
      },
      {
        "name": "web-repo"
      }
    ]
  }
}
```

Scheduled and event-triggered sessions use the same settings, so they stay open for follow-ups too, and anyone with write access to sessions can message a scheduled session because it has no owner. Set `conversation.interactive` to `false`, in the file or in a request body, to run once:

```yaml fragment
session:
  conversation:
    interactive: false
```

## Add a trigger

<span id="triggers" />

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

This runs every Monday at 09:00 UTC. An agent has at most one trigger. See [Triggers](/docs/agents/triggers) for schedules and events, or the [Agent schema reference](/docs/agents/schema) for complete examples.

## Handlers

Handlers answer `@ellipsis` mentions in [GitHub](/docs/integrations/github), [Slack](/docs/integrations/slack), and [Linear](/docs/integrations/linear), and investigate [Sentry](/docs/integrations/sentry) alerts. Each service has one handler file (`github.yaml`, `slack.yaml`, `linear.yaml`, or `sentry.yaml`) at the root of your organization's `.ellipsis` repository. Its `session` block works like an agent's, including budgets.

Open **Handlers** in the dashboard to see each handler's file, sync status, sessions, and cost, or list them with `GET /v1/handlers`.

---

# Agent schema reference

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

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

An agent file has 4 top-level blocks: `ellipsis`, optional `trigger`, optional `input`, and `session`. Set `ellipsis.kind` to `agent`. Unknown fields fail validation. See [Agents](/docs/agents) for how files deploy and run.

## 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-opus-5-5
  environment:
    repositories:
      - name: api-repo
  permissions:
    github:
      permissions: read_only
  budget:
    session: 3
    day: 10
    week: 50
```

Every night at 02:00 UTC, a session runs the tests and reports failures without changing code.

## 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:
    model: claude-opus-5-5
    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
  budget:
    session: 5
```

Each push to a non-draft pull request in `api-repo` that changes `src/routes/` starts a session. The trigger decides which events match; the environment decides which repositories are checked out.

## 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-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
```

Start it with `{"input":{"description":"Reject expired reset tokens"}}` instead of a prompt. The validated result is `output.result` on the session once the turn ends.

Structured output works with the models that list it in `GET /v1/account/models`.

An agent with a trigger can declare `input` too. The trigger fires on its event as before; `json_schema` applies when you start the agent from the dashboard, CLI, or API. One `message` template serves both, so every `{{field}}` in it must be a field of the event and of the schema: declare the event's field names in the schema. The template then reads the event when the trigger fires and the input when you start it. Omit `message` to keep each door's default: the event's details on a trigger, your input as JSON on a start.

```yaml title=".ellipsis/agents/issue-triage.yaml"
ellipsis:
  kind: agent
  name: issue-triage

trigger:
  type: react
  linear_issue:
    on: [opened]

input:
  json_schema:
    type: object
    properties:
      issue:
        type: object
        properties:
          identifier:
            type: string
        required: [identifier]
    required: [issue]
    additionalProperties: false
  message: 'Triage {{issue.identifier}}.'

session:
  claude_code:
    prompt: |
      Reproduce the issue, label it, and comment with a proposed fix.
    model: claude-opus-5-5
```

When a Linear issue opens, the message renders from the event: `Triage API-214.`. Starting the agent with `{"input":{"issue":{"identifier":"API-214"}}}` renders the same message from your input, so a nightly job can run it on an issue you choose.

## Add a Codex skill

A skill is a directory with a `SKILL.md` file that gives Codex a reusable procedure and its supporting files:

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

`SKILL.md` needs YAML frontmatter with a `description`. Ellipsis reads the skill from the session's checkout of that repository, or from its default branch when the repository isn't in the session. A missing or invalid skill fails the session.

A session can have up to 10 skills. Each skill can have up to 50 files, 64 KiB per file, and 512 KiB in total.

## Budgets

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  budget:
    session: 5
    day: 20
    week: 100
    month: 300
```

Values are US dollars. `session` caps each session. `day`, `week`, and `month` cap this agent's total spend over the last 1, 7, and 28 days. Handlers take the same fields. Account limits also apply; see [Budgets](/docs/budgets).

## Fields

<span id="identity-and-triggers" />
<span id="session-settings" />

| Field | Type | Meaning |
| --- | --- | --- |
| `ellipsis` | `object`, required | Identifies the file. |
| `ellipsis.kind` | `string`, required | `agent`. One of `agent`. |
| `ellipsis.name` | `string` | Agent name, unique within the account. |
| `ellipsis.description` | `string` | Description shown in the dashboard. |
| `ellipsis.enabled` | `boolean` | Whether the agent is active. Default `true`. |
| `ellipsis.metadata` | `object` | `labels` and `annotations` for your own use. |
| `ellipsis.metadata.labels` | `list of string` | Short tags. |
| `ellipsis.metadata.annotations` | `map of string` | Free text values by key. |
| `trigger` | `object` | One cron or react trigger; omit to start only on demand. See [Triggers](/docs/agents/triggers). |
| `trigger.type` | `string` | `cron` runs on a schedule; `react` runs on matching events. One of `cron`, `react`. |
| `trigger.enabled` | `boolean` | `false` pauses the trigger and keeps the agent startable; see [Pause a trigger](/docs/agents/triggers#pause-a-trigger). Default `true`. |
| `trigger.schedule` | `string` | A 5 field cron expression in UTC; see [Schedules](/docs/agents/triggers#schedules). `cron` only. |
| `trigger.pull_request` | `object` | Pull request events to match; see [Pull requests](/docs/agents/triggers#pull-requests). |
| `trigger.pull_request.on` | `list of string`, required | Which events fire. One of `opened` (Opened, reopened, or marked ready for review), `pushed` (New commits, including when the pull request opens), `merged` (Merged), `closed` (Closed without merging), `review_submitted` (A review is submitted), `commented` (A comment is added). |
| `trigger.pull_request.repositories` | `list of string or object` | Repository names, or an object with `include` and `exclude` lists. Default every installed repository. |
| `trigger.pull_request.repositories.include` | `list of string` | Repository names to match. Default every repository of the installation, including ones added later. |
| `trigger.pull_request.repositories.exclude` | `list of string` | Repository names to skip, applied after `include`. |
| `trigger.pull_request.base` | `list of string` | Base branches to match. Exact names, prefixes ending in `*`, and `default`. |
| `trigger.pull_request.head` | `list of string` | Head branches to match. Exact names, prefixes ending in `*`, and `default`. |
| `trigger.pull_request.draft` | `boolean` | `true` matches only draft pull requests, `false` only ready ones. Default both. |
| `trigger.pull_request.labels` | `list of string` | Labels match when any listed label is present. |
| `trigger.pull_request.paths` | `list of string` | Globs of changed files to match. `!` patterns aren't allowed. Default every change. |
| `trigger.pull_request.for` | `object` | Which authors count. |
| `trigger.pull_request.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `trigger.pull_request.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.pull_request.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.pull_request.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `trigger.pull_request.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.pull_request.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.pull_request.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `trigger.push` | `object` | Branch pushes to match; see [Branch pushes](/docs/agents/triggers#branch-pushes). Push triggers have no `on` field. |
| `trigger.push.repositories` | `list of string or object` | Repository names, or an object with `include` and `exclude` lists. Default every installed repository. |
| `trigger.push.repositories.include` | `list of string` | Repository names to match. Default every repository of the installation, including ones added later. |
| `trigger.push.repositories.exclude` | `list of string` | Repository names to skip, applied after `include`. |
| `trigger.push.branch` | `list of string` | Branches to match. Exact names, prefixes ending in `*`, and `default`. |
| `trigger.push.paths` | `list of string` | Globs of changed files to match. `!` patterns aren't allowed. Default every change. |
| `trigger.push.for` | `object` | Which authors count. |
| `trigger.push.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `trigger.push.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.push.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.push.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `trigger.push.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.push.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.push.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `trigger.issue` | `object` | GitHub issue events to match; see [Issues](/docs/agents/triggers#issues). |
| `trigger.issue.on` | `list of string`, required | Which events fire. One of `opened` (Opened), `closed` (Closed), `commented` (A comment is added). |
| `trigger.issue.repositories` | `list of string or object` | Repository names, or an object with `include` and `exclude` lists. Default every installed repository. |
| `trigger.issue.repositories.include` | `list of string` | Repository names to match. Default every repository of the installation, including ones added later. |
| `trigger.issue.repositories.exclude` | `list of string` | Repository names to skip, applied after `include`. |
| `trigger.issue.labels` | `list of string` | Labels match when any listed label is present. |
| `trigger.issue.for` | `object` | Which authors count. |
| `trigger.issue.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `trigger.issue.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.issue.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.issue.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `trigger.issue.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.issue.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.issue.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `trigger.check_run` | `object` | CI checks to match; see [CI checks](/docs/agents/triggers#ci-checks). Needs the Checks permission on the GitHub App installation. |
| `trigger.check_run.on` | `list of string` | Which states fire. Default `[failed]`. One of `requested` (Created with status `requested`), `queued` (Created with status `queued`), `waiting` (Created with status `waiting`), `pending` (Created with status `pending`), `started` (Created with status `in_progress`), `passed` (Concluded `success`), `failed` (Concluded `failure`), `timed_out` (Concluded `timed_out`), `cancelled` (Concluded `cancelled`), `skipped` (Concluded `skipped`), `neutral` (Concluded `neutral`), `action_required` (Concluded `action_required`), `stale` (Concluded `stale`). |
| `trigger.check_run.repositories` | `list of string or object` | Repository names, or an object with `include` and `exclude` lists. Default every installed repository. |
| `trigger.check_run.repositories.include` | `list of string` | Repository names to match. Default every repository of the installation, including ones added later. |
| `trigger.check_run.repositories.exclude` | `list of string` | Repository names to skip, applied after `include`. |
| `trigger.check_run.names` | `list of string` | Check names to match. Exact names and prefixes ending in `*`. Default every check. |
| `trigger.check_run.branch` | `list of string` | Branches the check ran on. Exact names, prefixes ending in `*`, and `default`. |
| `trigger.check_run.for` | `object` | Which authors count. |
| `trigger.check_run.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `trigger.check_run.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.check_run.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.check_run.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `trigger.check_run.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.check_run.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.check_run.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `trigger.check_suite` | `object` | Check suites to match; see [Check suites](/docs/agents/triggers#check-suites). Needs the Checks permission on the GitHub App installation. |
| `trigger.check_suite.on` | `list of string` | Which outcomes fire. Default `[failed]`. One of `passed` (Concluded `success`), `failed` (Concluded `failure`), `timed_out` (Concluded `timed_out`), `cancelled` (Concluded `cancelled`), `skipped` (Concluded `skipped`), `neutral` (Concluded `neutral`), `action_required` (Concluded `action_required`), `stale` (Concluded `stale`), `startup_failure` (Concluded `startup_failure`). |
| `trigger.check_suite.repositories` | `list of string or object` | Repository names, or an object with `include` and `exclude` lists. Default every installed repository. |
| `trigger.check_suite.repositories.include` | `list of string` | Repository names to match. Default every repository of the installation, including ones added later. |
| `trigger.check_suite.repositories.exclude` | `list of string` | Repository names to skip, applied after `include`. |
| `trigger.check_suite.apps` | `list of string` | Reporting app slugs to match, such as `github-actions`. Exact slugs and prefixes ending in `*`. Default every app. |
| `trigger.check_suite.branch` | `list of string` | Branches the suite ran on. Exact names, prefixes ending in `*`, and `default`. |
| `trigger.check_suite.for` | `object` | Which authors count. |
| `trigger.check_suite.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `trigger.check_suite.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.check_suite.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.check_suite.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `trigger.check_suite.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.check_suite.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.check_suite.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `trigger.workflow_run` | `object` | GitHub Actions workflow runs to match; see [Workflow runs](/docs/agents/triggers#workflow-runs). Needs the Actions permission on the GitHub App installation. |
| `trigger.workflow_run.on` | `list of string` | Which states fire. Default `[failed]`. One of `requested` (Created with status `requested`), `queued` (Created with status `queued`), `waiting` (Created with status `waiting`), `pending` (Created with status `pending`), `started` (Created with status `in_progress`), `passed` (Concluded `success`), `failed` (Concluded `failure`), `timed_out` (Concluded `timed_out`), `cancelled` (Concluded `cancelled`), `skipped` (Concluded `skipped`), `neutral` (Concluded `neutral`), `action_required` (Concluded `action_required`), `stale` (Concluded `stale`), `startup_failure` (Concluded `startup_failure`). |
| `trigger.workflow_run.repositories` | `list of string or object` | Repository names, or an object with `include` and `exclude` lists. Default every installed repository. |
| `trigger.workflow_run.repositories.include` | `list of string` | Repository names to match. Default every repository of the installation, including ones added later. |
| `trigger.workflow_run.repositories.exclude` | `list of string` | Repository names to skip, applied after `include`. |
| `trigger.workflow_run.names` | `list of string` | Workflow names to match. Exact names and prefixes ending in `*`. Default every workflow. |
| `trigger.workflow_run.branch` | `list of string` | Branches the run is for. Exact names, prefixes ending in `*`, and `default`. |
| `trigger.workflow_run.for` | `object` | Which authors count. |
| `trigger.workflow_run.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `trigger.workflow_run.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.workflow_run.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.workflow_run.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `trigger.workflow_run.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.workflow_run.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.workflow_run.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `trigger.status` | `object` | Commit statuses to match; see [Commit statuses](/docs/agents/triggers#commit-statuses). Needs the Commit statuses permission on the GitHub App installation. |
| `trigger.status.on` | `list of string` | Which states fire. Default `[failed]`. One of `pending` (The status is `pending`), `passed` (The status is `success`), `failed` (The status is `failure`), `errored` (The status is `error`). |
| `trigger.status.repositories` | `list of string or object` | Repository names, or an object with `include` and `exclude` lists. Default every installed repository. |
| `trigger.status.repositories.include` | `list of string` | Repository names to match. Default every repository of the installation, including ones added later. |
| `trigger.status.repositories.exclude` | `list of string` | Repository names to skip, applied after `include`. |
| `trigger.status.names` | `list of string` | Status contexts to match. Exact names and prefixes ending in `*`. Default every context. |
| `trigger.status.branch` | `list of string` | Branches to match. Matches when any branch GitHub lists for the commit matches. Exact names, prefixes ending in `*`, and `default`. |
| `trigger.status.for` | `object` | Which authors count. |
| `trigger.status.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `trigger.status.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.status.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.status.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `trigger.status.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.status.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.status.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `trigger.release` | `object` | Releases to match; see [Releases](/docs/agents/triggers#releases). |
| `trigger.release.on` | `list of string` | Which events fire. Default `[published]`. One of `published` (A release or prerelease is published, including a draft published later). |
| `trigger.release.repositories` | `list of string or object` | Repository names, or an object with `include` and `exclude` lists. Default every installed repository. |
| `trigger.release.repositories.include` | `list of string` | Repository names to match. Default every repository of the installation, including ones added later. |
| `trigger.release.repositories.exclude` | `list of string` | Repository names to skip, applied after `include`. |
| `trigger.release.tag` | `list of string` | Tags to match. Exact names and prefixes ending in `*`. Default every tag. |
| `trigger.release.prerelease` | `boolean` | `true` matches only prereleases, `false` only full releases. Default both. |
| `trigger.release.for` | `object` | Which authors count. |
| `trigger.release.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `trigger.release.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.release.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.release.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `trigger.release.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.release.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.release.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `trigger.linear_issue` | `object` | Linear issue events to match; see [Linear issues](/docs/agents/triggers#linear-issues). Issues created by bots don't count. |
| `trigger.linear_issue.on` | `list of string` | Which events fire. Default `[opened]`. One of `opened` (Created). |
| `trigger.linear_issue.for` | `object` | Which authors count. |
| `trigger.linear_issue.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `trigger.linear_issue.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.linear_issue.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.linear_issue.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `trigger.linear_issue.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `trigger.linear_issue.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `trigger.linear_issue.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `trigger.sentry` | `object` | Sentry alerts to match; see [Sentry alerts](/docs/agents/triggers#sentry-alerts). |
| `trigger.sentry.on` | `list of string`, required | Which alerts fire. One of `issue_alert` (An issue alert fires), `metric_alert` (A metric alert becomes critical). |
| `trigger.sentry.projects` | `list of string` | Sentry project slugs. Default every project. |
| `trigger.slack_channel` | `object` | Runs when someone creates a Slack channel; see [Slack channels](/docs/agents/triggers#slack-channels). Takes no fields. |
| `input` | `object` | Typed input for sessions you start from the dashboard, CLI, or API; a trigger fires without it. See [Typed input and output](/docs/agents/schema#typed-input-and-output). |
| `input.json_schema` | `object` | Schema the request's `input` must match. |
| `input.message` | `string` | First message template; omit to send the input as JSON. `{{field}}` inserts a field from the input or the trigger event. |
| `session` | `object`, required | The session each run starts. |
| `session.claude_code` | `object` | Runs the session with [Claude Code](/docs/harnesses/claude). Exactly one of `claude_code` or `codex`. |
| `session.claude_code.prompt` | `string` | The task. |
| `session.claude_code.model` | `string`, required | A Claude Code model from [Models](/docs/models#current-support). |
| `session.claude_code.effort` | `string` | Reasoning effort, where the model supports it. One of `low`, `medium`, `high`, `xhigh`, `max`. |
| `session.claude_code.max_turns` | `integer` | The most turns the agent can take on each message, a whole number above 0. |
| `session.claude_code.fallback_model` | `string` | The model Claude Code switches to when `model` is overloaded. Default none. |
| `session.claude_code.settings` | `object` | A Claude Code `settings.json` in a repository, applied below the settings Ellipsis manages. Hooks stay disabled. |
| `session.claude_code.settings.path` | `string`, required | Path of the file, relative to the repository root. |
| `session.claude_code.settings.repository` | `object` | Where `path` resolves. Default the repository this file lives in. |
| `session.claude_code.settings.repository.name` | `string`, required | The repository name, without the owner. |
| `session.claude_code.settings.repository.owner` | `string` | The GitHub owner. Default your account. |
| `session.claude_code.settings.repository.ref` | `string` | Branch, tag, or commit. Default the default branch. |
| `session.codex` | `object` | Runs the session with [Codex](/docs/harnesses/codex). Exactly one of `claude_code` or `codex`. |
| `session.codex.prompt` | `string` | The task. |
| `session.codex.model` | `string`, required | `gpt-6.1-sol`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, or `gpt-5.6-sol`. |
| `session.codex.effort` | `string` | Reasoning effort. GPT-6.1 Sol and GPT-6 Astra don't accept `none`. Default `medium`. One of `none`, `low`, `medium`, `high`, `xhigh`, `max`. |
| `session.environment` | `string or object` | A saved environment name or an inline environment; see the [Environment schema reference](/docs/environments/schema). Default the built-in basic environment. |
| `session.permissions` | `object` | GitHub and Ellipsis access; see [Permissions](/docs/permissions). |
| `session.permissions.ellipsis` | `boolean or object` | Ellipsis API access for the session token. `true` grants everything a session token can do; a map narrows it per resource. Default `true`. |
| `session.permissions.github` | `object` | GitHub access for the session token. |
| `session.permissions.github.permissions` | `string or object` | `read_only`, or a map of GitHub permission names to levels. Default the installation's full permissions. |
| `session.permissions.github.repositories` | `list of string` | Repositories the token may reach. Default every repository of the installation. |
| `session.budget` | `object` | Spend limits in US dollars. Account limits also apply; see [Budgets](/docs/budgets). |
| `session.budget.session` | `number` | The most one session may spend, in US dollars. |
| `session.budget.day` | `number` | The most the agent may spend over the last day. |
| `session.budget.week` | `number` | The most the agent may spend over the last 7 days. |
| `session.budget.month` | `number` | The most the agent may spend over the last 28 days. |
| `session.conversation` | `object` | How the session behaves after its first turn. |
| `session.conversation.interactive` | `boolean` | Whether the session stays open for follow-ups; `false` runs once. Default `true`. |
| `session.metadata` | `map of string` | String keys and values stored on every session. |
| `session.output` | `object` | Structured result; see [Typed input and output](/docs/agents/schema#typed-input-and-output). |
| `session.output.json_schema` | `object`, required | Schema for the final JSON result, returned in `output.result` on `GET /v1/sessions/{id}`. |
| `session.skills` | `list of object` | Skills from a repository, for Codex; see [Add a Codex skill](/docs/agents/schema#add-a-codex-skill). Up to 10. Default none. |
| `session.skills[].path` | `string`, required | Directory holding `SKILL.md`, relative to the repository root. |
| `session.skills[].repository` | `object` | Where `path` resolves. Default the repository this file lives in. |
| `session.skills[].repository.name` | `string`, required | The repository name, without the owner. |
| `session.skills[].repository.owner` | `string` | The GitHub owner. Default your account. |
| `session.skills[].repository.ref` | `string` | Branch, tag, or commit. Default the default branch. |

In `input.message`, `{{field}}` inserts a field from the input. Triggered agents can insert event fields the same way. Every reference must exist in the input schema or the trigger's event, and in both when the agent has a trigger and a schema.

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

---

# Triggers

> Run agents on schedules or matching events.

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

An agent has at most one trigger. Without one, it runs only when you start it from the dashboard or API. Each run starts a new session that stays open for follow-ups unless the agent sets `conversation.interactive` to `false`. For event triggers, the session's first message includes the event.

## Schedules

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

Runs at 09:00 UTC on weekdays. `schedule` is a 5-field cron expression (minute, hour, day of month, month, day of week) in UTC:

```yaml fragment
trigger:
  type: cron
  schedule: '0 */6 * * *'
```

Runs every 6 hours, at 00:00, 06:00, 12:00, and 18:00 UTC. If Ellipsis is unavailable when a run is due, that run is skipped and the next one starts on schedule.

## Pull requests

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

Runs on each push to a non-draft pull request into `main` that changes a matching path, including when the pull request opens.

| Event | When it fires |
| --- | --- |
| `opened` | Opened, reopened, or marked ready for review |
| `pushed` | New commits, including when the pull request opens |
| `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 when a push to the default branch or a `release/` branch changes `package.json` or the lockfile. Push triggers have no `on` field.

## Issues

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

Runs when someone opens an issue labeled `bug` in `api-repo`.

## CI checks

```yaml fragment
trigger:
  type: react
  check_run:
    on: [failed, timed_out]
    repositories: [api-repo]
    names: ['test *', lint]
    branch: [default, 'release/*']
```

Runs when a check named `lint` or starting with `test ` fails or times out on the default branch or a `release/` branch of `api-repo`. A check is a GitHub Actions job or a check another CI app reports.

| Value | When it fires |
| --- | --- |
| `requested`, `queued`, `waiting`, `pending` | The check is created in that state |
| `started` | The check is created already running |
| `passed` | The check concludes `success` |
| `failed` | The check concludes `failure` |
| `timed_out`, `cancelled`, `skipped`, `neutral`, `action_required`, `stale` | The check concludes with that value |

- `names` matches check names exactly or by a prefix ending in `*`. Omit it to match every check
- `branch` is the branch the check ran on. A check on a fork's pull request has none
- `for` is the author of the commit the check ran on, so an agent's own commits don't count unless `bots` includes it
- Every matching check starts its own session, so a matrix of 20 failing jobs starts 20 sessions per agent. To run once when a whole workflow fails, use [workflow runs](#workflow-runs)
- A check on a commit that is no longer the head of its pull request starts nothing, so an agent never works on code that was already replaced

The session receives the check, its output, and the file annotations GitHub holds for it, plus the pull request it belongs to. For a GitHub Actions check it names the workflow run, so the session can read the job's log with `gh`.

The Ellipsis GitHub App needs the **Checks** permission on your installation. GitHub prompts the installation's owner to accept it, and until then Ellipsis receives no check events.

## Check suites

```yaml fragment
trigger:
  type: react
  check_suite:
    on: [failed]
    apps: [buildkite]
```

Runs once when every check Buildkite reported on a commit has finished and the suite failed. GitHub reports a suite only when it finishes, so `on` takes the finished values from [CI checks](#ci-checks) and `startup_failure`. `apps` matches the reporting app's slug, such as `github-actions`. `branch`, `for`, and the skip for a commit that is no longer the head of its pull request work as they do for checks. Needs the **Checks** permission.

## Workflow runs

```yaml fragment
trigger:
  type: react
  workflow_run:
    on: [failed]
    names: [CI]
    branch: [default]
```

Runs when the `CI` workflow fails on the default branch. `on` takes every [CI checks](#ci-checks) value and `startup_failure`. `queued` fires when a run is queued, `started` when it starts, and `action_required` when it waits for approval. `names` matches workflow names exactly or by a prefix ending in `*`. `branch`, `for`, and the skip for a commit that is no longer the head of its pull request work as they do for checks. The session can read the run's log with `gh`. Needs the **Actions** permission.

## Commit statuses

```yaml fragment
trigger:
  type: react
  status:
    on: [failed, errored]
    names: ['ci/circleci*']
```

Runs when a CircleCI status fails or errors. Some CI tools post commit statuses instead of checks. `on` takes `pending`, `passed`, `failed`, and `errored`. `names` matches the status context, its name on the pull request. `branch` matches when any branch GitHub lists for the commit matches. `for` and the skip for a commit that is no longer the head of its pull request work as they do for checks. Needs the **Commit statuses** permission.

## Releases

```yaml fragment
trigger:
  type: react
  release:
    on: [published]
    repositories: [api-repo]
    tag: ['v*']
    prerelease: false
```

Runs when a release whose tag starts with `v` is published in `api-repo`, skipping prereleases. A draft fires when it is published, not when it is saved; edits, deletions, and unpublishes never fire.

- `tag` matches tag names exactly or by a prefix ending in `*`; omit it to match every tag
- `prerelease: true` matches only prereleases and `false` only full releases; omit it to match both
- `for` is the release's author, so a release cut by CI or a release bot needs `bots` to include it

The session receives the release's tag, name, notes, target, author, and URL, and can read the release and the ones before it with `gh`.

## 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
      teams: [platform]
```

Filters only decide which events match. They don't grant access or choose which repositories the session checks out; the environment does.

- An empty repository list matches every installed repository
- Branch filters accept exact names, prefixes ending in `*`, and `default`
- Labels match when any listed label is present
- Paths are globs of files to match; `!` patterns aren't allowed
- `teams` lists GitHub team slugs of the installed organization, `platform` for `@org/platform`; the author must pass `users` and be on one of the teams, and bots never are
- Every matching agent runs

A team named in `teams` must exist when the file syncs; a missing team is a sync error, and a personal account installation can't use `teams`. Membership is checked against GitHub each time an event matches, and members of child teams count.

## Linear issues

```yaml fragment
trigger:
  type: react
  linear_issue:
    on: [opened]
```

Runs when a person creates a Linear issue; issues created by bots don't count. The session receives the issue. Name the repositories it needs in `session.environment`.

## Slack channels

```yaml fragment
trigger:
  type: react
  slack_channel: {}
```

Runs when someone creates a Slack channel. The session receives the channel's name and purpose. To answer messages instead, use [Slack mentions](/docs/integrations/slack#mention-routing).

## Sentry alerts

```yaml fragment
trigger:
  type: react
  sentry:
    on: [issue_alert]
    projects: [api]
```

Runs when an issue alert fires in the `api` Sentry project. `on` accepts `issue_alert` and `metric_alert`; omit `projects` to match every project. A [`sentry.yaml`](/docs/integrations/sentry) file, when present, replaces these triggers.

## Pause a trigger

```yaml fragment
trigger:
  type: react
  enabled: false
  linear_issue:
    on: [opened]
```

Pauses the trigger and keeps its definition in the file: new Linear issues no longer start sessions, and nothing else changes. Starts from the dashboard, CLI, and API still work, and open sessions keep taking follow-ups. The dashboard shows the agent as **Trigger paused**. Set `enabled` back to `true`, or remove the line, to resume. A paused cron resumes at its next scheduled time and doesn't make up the runs it missed. To pause the whole agent, including starts, set `ellipsis.enabled: false`.

## Mentions

`@ellipsis` mentions are configured separately, in [GitHub](/docs/integrations/github), [Slack](/docs/integrations/slack), and [Linear](/docs/integrations/linear) handler files.

---

# Code review

> One review per push, written by the reviewers you define.

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

A code review is a `kind: code_review` file that names which pull requests to review and a list of reviewers, each a [session](/docs/sessions) with its own prompt, model, [environment](/docs/environments), and [budget](/docs/budgets). Each push the file admits gets at most one review on the pull request, combining every reviewer's findings.

## Review every push

<span id="quick-start" />

[Install the Ellipsis GitHub App](https://app.ellipsis.dev/) on your repository, then commit this file to its default branch:

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

pull_requests:
  draft: false

reviewers:
  - name: bugs
    claude_code:
      prompt: Find bugs in this pull request.
      model: claude-opus-5-5
  - name: i18n
    paths: ['frontend/**']
    claude_code:
      prompt: Flag user-facing strings that bypass the translation layer.
      model: claude-sonnet-5-5

budget:
  session: 3
```

Open a pull request to see it work. Each push starts the reviewers whose `paths` match the new commits, and one review from `ellipsis-dev[bot]` lands with their comments. A reviewer only sees commits it has not reviewed before, and a comment on a line outside those commits is held back. A push with nothing new for any reviewer starts nothing. Every review, with each reviewer's comments and session, is listed under Code Review in the dashboard.

## What the review posts

Each reviewer marks every comment blocking or not. A review passes when no reviewer returned a blocking comment and fails otherwise. `output` sets the GitHub review submitted in each case:

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

reviewers:
  - name: bugs
    claude_code:
      prompt: Find bugs in this pull request. Mark a comment blocking only when the change must not merge as is.
      model: claude-opus-5-5

output:
  on_pass: approve
  on_fail: request_changes
  summary: true
```

`on_pass` is `silent` (nothing is posted unless a reviewer left a non-blocking comment, which posts as a comment), `comment`, or `approve`; `on_fail` is `comment` or `request_changes`. A failed review posts its `on_fail` event whether or not any of its comments lands on a changed line. A review in which a reviewer stopped early never approves, and a pull request the Ellipsis app opened itself gets a comment in every case, because GitHub refuses an approval or a request for changes from a pull request's own author. With `summary: true` every reviewer also returns a summary, and the review body opens with it, above the platform's own details; the prompt says what the summary should contain. Without `output`, a pass is silent and a fail is a comment.

## Configure a review

A file holds up to 64 reviewers, each with a unique `name`, and a repository holds one file. `pull_requests` takes the same filters as a pull request [trigger](/docs/agents/triggers#pull-requests). A reviewer takes the same `environment`, `skills`, and `permissions` blocks as an [agent session](/docs/agents/schema); its `budget` takes only `session`. Every reviewer's GitHub token reads the contents and pull requests of the repository under review; `permissions.github` can add read scopes and repositories, never write, because the platform posts the review. See the [Code review schema reference](/docs/code-review/schema) for complete examples and every field.

A file in the `.ellipsis` repository reviews every repository its `pull_requests.repositories` filter admits; a file in a repository reviews that repository and wins over the organization file. A file that breaks a limit or does not parse fails the sync, keeps the last good version running, and shows the error in the Ellipsis config check on the pull request.

## What happens when a reviewer fails

A review posts at most 64 comments, and each reviewer returns at most 64. Change these with `output.comments.max_per_review` and `output.comments.max_per_reviewer`, or set `comments.max` on one reviewer. A reviewer that returns more than its limit fails and contributes nothing. Comments past the review limit are kept with the review but not posted. A blocking comment on a line the push did not change is held back but still fails the review, which posts its `on_fail` event with the comments that did land. When no reviewer finishes, nothing is posted and nothing is marked reviewed. A reviewer that fails or runs out of budget contributes nothing; the review still posts with the other reviewers' comments, never as an approval, and that reviewer covers the same commits again on the next push. When GitHub rejects the review, the review ends with status `failed`, nothing posts, and every reviewer covers the same commits again on the next push.

---

# Code review schema reference

> Complete code review examples and field reference.

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

A code review file has 5 top-level blocks: `ellipsis`, optional `pull_requests`, `reviewers`, optional `output`, and optional `budget`. Set `ellipsis.kind` to `code_review`. A repository holds one file at `.ellipsis/code-review.yaml` on its default branch; the `.ellipsis` repository holds the organization file. Unknown fields fail the sync. See [Code review](/docs/code-review) for what a review posts and what happens when a reviewer fails.

## Review one organization

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

pull_requests:
  repositories:
    include: [api-repo, web-repo]
    exclude: [archived-repo]
  base: [main]
  draft: false
  for:
    users: true
    bots: false

reviewers:
  - name: bugs
    claude_code:
      prompt: Find bugs in this pull request.
      model: claude-opus-5-5

budget:
  session: 3
```

Committed to the `.ellipsis` repository, this reviews each push to a non-draft pull request by a human into `main` in `api-repo` or `web-repo`. `pull_requests` takes the same filters as a pull request [trigger](/docs/agents/triggers#pull-requests) without `on`; a repository's own file wins over this one.

## Approve when clean

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

reviewers:
  - name: review
    claude_code:
      prompt: |
        Review the pull request against the repository's contributing guide.
        Mark a comment blocking only when the change must not merge as is.
        In the summary, give the verdict, an overall score out of 4, and a
        table with one row per area you checked.
      model: claude-opus-5-5

output:
  on_pass: approve
  on_fail: request_changes
  summary: true
```

A push with no blocking comment gets an approval that opens with the reviewer's summary; a push with one gets a request for changes carrying the comments. Without `output`, a pass posts nothing and a fail posts a comment.

## Split reviewers by path

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

reviewers:
  - name: migrations
    paths: ['db/migrations/**']
    codex:
      prompt: Use the migration-checks skill to review each migration for locks and backfills.
      model: gpt-6-sol
    environment: api-environment
    skills:
      - path: skills/migration-checks
        repository:
          name: api-repo
    permissions:
      github:
        permissions: read_only
    budget:
      session: 5
  - name: tests
    claude_code:
      prompt: Check the changed code for missing test coverage and run the tests.
      model: claude-opus-5-5
    environment:
      repositories:
        - name: api-repo

budget:
  session: 2
```

A push that changes `db/migrations/` starts both reviewers; any other push starts only `tests`. The `migrations` reviewer runs in the `api-environment` [environment](/docs/environments) with the skill installed, reads issues as well as contents and pull requests, and may spend $5 per run; `tests` inherits the $2 cap. A reviewer takes the same `environment`, `skills`, and `permissions` blocks as an [agent session](/docs/agents/schema), except that `permissions.github` may only add read scopes. `read_only` reads every scope the GitHub App has.

## Fields

| Field | Type | Meaning |
| --- | --- | --- |
| `ellipsis` | `object`, required | Identifies the file. |
| `ellipsis.kind` | `string`, required | `code_review`. One of `code_review`. |
| `ellipsis.name` | `string` | A name for the file, unique within the account. |
| `ellipsis.description` | `string` | Description shown in the dashboard. |
| `ellipsis.enabled` | `boolean` | `false` pauses the file. Default `true`. |
| `ellipsis.metadata` | `object` | `labels` and `annotations` for your own use. |
| `ellipsis.metadata.labels` | `list of string` | Short tags. |
| `ellipsis.metadata.annotations` | `map of string` | Free text values by key. |
| `pull_requests` | `object` | Which pull requests to review. The same filters as a pull request [trigger](/docs/agents/triggers#pull-requests) without `on`. Default every pull request by a human author. |
| `pull_requests.repositories` | `list of string or object` | Repository names, or an object with `include` and `exclude` lists. Default every installed repository. |
| `pull_requests.repositories.include` | `list of string` | Repository names to match. Default every repository of the installation, including ones added later. |
| `pull_requests.repositories.exclude` | `list of string` | Repository names to skip, applied after `include`. |
| `pull_requests.base` | `list of string` | Base branches to match. Exact names, prefixes ending in `*`, and `default`. |
| `pull_requests.head` | `list of string` | Head branches to match. Exact names, prefixes ending in `*`, and `default`. |
| `pull_requests.draft` | `boolean` | `true` matches only draft pull requests, `false` only ready ones. Default both. |
| `pull_requests.labels` | `list of string` | Labels match when any listed label is present. |
| `pull_requests.paths` | `list of string` | Globs of changed files to match. `!` patterns aren't allowed. Default every change. |
| `pull_requests.for` | `object` | Which authors count. |
| `pull_requests.for.users` | `boolean, list of string, or object` | People. `true` is everyone, a list is those logins, `false` is no one, and an object sets `include` and `exclude`. Default `true`. |
| `pull_requests.for.users.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `pull_requests.for.users.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `pull_requests.for.bots` | `boolean, list of string, or object` | Bots. `true` is every bot, a list is those logins, `false` is none, and an object sets `include` and `exclude`. Default `false`. |
| `pull_requests.for.bots.include` | `boolean or list of string` | `true` is everyone, a list is those logins, `false` is no one. Default `true`. |
| `pull_requests.for.bots.exclude` | `list of string` | Logins to skip, applied after `include`. |
| `pull_requests.for.teams` | `list of string` | GitHub team slugs of the installed organization, such as `platform` for `@org/platform`. The author must also be on one of them. Bots never are. |
| `reviewers` | `list of object`, required | 1 to 64 reviewers. Each runs as its own session on every push with a change in its range. |
| `reviewers[].name` | `string`, required | Unique within the file. Heads the reviewer's section of the posted review. |
| `reviewers[].paths` | `list of string` | Glob patterns. The reviewer runs only when a changed file in its range matches. Default every change. |
| `reviewers[].claude_code` | `object` | Runs the session with [Claude Code](/docs/harnesses/claude). Exactly one of `claude_code` or `codex`. |
| `reviewers[].claude_code.prompt` | `string` | The task. |
| `reviewers[].claude_code.model` | `string`, required | A Claude Code model from [Models](/docs/models#current-support). |
| `reviewers[].claude_code.effort` | `string` | Reasoning effort, where the model supports it. One of `low`, `medium`, `high`, `xhigh`, `max`. |
| `reviewers[].claude_code.max_turns` | `integer` | The most turns the agent can take on each message, a whole number above 0. |
| `reviewers[].claude_code.fallback_model` | `string` | The model Claude Code switches to when `model` is overloaded. Default none. |
| `reviewers[].claude_code.settings` | `object` | A Claude Code `settings.json` in a repository, applied below the settings Ellipsis manages. Hooks stay disabled. |
| `reviewers[].claude_code.settings.path` | `string`, required | Path of the file, relative to the repository root. |
| `reviewers[].claude_code.settings.repository` | `object` | Where `path` resolves. Default the repository this file lives in. |
| `reviewers[].claude_code.settings.repository.name` | `string`, required | The repository name, without the owner. |
| `reviewers[].claude_code.settings.repository.owner` | `string` | The GitHub owner. Default your account. |
| `reviewers[].claude_code.settings.repository.ref` | `string` | Branch, tag, or commit. Default the default branch. |
| `reviewers[].codex` | `object` | Runs the session with [Codex](/docs/harnesses/codex). Exactly one of `claude_code` or `codex`. |
| `reviewers[].codex.prompt` | `string` | The task. |
| `reviewers[].codex.model` | `string`, required | `gpt-6.1-sol`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, or `gpt-5.6-sol`. |
| `reviewers[].codex.effort` | `string` | Reasoning effort. GPT-6.1 Sol and GPT-6 Astra don't accept `none`. Default `medium`. One of `none`, `low`, `medium`, `high`, `xhigh`, `max`. |
| `reviewers[].environment` | `string or object` | A saved environment name or an inline environment; see the [Environment schema reference](/docs/environments/schema). Default the built-in basic environment. |
| `reviewers[].permissions` | `object` | Ellipsis access as in an agent session, and GitHub read scopes on top of the floor every reviewer has: contents and pull requests of the repository under review. Write scopes fail the sync; see [Permissions](/docs/permissions). |
| `reviewers[].permissions.ellipsis` | `boolean or object` | Ellipsis API access for the session token. `true` grants everything a session token can do; a map narrows it per resource. Default `true`. |
| `reviewers[].permissions.github` | `object` | GitHub access for the session token. |
| `reviewers[].permissions.github.permissions` | `string or object` | `read_only`, or a map of GitHub permission names to levels. Default the installation's full permissions. |
| `reviewers[].permissions.github.repositories` | `list of string` | Repositories the token may reach. Default every repository of the installation. |
| `reviewers[].skills` | `list of object` | Skills from a repository, for Codex; see [Add a Codex skill](/docs/agents/schema#add-a-codex-skill). Up to 10. Default none. |
| `reviewers[].skills[].path` | `string`, required | Directory holding `SKILL.md`, relative to the repository root. |
| `reviewers[].skills[].repository` | `object` | Where `path` resolves. Default the repository this file lives in. |
| `reviewers[].skills[].repository.name` | `string`, required | The repository name, without the owner. |
| `reviewers[].skills[].repository.owner` | `string` | The GitHub owner. Default your account. |
| `reviewers[].skills[].repository.ref` | `string` | Branch, tag, or commit. Default the default branch. |
| `reviewers[].budget` | `object` | Spend limit for this reviewer. |
| `reviewers[].budget.session` | `number` | The most this reviewer may spend per run, in US dollars. Default `budget.session`. |
| `reviewers[].comments` | `object` | Comment limit for this reviewer. |
| `reviewers[].comments.max` | `integer` | The most comments this reviewer returns. A reviewer that returns more fails and contributes nothing. Default `output.comments.max_per_reviewer`. |
| `output` | `object` | What the review posts. A review passes when no reviewer returned a blocking comment and fails otherwise. |
| `output.on_pass` | `string` | The GitHub review submitted on a pass. Default `silent`. One of `silent` (Nothing is posted unless a reviewer left a suggestion, which posts as a comment), `comment` (A comment review), `approve` (An approval. A review in which a reviewer stopped early posts a comment instead). |
| `output.on_fail` | `string` | The GitHub review submitted on a fail. Default `comment`. One of `comment` (A comment review), `request_changes` (A review that requests changes). |
| `output.summary` | `boolean` | Ask every reviewer for a summary and open the review body with it, above the platform details. The prompt says what it contains. Default `false`. |
| `output.comments` | `object` | Comment limits for the review. |
| `output.comments.max_per_review` | `integer` | The most comments one review posts. Comments past it are kept with the review but not posted. Default `64`. |
| `output.comments.max_per_reviewer` | `integer` | The most comments each reviewer returns, unless the reviewer sets its own `comments.max`. Default `64`. |
| `budget` | `object` | Spend limits every reviewer inherits. |
| `budget.session` | `number` | The per-run cap every reviewer inherits, in US dollars. Default the account's default session budget; any value is clamped to the account and platform ceiling. See [Budgets](/docs/budgets). |

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

---

# Environments

> Set the repositories, setup scripts, and environment variables a session starts with.

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

An environment is the repositories, setup scripts, environment variables, and machine size a session starts with.

## Define an environment

Commit this file to 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, its npm dependencies installed, and the project built.

You can also create an environment on the dashboard's **Environments** page or with `POST /v1/environments`.

## Use an environment

Select it in **New session**, pass it to the CLI with `-e`, or name it in an API request:

```bash
ellipsis --model claude-opus-5-5 -e api-environment "Run the tests and fix one failure."
```

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

An agent names it in `session.environment`:

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  environment: api-environment
```

An unknown name fails the session at start. Without an environment, a session starts in a basic sandbox; there is no default environment.

## Check a change on a pull request

A pull request that changes an environment file gets an **Ellipsis environment** check. Ellipsis clones the environment's repositories, with the pull request's repository at the pull request's commit, runs all three hooks, and reports the result on the pull request. A failing check names the hook and shows the end of its output. Pull requests from forks are not checked.

## Setup and hooks

| Hook | Runs | Use for |
| --- | --- | --- |
| `hooks.build_base` | The first time, and when a file in its `inputs` changes | Installing dependencies and system tools |
| `hooks.after_checkout` | When a session needs a commit that isn't prepared yet | Building, generating code, starting services |
| `hooks.before_start` | Every time a session starts or resumes | Quick per-session setup |

Scripts run in `/sandbox` as the sandbox user, under `bash -eo pipefail`: the first command that fails, including one inside a pipeline, stops the script and fails the session. The session's error names the hook and shows the end of its output. `build_base` and `after_checkout` each have 10 minutes; `before_start` has 5. Shell exports don't carry between scripts; put shared values under `variables`.

## Reuse cached dependencies

Ellipsis saves the result of each setup script and reruns only what your change affects:

| You change | The next session runs |
| --- | --- |
| Nothing | `before_start` |
| A source file | `after_checkout`, then `before_start` |
| A file in `build_base.inputs` | All 3 scripts |
| The `build_base` script, a variable, or `compute` | All 3 scripts |

List every file your install reads in `build_base.inputs`, starting with the repository name. Include files such as `.npmrc` and workspace manifests: only the listed files exist while `build_base` runs. Globs, missing files, and symlinks fail the build. Omit `inputs` to rebuild on every commit, or set `inputs: []` when the install reads no repository files.

Make `after_checkout` safe to run again on a workspace that already has its output. Saved results keep files and running services, so start services in the background (for example, `docker compose up -d --wait`) and wait until they're ready before the script exits. Keep secret values out of files your scripts write.

A resumed session keeps its workspace, including uncommitted changes. Setup changes apply to new sessions.

To rebuild from scratch, send `"force_rebuild": true` when starting a session. The session's environment log shows each script's output.

See the [Environment schema reference](/docs/environments/schema) for Python, multi-repository, variable, and MCP server examples.

---

# Environment schema reference

> Complete environment examples and field reference.

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

Environment files live under `.ellipsis/` on the default branch, with `ellipsis.kind: environment` and a unique name. See [Environments](/docs/environments) for when each setup script runs.

## 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
```

`npm ci` reruns only when `package.json` or the lockfile changes. The build reruns for each new commit. `before_start` checks that dependencies exist each time a session 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
```

Each repository is checked out at `/sandbox/<name>`. A repository's `owner` defaults to your account.

## Add environment variables and secrets

Set a plain value with `value`. For a secret, [store it](/docs/secrets) first, then list its name without a `value`:

```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
```

`NODE_ENV` is `test`, and `NPM_TOKEN` comes from the stored secret, so its value never appears in git. Both are available to setup scripts and the agent.

- Names use letters, digits, and underscores, and can't start with a digit.
- A missing secret fails the session.
- Changing a variable reruns all setup scripts.
- Names starting with `ANTHROPIC_`, `OPENAI_`, `CODEX_`, or `CLAUDE_CODE_USE_`, and `CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_CONFIG_DIR`, and `ELLIPSIS_LLM_PROXY_URL`, are rejected.

## Install 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
```

The agent can run `jq`. Install system packages in `build_base` with `sudo`.

## Add an MCP server

List MCP servers under `mcp_servers`. Claude Code and Codex sessions both get their tools.

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

repositories:
  - name: api-repo

mcp_servers:
  - name: internal-tools
    url: https://tools.example.com/mcp
    headers:
      Authorization: Bearer ${TOOLS_TOKEN}
  - name: repo-tools
    command: node
    args: [/sandbox/api-repo/scripts/mcp-server.js]
```

Sessions using `api-with-tools` get the tools of both servers.

- A server with `url` is a remote server that speaks streamable HTTP. Replace the example URL with your server's.
- A server with `command` runs inside the sandbox, with optional `args` and `env`. Install anything it needs in `build_base`.
- `${NAME}` in `headers` or `env` reads the [secret](/docs/secrets) `NAME` when the session starts. It doesn't need a `variables` entry. A missing secret fails the session.
- To add the tools of a connected [Slack](/docs/integrations/slack) or [Linear](/docs/integrations/linear) integration, list it by name: `- slack` or `- linear`. Listing an integration that isn't connected fails the session at start.
- A repository's own `.mcp.json` is ignored.
- With Codex, a server that fails to start fails the turn.

## Inline environments

An agent can define its environment in `session.environment` instead of naming a saved one. Use the same fields without the `ellipsis` block:

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  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
```

## Fields

| Field | Type | Meaning |
| --- | --- | --- |
| `ellipsis` | `object`, required | Identifies the file. |
| `ellipsis.kind` | `string`, required | `environment`. One of `environment`. |
| `ellipsis.name` | `string` | Unique environment name. |
| `ellipsis.description` | `string` | Description shown in the dashboard. |
| `ellipsis.metadata` | `object` | `labels` and `annotations` for your own use. |
| `ellipsis.metadata.labels` | `list of string` | Short tags. |
| `ellipsis.metadata.annotations` | `map of string` | Free text values by key. |
| `repositories` | `list of object` | Each repository is checked out at `/sandbox/<name>`. |
| `repositories[].name` | `string`, required | The repository name, without the owner. |
| `repositories[].owner` | `string` | The GitHub owner. Default your account. |
| `repositories[].ref` | `string` | Branch, tag, or commit. Default the default branch. |
| `variables` | `list of object` | Environment variables for setup scripts and the agent. Changing a variable reruns all setup scripts. |
| `variables[].name` | `string`, required | Letters, digits, and underscores; can't start with a digit. Names starting with `ANTHROPIC_`, `OPENAI_`, `CODEX_`, or `CLAUDE_CODE_USE_` are rejected. |
| `variables[].value` | `string` | A plain value; omit it to use the stored [secret](/docs/secrets) of the same name. A missing secret fails the session. |
| `hooks` | `object` | Setup scripts; see [Setup and hooks](/docs/environments#setup-and-hooks). |
| `hooks.build_base` | `string or object` | Script or `{run, inputs}`; installs dependencies. A string reruns on any source change. |
| `hooks.build_base.run` | `string`, required | The script. |
| `hooks.build_base.inputs` | `list of string` | Exact files, starting with the repository name; omit for all source, or `[]` for none. |
| `hooks.after_checkout` | `string or object` | Script or `{run}`; prepares each new commit. |
| `hooks.after_checkout.run` | `string`, required | The script. |
| `hooks.before_start` | `string or object` | Script or `{run}`; runs whenever a session starts or resumes. |
| `hooks.before_start.run` | `string`, required | The script. |
| `compute` | `object` | The size of the environment. |
| `compute.cpu` | `integer` | 2 to 32 vCPUs. Default `2`. |
| `compute.memory` | `string` | 4096MB to 64GB. Accepts `MB` or `GB`. Default `4096MB`. |
| `compute.timeout` | `string` | 60 seconds to 1 hour. Accepts `s`, `m`, and `h`, including combinations such as `1h30m`. Default `1h`. |
| `mcp_servers` | `list of string or object` | `slack`, `linear`, remote servers, or local servers; see [Add an MCP server](/docs/environments/schema#add-an-mcp-server). |
| `mcp_servers[].name` | `string`, required | The server name. `slack` or `linear` attaches a connected integration. |
| `mcp_servers[].url` | `string` | A remote server that speaks streamable HTTP. |
| `mcp_servers[].headers` | `map of string` | Sent with every request. `${NAME}` reads the [secret](/docs/secrets) `NAME` when the session starts. |
| `mcp_servers[].command` | `string` | A local server run inside the environment. Install anything it needs in `build_base`. |
| `mcp_servers[].args` | `list of string` | Arguments for `command`. |
| `mcp_servers[].env` | `map of string` | Environment variables for `command`. `${NAME}` reads the [secret](/docs/secrets) `NAME` when the session starts. |

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

---

# Claude Code

> Models, options, and features for Claude Code.

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

Send a `claude_code` block to run a session with Claude Code:

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

In agent YAML, the same fields go under `session.claude_code`. The CLI picks the harness from `--model`.

## Options

| Field | Type | Meaning |
| --- | --- | --- |
| `prompt` | `string` | The task. |
| `model` | `string`, required | A Claude Code model from [Models](/docs/models#current-support). |
| `effort` | `string` | Reasoning effort, where the model supports it. One of `low`, `medium`, `high`, `xhigh`, `max`. |
| `max_turns` | `integer` | The most turns the agent can take on each message, a whole number above 0. |
| `fallback_model` | `string` | The model Claude Code switches to when `model` is overloaded. Default none. |
| `settings` | `object` | A Claude Code `settings.json` in a repository, applied below the settings Ellipsis manages. Hooks stay disabled. |
| `settings.path` | `string`, required | Path of the file, relative to the repository root. |
| `settings.repository` | `object` | Where `path` resolves. Default the repository this file lives in. |
| `settings.repository.name` | `string`, required | The repository name, without the owner. |
| `settings.repository.owner` | `string` | The GitHub owner. Default your account. |
| `settings.repository.ref` | `string` | Branch, tag, or commit. Default the default branch. |

| Model | Effort levels | Default effort |
| --- | --- | --- |
| Claude Opus 5.5, Sonnet 5.5, and Haiku 5.5 | All 5 | `medium` |
| Claude Fable 5.1 | All 5 | `high` |

## Features

| Feature | Support |
| --- | --- |
| Follow-up messages | All models |
| [MCP servers](/docs/environments/schema#add-an-mcp-server) | All models |
| [JSON output](/docs/agents/schema#typed-input-and-output) | All models |
| [Skills](/docs/agents/schema#add-a-codex-skill) | Not supported; use Codex |
| Images in messages | On credits; not on a Claude subscription |
| [Settings file](#options) | On credits; not on a Claude subscription |

## Subscription

To pay with your Claude plan instead of credits, [connect your Claude subscription](/docs/models#use-your-subscription). A session keeps the token it started with; a replaced token applies to new sessions.

---

# Codex

> Models, options, and features for Codex.

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

Send a `codex` block to run a session with Codex:

```json
{
  "codex": {
    "prompt": "Find and fix the failing test.",
    "model": "gpt-6.1-sol",
    "effort": "medium"
  }
}
```

In agent YAML, the same fields go under `session.codex`. The CLI picks the harness from `--model`:

```bash
el --model gpt-6-astra -e cloud_agent_environment "Find and fix the failing test."
```

## Options

| Field | Type | Meaning |
| --- | --- | --- |
| `prompt` | `string` | The task. |
| `model` | `string`, required | `gpt-6.1-sol`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, or `gpt-5.6-sol`. |
| `effort` | `string` | Reasoning effort. GPT-6.1 Sol and GPT-6 Astra don't accept `none`. Default `medium`. One of `none`, `low`, `medium`, `high`, `xhigh`, `max`. |

## Features

| Feature | Support |
| --- | --- |
| Follow-up messages | All models |
| [MCP servers](/docs/environments/schema#add-an-mcp-server) | All models |
| [JSON output](/docs/agents/schema#typed-input-and-output) | All models |
| [Skills](/docs/agents/schema#add-a-codex-skill) | All models |
| Images in messages | All models |

## Subscription

To pay with your ChatGPT plan instead of credits, [connect your Codex subscription](/docs/models#use-your-subscription). Ellipsis refreshes the login when needed.

---

# Harnesses

> Claude Code and Codex, the two coding agents Ellipsis runs.

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

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

---

# GitHub

> Connect repositories and configure the handler for GitHub mentions.

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

The Ellipsis GitHub App gives sessions access to your repositories and answers `@ellipsis` on issues and pull requests.

## Answer a mention

<span id="quick-start" />

1. [Install the Ellipsis GitHub App](https://app.ellipsis.dev/) and choose the repositories it can access.
2. Comment `@ellipsis` with a question on an issue or pull request in one of them.

Change the repository list later in GitHub's settings for installed apps.

## Repository access

The environment chooses which repositories a session checks out. Session permissions can further limit its GitHub token.

- [Environment schema reference](/docs/environments/schema) configures checkouts
- [Permissions](/docs/permissions) controls reads and writes
- [Triggers](/docs/agents/triggers) starts agents from repository events

## Mentions

Mention `@ellipsis` on an issue or pull request to start or continue a session. Without a `github.yaml`, the built-in handler answers.

To customize the handler, put `github.yaml` at the root of your organization's `.ellipsis` repository:

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

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

session:
  claude_code:
    model: claude-opus-5-5
    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 handler; other repositories use the built-in one. Set `github.repositories: ['*']` to use it everywhere; don't combine `'*'` with names.

The `session` block works like an [agent's](/docs/agents/schema#session-settings). The default-branch version is live, and an invalid edit keeps the last valid one. Set `ellipsis.enabled: false` to go back to the built-in handler. Only the copy in the `.ellipsis` repository counts.

## Who can mention Ellipsis

`github.mentions` controls which authors can summon Ellipsis and whether a comment starting with `...` or `…` counts as a mention:

```yaml title="github.yaml"
ellipsis:
  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:
    model: claude-opus-5-5
    prompt: Answer questions using the relevant code.
```

People can summon Ellipsis in public and private repositories; bots such as Dependabot and Renovate can't. A comment starting with `...` or `…` also counts.

These settings apply in every repository, including ones your handler doesn't cover and while it's disabled. Omitted fields use the defaults above, even without a `github.yaml`. The dashboard shows the settings in effect.

## Fields

| Field | Type | Meaning |
| --- | --- | --- |
| `ellipsis` | `object`, required | Identifies the file. |
| `ellipsis.kind` | `string`, required | `github`. One of `github`. |
| `ellipsis.name` | `string` | A name for the file, unique within the account. |
| `ellipsis.description` | `string` | Description shown in the dashboard. |
| `ellipsis.enabled` | `boolean` | `false` goes back to the built-in handler. Default `true`. |
| `ellipsis.metadata` | `object` | `labels` and `annotations` for your own use. |
| `ellipsis.metadata.labels` | `list of string` | Short tags. |
| `ellipsis.metadata.annotations` | `map of string` | Free text values by key. |
| `github` | `object`, required | Which mentions this handler answers. |
| `github.repositories` | `list of string` | Repository names, or `['*']` for every repository; don't combine `'*'` with names. |
| `github.mentions` | `object` | Who can summon Ellipsis. Applies in every repository, even while the handler is disabled. |
| `github.mentions.for` | `object` | Which authors count, by repository visibility. |
| `github.mentions.for.public` | `object` | Public repositories. |
| `github.mentions.for.public.users` | `boolean` | People can summon Ellipsis in public repositories. Default `true`. |
| `github.mentions.for.public.bots` | `boolean` | Bots can summon Ellipsis in public repositories. Default `false`. |
| `github.mentions.for.private` | `object` | Private repositories. |
| `github.mentions.for.private.users` | `boolean` | People can summon Ellipsis in private repositories. Default `true`. |
| `github.mentions.for.private.bots` | `boolean` | Bots can summon Ellipsis in private repositories. Default `false`. |
| `github.mentions.allow_leading_ellipsis` | `boolean` | A comment starting with `...` or `…` counts as a mention. Default `true`. |
| `github.mentions.require_leading_mention` | `boolean` | The mention must start the comment. Default `false`. |
| `session` | `object`, required | Works like an [agent's](/docs/agents/schema#session-settings) `session` block. |

---

# 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 (not generally released)

---

# Linear

> Connect Linear, answer Ellipsis mentions and delegations on issues, and give sessions Linear tools.

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

Ellipsis answers mentions on Linear issues, works issues delegated to it, and gives sessions Linear tools.

## Answer a mention

<span id="quick-start" />

1. Connect a workspace from **Integrations > Linear** in the dashboard.
2. Mention Ellipsis with a question in a comment on an issue.

## Delegate an issue

Set Ellipsis as the delegate on an issue to start a session on it. The session reads the issue and its comments, and replies in the issue's agent session. Other agents can delegate too, through the Linear API. If Ellipsis isn't offered as a delegate, reconnect Linear from **Integrations > Linear**.

## Agent access

A session gets Linear tools when its environment lists `linear` under [`mcp_servers`](/docs/environments/schema#add-an-mcp-server), or when it starts from Linear. A session that lists `linear` while Linear isn't connected fails at start.

## Mention routing

Mention Ellipsis in a comment on a Linear issue, picking it from the mention list, to start a session. Ellipsis answers in that comment's thread, and replies in the thread continue the same session. A typed `@ellipsis` starts nothing. If Ellipsis isn't in the mention list, reconnect Linear from **Integrations > Linear**. Delegations route the same way as mentions. Without a `linear.yaml`, the built-in handler answers. To customize it, put `linear.yaml` at the root of your organization's `.ellipsis` repository:

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

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

session:
  codex:
    model: gpt-6.1-sol
    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 handler answers mentions on issues in the `ENG` team or the `Website` project. Other issues use the built-in handler.

Set at least one of `linear.teams` or `linear.projects`. Don't mix `'*'` with team names. Names match regardless of case.

Linear issues aren't tied to a repository, so list the repositories the handler needs in `session.environment`, or name a saved environment that has them.

The default-branch version is live, and an invalid edit keeps the last valid one. Set `ellipsis.enabled: false`, or delete the file, to go back to the built-in handler. Only the copy in the `.ellipsis` repository counts.

## Issue events

To run an agent whenever someone creates an issue, use a [`linear_issue` trigger](/docs/agents/triggers#linear-issues).

## Fields

| Field | Type | Meaning |
| --- | --- | --- |
| `ellipsis` | `object`, required | Identifies the file. |
| `ellipsis.kind` | `string`, required | `linear`. One of `linear`. |
| `ellipsis.name` | `string` | A name for the file, unique within the account. |
| `ellipsis.description` | `string` | Description shown in the dashboard. |
| `ellipsis.enabled` | `boolean` | `false` goes back to the built-in handler. Default `true`. |
| `ellipsis.metadata` | `object` | `labels` and `annotations` for your own use. |
| `ellipsis.metadata.labels` | `list of string` | Short tags. |
| `ellipsis.metadata.annotations` | `map of string` | Free text values by key. |
| `linear` | `object`, required | Which issues this handler answers. Set at least one of `teams` or `projects`; don't mix `'*'` with team names. |
| `linear.teams` | `list of string` | Team keys or names, such as `ENG` or `Engineering`. `['*']` matches every issue. |
| `linear.projects` | `list of string` | Project names. Use `teams: ['*']` to match every issue. |
| `session` | `object`, required | Works like an [agent's](/docs/agents/schema#session-settings) `session` block. |

---

# Sentry

> Start an investigation when a Sentry alert fires, configured with sentry.yaml.

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

Sentry can start a session when an issue alert fires or a metric alert becomes critical. The Sentry integration is not generally released yet; contact [Support](/docs/support) for access.

## Connect and configure alerts

<span id="quick-start" />

1. Connect Sentry from the Ellipsis integrations settings and complete the installation in your Sentry organization.
2. In Sentry, set each project's issue or metric alert rule to notify the Ellipsis integration. Installing the integration alone sends no alerts.
3. Merge `sentry.yaml` at the root of your organization's `.ellipsis` repository.
4. Send a test alert from Sentry and check that a session starts and delivers its report.

Sentry credentials stay in the integration settings; `sentry.yaml` only chooses which alerts start a session and what the session does. Slack reports also need a connected Slack workspace.

## Route alerts

This handler investigates alerts from every project in one Sentry organization and posts a short Slack report for each:

```yaml
ellipsis:
  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-6.1-sol
  environment:
    repositories:
      - name: api-repo
    mcp_servers:
      - name: slack
  permissions:
    github:
      permissions: read_only
  budget:
    session: 2
```

An alert starts a session only when its organization, project, and alert type all match. Don't mix `'*'` with names in the same list.

## Delivery

An issue alert starts at most one investigation every 6 hours. A metric alert starts one only when it becomes critical, not on warning or resolved. Repeated deliveries of the same alert are ignored.

While `sentry.yaml` exists, it handles every Sentry alert, and agents with a `sentry` trigger don't run, even when the file is disabled. Delete the file to use those agents instead.

The default-branch version is live, and an invalid edit keeps the last valid one. Only the copy in the `.ellipsis` repository counts.

## Fields

| Field | Type | Meaning |
| --- | --- | --- |
| `ellipsis` | `object`, required | Identifies the file. |
| `ellipsis.kind` | `string`, required | `sentry`. One of `sentry`. |
| `ellipsis.name` | `string` | A name for the file, unique within the account. |
| `ellipsis.description` | `string` | Description shown in the dashboard. |
| `ellipsis.enabled` | `boolean` | `false` stops investigations. Default `true`. |
| `ellipsis.metadata` | `object` | `labels` and `annotations` for your own use. |
| `ellipsis.metadata.labels` | `list of string` | Short tags. |
| `ellipsis.metadata.annotations` | `map of string` | Free text values by key. |
| `sentry` | `object`, required | Which alerts start a session. An alert matches when its organization, project, and alert type all match; don't mix `'*'` with names in the same list. |
| `sentry.organizations` | `list of string` | Sentry organization slugs. Default `['*']`. |
| `sentry.projects` | `list of string`, required | Project slugs, or `['*']` for every project. |
| `sentry.on` | `list of string` | Which alerts start a session. Default `[issue_alert, metric_alert]`. One of `issue_alert` (An issue alert fires), `metric_alert` (A metric alert becomes critical). |
| `session` | `object`, required | Works like an [agent's](/docs/agents/schema#session-settings) `session` block, including `budget`. |

---

# Slack

> Connect Slack, answer @ellipsis mentions, and give sessions Slack tools.

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

Ellipsis answers `@ellipsis` mentions in Slack channels and gives sessions Slack tools.

## Answer a mention

<span id="quick-start" />

1. Connect a workspace from **Integrations > Slack** in the dashboard.
2. Invite Ellipsis to any private channel it should read or answer in.
3. Mention `@ellipsis` with a question in a channel.

## Agent access

A session gets Slack tools when its environment lists `slack` under [`mcp_servers`](/docs/environments/schema#add-an-mcp-server), or when it starts from Slack. After you remove the connection, a session that lists `slack` fails at start.

## Operations channel

Under **Your channels**, **Operations Channel** creates `#ellipsis-operations`. Ellipsis posts [budget alerts](/docs/budgets#when-a-limit-is-reached) there.

## Mention routing

Mention `@ellipsis` in a channel or direct message to start a session in that thread. Without a `slack.yaml`, the built-in handler answers. To customize it, put `slack.yaml` at the root of your organization's `.ellipsis` repository:

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

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

session:
  codex:
    model: gpt-6.1-sol
    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 handler answers mentions in `#engineering` and `#support`, and all direct messages. Other channels use the built-in handler.

Set at least one of `slack.channels` or `slack.direct_messages`. Don't mix `'*'` with names in the same list. Names match regardless of case.

The default-branch version is live, and an invalid edit keeps the last valid one. Set `ellipsis.enabled: false`, or delete the file, to go back to the built-in handler. Only the copy in the `.ellipsis` repository counts.

A [`slack_channel` trigger](/docs/agents/triggers#slack-channels) is different: it runs an agent when a channel is created.

## Fields

| Field | Type | Meaning |
| --- | --- | --- |
| `ellipsis` | `object`, required | Identifies the file. |
| `ellipsis.kind` | `string`, required | `slack`. One of `slack`. |
| `ellipsis.name` | `string` | A name for the file, unique within the account. |
| `ellipsis.description` | `string` | Description shown in the dashboard. |
| `ellipsis.enabled` | `boolean` | `false` goes back to the built-in handler. Default `true`. |
| `ellipsis.metadata` | `object` | `labels` and `annotations` for your own use. |
| `ellipsis.metadata.labels` | `list of string` | Short tags. |
| `ellipsis.metadata.annotations` | `map of string` | Free text values by key. |
| `slack` | `object`, required | Which conversations this handler answers. Set at least one of `channels` or `direct_messages`; don't mix `'*'` with names in the same list. |
| `slack.channels` | `list of string` | Channel names, with or without `#`. `['*']` matches every channel. |
| `slack.direct_messages` | `list of string` | GitHub logins of the people whose direct messages it answers, such as `['priya-shah']`. `['*']` matches everyone, including people without a linked GitHub account. |
| `session` | `object`, required | Works like an [agent's](/docs/agents/schema#session-settings) `session` block. |

---

# Sessions

> Start a coding task, follow it, send follow-ups, and review the changes.

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

A session is a conversation with [Claude Code or Codex](/docs/harnesses) in its own cloud environment. The agent keeps working when you close the page or disconnect.

## Start a session

In the dashboard, describe the task on **Home** and click **New session**. From a terminal:

```bash
ellipsis --model claude-opus-5-5 -e cloud_agent_environment "Add an empty-body test in api-repo. Run it; do not commit."
```

From code:

```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={"session": 5},
    claude_code={
        "model": "claude-opus-5-5",
        "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: { session: 5 },
  claude_code: {
    model: 'claude-opus-5-5',
    prompt:
      'Add an empty-body test in api-repo. Run it; do not commit.',
  },
});
console.log(handle.id);
```

Replace `cloud_agent_environment` and `api-repo` with your [environment](/docs/environments) and repository; without an environment, the session uses the default environment. `budget` caps the session at $5. Keep the session ID to check on it later. To set up the client, see the [Python](/docs/api/python-sdk) or [TypeScript](/docs/api/typescript-sdk) SDK and [API authentication](/docs/api/authentication).

## Follow the work

The dashboard and the CLI show messages and tool calls as they happen. To reattach the CLI to a running session, run `ellipsis session get <session-id> --watch`. From code, wait for the turn that answers your prompt:

```python
session = handle.wait(timeout=900)
print(session.turn.status, session.turn.reason, session.turn.detail)

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.turn?.status, session.turn?.reason, session.turn?.detail);

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

`wait()` returns when the turn reaches a final status: `completed`, `failed`, `stopped`, or `cancelled`. Check `turn.status` before treating the task as done; `reason` and `detail` explain a `failed` or `cancelled` turn. A timeout stops your client from waiting, not the agent. To stream messages as they happen, see the [Python](/docs/api/python-sdk#stream-a-session) or [TypeScript](/docs/api/typescript-sdk#stream-a-session) SDK; for what each status means, see [Lifecycle](/docs/sessions/lifecycle#turn).

### Retrieve a session

```python
handle = client.sessions.handle("your-session-id")
print(handle.session.conversation.state, handle.session.turn)
```

```typescript
const handle = await client.sessions.handle('your-session-id');
console.log(handle.session.conversation.state, handle.session.turn);
```

Get a handle by ID at any time, for example after your application restarts. `turn` is the turn in progress, or the latest one when none is running.

## Send a follow-up

<span id="conversations" />

In the dashboard, type in **Reply to the agent...** and click **Send**. In the CLI, type in the session view. From code:

```python
message = handle.send("Add a test for an invalid content type too.")
session = handle.wait(timeout=900)
print(message.turn_id, session.turn.status)
```

```typescript
const message = await handle.send(
  'Add a test for an invalid content type too.'
);
const session = await handle.wait({ timeoutMs: 900_000 });
console.log(message.turn_id, session.turn?.status);
```

A follow-up continues the same conversation and workspace. The message gets its turn the moment it is received, and `wait()` then waits on that turn; a message sent while a turn is running is answered after it. Only the person who started a session can message it. Sessions started by a mention take replies in their GitHub, Slack, or Linear thread. A closed session can't take follow-ups; `conversation.prompting` says whether a message would be accepted, see [Lifecycle](/docs/sessions/lifecycle#conversation).

## Run a one-off task

<span id="one-shot-tasks" />
<span id="from-scripts" />

```python
task = client.sessions.run(
    environment="cloud_agent_environment",
    claude_code={
        "model": "claude-opus-5-5",
        "prompt": "Run request-validation tests in api-repo and report failures.",
    },
    conversation={"interactive": False},
)
result = task.wait(timeout=900)
print(task.id, result.turn.status, result.conversation.state)
```

```typescript
const task = await client.sessions.run({
  environment: 'cloud_agent_environment',
  claude_code: {
    model: 'claude-opus-5-5',
    prompt:
      'Run request-validation tests in api-repo and report failures.',
  },
  conversation: { interactive: false },
});
const result = await task.wait({ timeoutMs: 900_000 });
console.log(task.id, result.turn?.status, result.conversation.state);
```

Set `conversation.interactive` to `false` when you won't send follow-ups. The conversation closes when its turn ends and its environment is deleted; its messages and results stay available. To save a task and run it again or on a schedule, use [Agents](/docs/agents).

## 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);
}
```

Get the session's [uncommitted changes](/docs/api/sessions/get-sessions-id-diff) and the [commits and pull requests](/docs/api/sessions/get-sessions-id-git) it made. Files left out of the diff are listed in `omitted_paths`.

### Cost and records

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

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

`cost.total` and `budget` are in thousandths of a cent, so divide by 100,000 for dollars. Follow-ups share the budget. Each turn carries its own `cost` and `tokens`; list them with [`GET /v1/sessions/{id}/turns`](/docs/api/sessions/get-sessions-id-turns). See [Pricing](/docs/pricing) for rates, or [download the session history](/docs/api/sessions/get-sessions-id-download).

## Stop a session

Click **Stop** in the dashboard. In the CLI, type `/stop` in the session view or run `ellipsis session stop <session-id>`. From code:

```python
session = handle.stop()
print(session.turn.status, session.turn.stopped)
```

```typescript
const session = await handle.stop();
console.log(session.turn?.status, session.turn?.stopped);
```

Stopping ends the running turn with `stopped`, not the conversation. The session can still take follow-ups. Stopping a session with no turn queued, preparing, or running fails with `409`. Disconnecting doesn't stop the agent.

---

# Lifecycle

> Read a session's conversation and turn, and know when the message you sent is answered.

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

A session is a conversation with an agent. The session object reports it in two parts: `conversation` says whether the session can take more messages, and `turn` says what is happening to the latest message. A turn is one message and the agent's answer to it. The message you sent is answered when its turn reaches a final status.

## Conversation

| Field | Meaning |
| --- | --- |
| `conversation.state` | `open` while the session can take messages; `closed` is permanent |
| `conversation.interactive` | Whether the session stays open after its first turn; set it when [starting a session](/docs/sessions#run-a-one-off-task), on an agent, or when [starting an agent session](/docs/agents#override-settings-for-a-session) |
| `conversation.warm` | Whether an agent is ready to answer the next message right away; when `false`, the next message first prepares an environment, which takes longer |
| `conversation.prompting` | Whether a message you send now would be accepted: `enabled`, and when it is `false`, `blocked_reason` and `detail` say why |

A session started with `interactive: false` closes when its turn ends. After that, start a new session. `warm` is a hint for what to show while a message is `queued` or `preparing`, never something to branch on. `prompting.detail` is a sentence you can show as is. `blocked_reason` takes these values.

| Reason | Meaning |
| --- | --- |
| `closed` | The conversation is closed |
| `mention_surface` | The session was started by a mention; reply on the surface `surface_name` names (GitHub, Slack, or Linear) |
| `non_interactive` | The session was started with `interactive: false` |
| `harness_single_turn` | The harness takes one message per session |
| `budget_exhausted` | The session spent its [budget](/docs/budgets) |

`POST /v1/sessions/{id}/messages` fails with `409` while `prompting.enabled` is `false`.

## Turn

<span id="statuses" />

| Status | Meaning |
| --- | --- |
| `queued` | The message was received and waits to start, behind another turn or until a session ends when your account has its [limit](/docs/organization#platform-allowances) of sessions alive, which `detail` then says |
| `preparing` | The environment for the message is being set up |
| `running` | The agent is working on the message |
| `completed` | The agent finished |
| `failed` | The turn ended with an error; `reason` and `detail` explain |
| `stopped` | Someone stopped the turn; `stopped.at` and `stopped.by` say when and who |
| `cancelled` | The turn was refused before the agent started; `reason` and `detail` explain |

`completed`, `failed`, `stopped`, and `cancelled` are final. A final turn ends that turn, not the conversation: an interactive session still takes follow-ups while `prompting.enabled` is `true`. The other turn fields are `id`, `index` (its position in the session, from 0), `created_at` (when the message was received), `started_at`, `ended_at`, `cost`, and `tokens`.

`reason` is set only on `failed` and `cancelled` turns:

| Reason | Meaning |
| --- | --- |
| `error` | The agent ended with an error |
| `tool_call_failed` | The agent process failed or stalled before finishing |
| `budget_hit` | The session [budget](/docs/budgets) or a spend limit was reached |
| `payment_required` | The account has no credit or a subscription problem |
| `blocked` | The account or user is blocked |
| `contact_email_required` | The account needs a contact email |
| `lifecycle_hook_failed` | An environment [hook](/docs/environments#setup-and-hooks) exited with a nonzero status |
| `missing_repo_access` | The GitHub installation can't access a repository the session needs |
| `missing_token_permissions` | The GitHub installation lacks a permission the session needs |
| `missing_environment_variables` | An environment variable has no value |
| `missing_github_integration` | The account has no GitHub installation |
| `agent_unavailable` | The saved agent was deleted or disabled |
| `upstream_unavailable` | The model provider was rate limited or down after retries, or the Claude or Codex subscription the session uses is unavailable |
| `unsupported_configuration` | The harness, model, and settings can't be combined |
| `execution_disabled` | Sessions from this source are disabled |
| `interrupted` | The turn lost its agent before answering; the message is queued again on a new turn |

`detail` is a sentence you can show as is.

## Wait for the answer

<span id="check-the-status" />

The message you sent is answered when the turn with its `turn_id` reaches a final status. `POST /v1/sessions` returns the session with the turn for its prompt in `turn`; `POST /v1/sessions/{id}/messages` returns the `message` and its `turn`. Poll [`GET /v1/sessions/{session_id}/turns/{id}`](/docs/api/sessions/get-sessions-session_id-turns-id) or watch the stream's `session` frames until `status` is final. Waiting for the conversation to close, or for it to go quiet, is wrong: an open conversation stays open between turns.

The SDK handle's `wait()` does this for you. It returns when the turn it waits on ends: the session's opening turn, then each turn a `send()` creates.

```python
session = handle.wait(timeout=900)
turn = session.turn
print(turn.status, turn.reason, turn.detail)
print(session.conversation.state, session.conversation.prompting.enabled)
```

```typescript
const session = await handle.wait({ timeoutMs: 900_000 });
const turn = session.turn;
console.log(turn?.status, turn?.reason, turn?.detail);
console.log(session.conversation.state, session.conversation.prompting.enabled);
```

`session.turn` is the turn in progress, or the latest one when none is running, and null until the session has a message. [`GET /v1/sessions/{id}/turns`](/docs/api/sessions/get-sessions-id-turns) lists every turn and message, oldest first.

## Follow the stream

```python
from ellipsis.frames import StreamFrame

def on_frame(frame: StreamFrame):
    if frame.type in ("snapshot", "session"):
        turn = frame.session.turn
        if turn is not None:
            print(turn.index, turn.status)
        print(frame.session.conversation.state)
    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') {
    const turn = frame.session.turn;
    if (turn) console.log(turn.index, turn.status);
    console.log(frame.session.conversation.state);
  } 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 in the [Python](/docs/api/python-sdk#stream-a-session) or [TypeScript](/docs/api/typescript-sdk#stream-a-session) SDK. `snapshot` sends the current session, `session` replaces it whenever the turn, the conversation, or the cost changes, `records_append` adds saved records in `feed_seq` order, and `done` means the conversation closed. `delta` frames carry live partial output that isn't saved. A [`turn_ended`](/docs/api/session-events#turn_ended) record carries the same `status`, `reason`, and `detail` as the turn. Frames can repeat, so ignore duplicates and types you don't recognize. See [Session events](/docs/api/session-events) for every event.

A session keeps the Claude or Codex subscription it started with; connecting a different one affects only new 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.
Session 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": {
      "day": int,
      "month": int,
      "week": int
    },
    "percent_thresholds": [
      int
    ]
  },
  "as_of": str,
  "credit_balance": int,
  "credit_exhausted": bool,
  "developer_limits": {
    "defaults": [
      {
        "limit": int,
        "platform_max": int,
        "window_days": int
      }
    ],
    "developers": [
      {
        "attribution_id": str,
        "attribution_type": str,
        "avatar_url": str,
        "developer_key": str,
        "login": str,
        "name": str,
        "windows": [
          {
            "exhausted": bool,
            "limit": int,
            "override": int,
            "remaining": int,
            "spent": int,
            "window_days": int
          }
        ]
      }
    ],
    "enabled": bool
  },
  "per_run": {
    "budget": int,
    "ceiling": int,
    "platform_max": int
  },
  "policy": {
    "account": {
      "day": int,
      "month": int,
      "week": int
    },
    "default_session": int,
    "developer_defaults": {
      "day": int,
      "month": int,
      "week": int
    },
    "developer_overrides": {
      "[str]": {
        "day": int,
        "month": int,
        "week": int
      }
    }
  },
  "windows": [
    {
      "exhausted": bool,
      "fraction_used": float,
      "limit": int,
      "platform_max": int,
      "remaining": int,
      "spent": int,
      "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": {
                "day": {
                  "anyOf": [
                    {
                      "minimum": 100000,
                      "multipleOf": 1000,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "month": {
                  "anyOf": [
                    {
                      "minimum": 100000,
                      "multipleOf": 1000,
                      "type": "integer"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "week": {
                  "anyOf": [
                    {
                      "minimum": 100000,
                      "multipleOf": 1000,
                      "type": "integer"
                    },
                    {
                      "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": {
      "type": "integer"
    },
    "credit_exhausted": {
      "type": "boolean"
    },
    "developer_limits": {
      "properties": {
        "defaults": {
          "items": {
            "properties": {
              "limit": {
                "type": "integer"
              },
              "platform_max": {
                "type": "integer"
              },
              "window_days": {
                "type": "integer"
              }
            },
            "required": [
              "window_days",
              "limit",
              "platform_max"
            ],
            "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": {
                      "type": "object"
                    },
                    "override": {
                      "type": "object"
                    },
                    "remaining": {
                      "type": "object"
                    },
                    "spent": {
                      "type": "integer"
                    },
                    "window_days": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "window_days",
                    "spent",
                    "limit",
                    "override",
                    "remaining",
                    "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": {
          "type": "integer"
        },
        "ceiling": {
          "type": "integer"
        },
        "platform_max": {
          "type": "integer"
        }
      },
      "required": [
        "budget",
        "platform_max",
        "ceiling"
      ],
      "type": "object"
    },
    "policy": {
      "additionalProperties": false,
      "properties": {
        "account": {
          "additionalProperties": false,
          "properties": {
            "day": {
              "minimum": 100000,
              "multipleOf": 1000,
              "type": "integer"
            },
            "month": {
              "minimum": 100000,
              "multipleOf": 1000,
              "type": "integer"
            },
            "week": {
              "minimum": 100000,
              "multipleOf": 1000,
              "type": "integer"
            }
          },
          "required": [
            "day",
            "week",
            "month"
          ],
          "type": "object"
        },
        "default_session": {
          "minimum": 100000,
          "multipleOf": 1000,
          "type": "integer"
        },
        "developer_defaults": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "day": {
                  "minimum": 100000,
                  "multipleOf": 1000,
                  "type": "integer"
                },
                "month": {
                  "minimum": 100000,
                  "multipleOf": 1000,
                  "type": "integer"
                },
                "week": {
                  "minimum": 100000,
                  "multipleOf": 1000,
                  "type": "integer"
                }
              },
              "required": [
                "day",
                "week",
                "month"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "developer_overrides": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "day": {
                "anyOf": [
                  {
                    "minimum": 100000,
                    "multipleOf": 1000,
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "month": {
                "anyOf": [
                  {
                    "minimum": 100000,
                    "multipleOf": 1000,
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "week": {
                "anyOf": [
                  {
                    "minimum": 100000,
                    "multipleOf": 1000,
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "type": "object"
          },
          "type": "object"
        }
      },
      "required": [
        "default_session",
        "account",
        "developer_defaults",
        "developer_overrides"
      ],
      "type": "object"
    },
    "windows": {
      "items": {
        "properties": {
          "exhausted": {
            "type": "boolean"
          },
          "fraction_used": {
            "type": "number"
          },
          "limit": {
            "type": "integer"
          },
          "platform_max": {
            "type": "integer"
          },
          "remaining": {
            "type": "integer"
          },
          "spent": {
            "type": "integer"
          },
          "window_days": {
            "type": "integer"
          }
        },
        "required": [
          "window_days",
          "spent",
          "limit",
          "remaining",
          "fraction_used",
          "exhausted",
          "platform_max"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "as_of",
    "credit_balance",
    "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.
Session 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": [
    {
      "aliases": [
        str
      ],
      "capabilities": [
        str
      ],
      "default_reasoning_effort": str, # str | null
      "display_name": str,
      "harness": str,
      "id": str,
      "manufacturer": str,
      "rate_card": {
        "cache_read_per_1m_tokens": int,
        "cache_write_1h_per_1m_tokens": int,
        "cache_write_5m_per_1m_tokens": int,
        "input_per_1m_tokens": int,
        "output_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": {
          "aliases": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "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"
          },
          "manufacturer": {
            "enum": [
              "anthropic",
              "openai"
            ],
            "type": "string"
          },
          "rate_card": {
            "properties": {
              "cache_read_per_1m_tokens": {
                "type": "integer"
              },
              "cache_write_1h_per_1m_tokens": {
                "type": "integer"
              },
              "cache_write_5m_per_1m_tokens": {
                "type": "integer"
              },
              "input_per_1m_tokens": {
                "type": "integer"
              },
              "output_per_1m_tokens": {
                "type": "integer"
              }
            },
            "required": [
              "input_per_1m_tokens",
              "cache_write_5m_per_1m_tokens",
              "cache_write_1h_per_1m_tokens",
              "cache_read_per_1m_tokens",
              "output_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",
          "aliases",
          "display_name",
          "harness",
          "capabilities",
          "manufacturer",
          "rate_card"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "models"
  ],
  "type": "object"
}
```

---

# Get usage

> Read usage for a UTC calendar month, split by billing source.

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

## GET /v1/account/usage

Read usage for a UTC calendar month, split by billing source.

Required permissions: read:account.
API key: Supported.
CLI user token: Supported.
Session 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_sessions": {
    "cost": {
      "charged": int,
      "cpu": int,
      "fee": int,
      "llm": {
        "all": {
          "claude_subscription": int,
          "codex_subscription": int,
          "platform": int,
          "total": int
        },
        "by_model": [
          {
            "claude_subscription": int,
            "codex_subscription": int,
            "model": str,
            "platform": int,
            "total": int
          }
        ]
      },
      "memory": int,
      "total": int
    },
    "tokens": {
      "all": {
        "cache_creation": int,
        "cache_read": int,
        "input": int,
        "output": int,
        "total": int
      },
      "by_model": [
        {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "model": str,
          "output": int,
          "total": int
        }
      ]
    }
  },
  "billing_periods": [
    {
      "is_current": bool,
      "period_end": str,
      "period_start": str
    }
  ],
  "by_billing_source": [
    {
      "billing_source": str,
      "charged": int,
      "pending_requests": int,
      "requests": int,
      "token_charged": int,
      "token_cost": int,
      "tokens": int,
      "unresolved_requests": int
    }
  ],
  "by_day": [
    {
      "cost": {
        "charged": int,
        "cpu": int,
        "fee": int,
        "llm": {
          "all": {
            "claude_subscription": int,
            "codex_subscription": int,
            "platform": int,
            "total": int
          },
          "by_model": [
            {
              "claude_subscription": int,
              "codex_subscription": int,
              "model": str,
              "platform": int,
              "total": int
            }
          ]
        },
        "memory": int,
        "total": int
      },
      "date": str,
      "tokens": {
        "all": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "output": int,
          "total": int
        },
        "by_model": [
          {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": int
          }
        ]
      }
    }
  ],
  "by_developer": [
    {
      "attribution_id": str,
      "attribution_login": str,
      "attribution_type": str,
      "cost": {
        "charged": int,
        "cpu": int,
        "fee": int,
        "llm": {
          "all": {
            "claude_subscription": int,
            "codex_subscription": int,
            "platform": int,
            "total": int
          },
          "by_model": [
            {
              "claude_subscription": int,
              "codex_subscription": int,
              "model": str,
              "platform": int,
              "total": int
            }
          ]
        },
        "memory": int,
        "total": int
      },
      "runs": int,
      "tokens": {
        "all": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "output": int,
          "total": int
        },
        "by_model": [
          {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": int
          }
        ]
      }
    }
  ],
  "cost": {
    "charged": int,
    "cpu": int,
    "fee": int,
    "llm": {
      "all": {
        "claude_subscription": int,
        "codex_subscription": int,
        "platform": int,
        "total": int
      },
      "by_model": [
        {
          "claude_subscription": int,
          "codex_subscription": int,
          "model": str,
          "platform": int,
          "total": int
        }
      ]
    },
    "memory": int,
    "total": int
  },
  "period_end": str,
  "period_start": str,
  "prior_cost": {
    "charged": int,
    "cpu": int,
    "fee": int,
    "llm": {
      "all": {
        "claude_subscription": int,
        "codex_subscription": int,
        "platform": int,
        "total": int
      },
      "by_model": [
        {
          "claude_subscription": int,
          "codex_subscription": int,
          "model": str,
          "platform": int,
          "total": int
        }
      ]
    },
    "memory": int,
    "total": int
  },
  "prior_tokens": {
    "all": {
      "cache_creation": int,
      "cache_read": int,
      "input": int,
      "output": int,
      "total": int
    },
    "by_model": [
      {
        "cache_creation": int,
        "cache_read": int,
        "input": int,
        "model": str,
        "output": int,
        "total": int
      }
    ]
  },
  "tokens": {
    "all": {
      "cache_creation": int,
      "cache_read": int,
      "input": int,
      "output": int,
      "total": int
    },
    "by_model": [
      {
        "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.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_sessions": {
      "properties": {
        "cost": {
          "properties": {
            "charged": {
              "default": 0,
              "type": "integer"
            },
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "properties": {
                "all": {
                  "properties": {
                    "claude_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "codex_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "platform": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "claude_subscription",
                    "codex_subscription",
                    "platform",
                    "total"
                  ],
                  "type": "object"
                },
                "by_model": {
                  "items": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "model": {
                        "type": "string"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "model",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "all",
                "by_model"
              ],
              "type": "object"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "charged",
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "tokens": {
          "properties": {
            "all": {
              "properties": {
                "cache_creation": {
                  "default": 0,
                  "type": "integer"
                },
                "cache_read": {
                  "default": 0,
                  "type": "integer"
                },
                "input": {
                  "default": 0,
                  "type": "integer"
                },
                "output": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "cache_creation",
                "cache_read",
                "input",
                "output",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "model",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        }
      },
      "required": [
        "cost",
        "tokens"
      ],
      "type": "object"
    },
    "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_billing_source": {
      "items": {
        "properties": {
          "billing_source": {
            "enum": [
              "platform",
              "claude_subscription",
              "codex_subscription",
              "unknown"
            ],
            "type": "string"
          },
          "charged": {
            "default": 0,
            "type": "integer"
          },
          "pending_requests": {
            "default": 0,
            "type": "integer"
          },
          "requests": {
            "default": 0,
            "type": "integer"
          },
          "token_charged": {
            "default": 0,
            "type": "integer"
          },
          "token_cost": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "tokens": {
            "default": 0,
            "type": "integer"
          },
          "unresolved_requests": {
            "default": 0,
            "type": "integer"
          }
        },
        "required": [
          "billing_source"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "by_day": {
      "items": {
        "properties": {
          "cost": {
            "properties": {
              "charged": {
                "default": 0,
                "type": "integer"
              },
              "cpu": {
                "default": 0,
                "type": "integer"
              },
              "fee": {
                "default": 0,
                "type": "integer"
              },
              "llm": {
                "properties": {
                  "all": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "by_model": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "all",
                  "by_model"
                ],
                "type": "object"
              },
              "memory": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "charged",
              "cpu",
              "fee",
              "llm",
              "memory",
              "total"
            ],
            "type": "object"
          },
          "date": {
            "type": "string"
          },
          "tokens": {
            "properties": {
              "all": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "by_model": {
                "items": {
                  "properties": {
                    "cache_creation": {
                      "type": "integer"
                    },
                    "cache_read": {
                      "type": "integer"
                    },
                    "input": {
                      "type": "integer"
                    },
                    "model": {
                      "type": "string"
                    },
                    "output": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "cache_creation",
                    "cache_read",
                    "input",
                    "model",
                    "output",
                    "total"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "all",
              "by_model"
            ],
            "type": "object"
          }
        },
        "required": [
          "date",
          "cost",
          "tokens"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "by_developer": {
      "items": {
        "properties": {
          "attribution_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "attribution_login": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "attribution_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "cost": {
            "properties": {
              "charged": {
                "default": 0,
                "type": "integer"
              },
              "cpu": {
                "default": 0,
                "type": "integer"
              },
              "fee": {
                "default": 0,
                "type": "integer"
              },
              "llm": {
                "properties": {
                  "all": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "by_model": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "all",
                  "by_model"
                ],
                "type": "object"
              },
              "memory": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "charged",
              "cpu",
              "fee",
              "llm",
              "memory",
              "total"
            ],
            "type": "object"
          },
          "runs": {
            "type": "integer"
          },
          "tokens": {
            "properties": {
              "all": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "by_model": {
                "items": {
                  "properties": {
                    "cache_creation": {
                      "type": "integer"
                    },
                    "cache_read": {
                      "type": "integer"
                    },
                    "input": {
                      "type": "integer"
                    },
                    "model": {
                      "type": "string"
                    },
                    "output": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "cache_creation",
                    "cache_read",
                    "input",
                    "model",
                    "output",
                    "total"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "all",
              "by_model"
            ],
            "type": "object"
          }
        },
        "required": [
          "attribution_type",
          "attribution_id",
          "attribution_login",
          "runs",
          "cost",
          "tokens"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "cost": {
      "properties": {
        "charged": {
          "default": 0,
          "type": "integer"
        },
        "cpu": {
          "default": 0,
          "type": "integer"
        },
        "fee": {
          "default": 0,
          "type": "integer"
        },
        "llm": {
          "properties": {
            "all": {
              "properties": {
                "claude_subscription": {
                  "default": 0,
                  "type": "integer"
                },
                "codex_subscription": {
                  "default": 0,
                  "type": "integer"
                },
                "platform": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "claude_subscription",
                "codex_subscription",
                "platform",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "claude_subscription": {
                    "default": 0,
                    "type": "integer"
                  },
                  "codex_subscription": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "platform": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "claude_subscription",
                  "codex_subscription",
                  "model",
                  "platform",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        },
        "memory": {
          "default": 0,
          "type": "integer"
        },
        "total": {
          "default": 0,
          "type": "integer"
        }
      },
      "required": [
        "charged",
        "cpu",
        "fee",
        "llm",
        "memory",
        "total"
      ],
      "type": "object"
    },
    "period_end": {
      "type": "string"
    },
    "period_start": {
      "type": "string"
    },
    "prior_cost": {
      "properties": {
        "charged": {
          "default": 0,
          "type": "integer"
        },
        "cpu": {
          "default": 0,
          "type": "integer"
        },
        "fee": {
          "default": 0,
          "type": "integer"
        },
        "llm": {
          "properties": {
            "all": {
              "properties": {
                "claude_subscription": {
                  "default": 0,
                  "type": "integer"
                },
                "codex_subscription": {
                  "default": 0,
                  "type": "integer"
                },
                "platform": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "claude_subscription",
                "codex_subscription",
                "platform",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "claude_subscription": {
                    "default": 0,
                    "type": "integer"
                  },
                  "codex_subscription": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "platform": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "claude_subscription",
                  "codex_subscription",
                  "model",
                  "platform",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        },
        "memory": {
          "default": 0,
          "type": "integer"
        },
        "total": {
          "default": 0,
          "type": "integer"
        }
      },
      "required": [
        "charged",
        "cpu",
        "fee",
        "llm",
        "memory",
        "total"
      ],
      "type": "object"
    },
    "prior_tokens": {
      "properties": {
        "all": {
          "properties": {
            "cache_creation": {
              "default": 0,
              "type": "integer"
            },
            "cache_read": {
              "default": 0,
              "type": "integer"
            },
            "input": {
              "default": 0,
              "type": "integer"
            },
            "output": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cache_creation",
            "cache_read",
            "input",
            "output",
            "total"
          ],
          "type": "object"
        },
        "by_model": {
          "items": {
            "properties": {
              "cache_creation": {
                "default": 0,
                "type": "integer"
              },
              "cache_read": {
                "default": 0,
                "type": "integer"
              },
              "input": {
                "default": 0,
                "type": "integer"
              },
              "model": {
                "type": "string"
              },
              "output": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "cache_creation",
              "cache_read",
              "input",
              "model",
              "output",
              "total"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "all",
        "by_model"
      ],
      "type": "object"
    },
    "tokens": {
      "properties": {
        "all": {
          "properties": {
            "cache_creation": {
              "default": 0,
              "type": "integer"
            },
            "cache_read": {
              "default": 0,
              "type": "integer"
            },
            "input": {
              "default": 0,
              "type": "integer"
            },
            "output": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cache_creation",
            "cache_read",
            "input",
            "output",
            "total"
          ],
          "type": "object"
        },
        "by_model": {
          "items": {
            "properties": {
              "cache_creation": {
                "default": 0,
                "type": "integer"
              },
              "cache_read": {
                "default": 0,
                "type": "integer"
              },
              "input": {
                "default": 0,
                "type": "integer"
              },
              "model": {
                "type": "string"
              },
              "output": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "cache_creation",
              "cache_read",
              "input",
              "model",
              "output",
              "total"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "all",
        "by_model"
      ],
      "type": "object"
    }
  },
  "required": [
    "billing_periods",
    "period_start",
    "period_end",
    "cost",
    "tokens",
    "prior_cost",
    "prior_tokens",
    "by_day",
    "agent_sessions",
    "by_developer"
  ],
  "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-id

## DELETE /v1/agents/{id}

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

Required permissions: write:configs.
API key: Supported.
CLI user token: Supported.
Session token: Not supported by session 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl -X DELETE "https://api.ellipsis.dev/v1/agents/{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-id-metrics

## GET /v1/agents/{id}/metrics

Read usage and spend windows for an agent.

Required permissions: read:configs.
API key: Supported.
CLI user token: Supported.
Session 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": {
        "charged": int,
        "cpu": int,
        "fee": int,
        "llm": {
          "all": {
            "claude_subscription": int,
            "codex_subscription": int,
            "platform": int,
            "total": int
          },
          "by_model": [
            {
              "claude_subscription": int,
              "codex_subscription": int,
              "model": str,
              "platform": int,
              "total": int
            }
          ]
        },
        "memory": int,
        "total": int
      },
      "duration_seconds": float,
      "tokens": {
        "all": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "output": int,
          "total": int
        },
        "by_model": [
          {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": int
          }
        ]
      }
    }
  ],
  "spend_windows": [
    {
      "limit": int,
      "platform_max": int,
      "spent": int,
      "window_days": int
    }
  ]
}
```

### Python

```python
import os

from ellipsis import Ellipsis

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

result = client.agents.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.agents.metrics('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/agents/{id}/metrics" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "samples": {
      "items": {
        "properties": {
          "cost": {
            "properties": {
              "charged": {
                "default": 0,
                "type": "integer"
              },
              "cpu": {
                "default": 0,
                "type": "integer"
              },
              "fee": {
                "default": 0,
                "type": "integer"
              },
              "llm": {
                "properties": {
                  "all": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "by_model": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "all",
                  "by_model"
                ],
                "type": "object"
              },
              "memory": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "charged",
              "cpu",
              "fee",
              "llm",
              "memory",
              "total"
            ],
            "type": "object"
          },
          "duration_seconds": {
            "type": "number"
          },
          "tokens": {
            "properties": {
              "all": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "by_model": {
                "items": {
                  "properties": {
                    "cache_creation": {
                      "type": "integer"
                    },
                    "cache_read": {
                      "type": "integer"
                    },
                    "input": {
                      "type": "integer"
                    },
                    "model": {
                      "type": "string"
                    },
                    "output": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "cache_creation",
                    "cache_read",
                    "input",
                    "model",
                    "output",
                    "total"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "all",
              "by_model"
            ],
            "type": "object"
          }
        },
        "required": [
          "duration_seconds",
          "cost",
          "tokens"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "spend_windows": {
      "items": {
        "properties": {
          "limit": {
            "type": "integer"
          },
          "platform_max": {
            "type": "integer"
          },
          "spent": {
            "type": "integer"
          },
          "window_days": {
            "type": "integer"
          }
        },
        "required": [
          "window_days",
          "spent",
          "limit",
          "platform_max"
        ],
        "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-id

## GET /v1/agents/{id}

Read a saved agent and its configuration source.

Required permissions: read:configs.
API key: Supported.
CLI user token: Supported.
Session 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
        },
        "conversation": {
          "interactive": bool
        },
        "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
            }
          ]
        },
        "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
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "check_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "check_suite": {
          "apps": [
            str
          ],
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "enabled": bool,
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "release": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "prerelease": bool,
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          },
          "tag": [
            str
          ]
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "status": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "type": "react",
        "workflow_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        }
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "name": 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,
    "raw_yaml": 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/agents/{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": "string"
                        },
                        "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"
                    }
                  ]
                },
                "conversation": {
                  "additionalProperties": false,
                  "properties": {
                    "interactive": {
                      "default": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "interactive"
                  ],
                  "type": "object"
                },
                "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": []
                  }
                },
                "metadata": {
                  "items": {
                    "type": "string"
                  },
                  "default": {},
                  "type": "object"
                },
                "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",
                "conversation",
                "environment",
                "metadata",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "enabled",
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "check_run": {
                          "type": "object"
                        },
                        "check_suite": {
                          "type": "object"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "release": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "status": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        },
                        "workflow_run": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "check_run",
                        "check_suite",
                        "enabled",
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "release",
                        "sentry",
                        "slack_channel",
                        "status",
                        "type",
                        "workflow_run"
                      ],
                      "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"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "name",
                "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"
            }
          ]
        },
        "raw_yaml": {
          "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",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config",
        "raw_yaml"
      ],
      "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.
Session 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
          },
          "conversation": {
            "interactive": bool
          },
          "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
              }
            ]
          },
          "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
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "check_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "check_suite": {
            "apps": [
              str
            ],
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "enabled": bool,
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "release": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "prerelease": bool,
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            },
            "tag": [
              str
            ]
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "status": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "type": "react",
          "workflow_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          }
        }
      },
      "created_at": str,
      "display_name": str,
      "edited_by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": 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,
      "raw_yaml": 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"
                      }
                    ]
                  },
                  "conversation": {
                    "additionalProperties": false,
                    "properties": {
                      "interactive": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "interactive"
                    ],
                    "type": "object"
                  },
                  "environment": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      }
                    ],
                    "default": {
                      "compute": {},
                      "hooks": {},
                      "mcp_servers": [],
                      "repositories": [],
                      "variables": []
                    }
                  },
                  "metadata": {
                    "items": {
                      "type": "string"
                    },
                    "default": {},
                    "type": "object"
                  },
                  "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",
                  "conversation",
                  "environment",
                  "metadata",
                  "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"
                  },
                  "name": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "type": {
                    "enum": [
                      "User",
                      "Organization",
                      "Bot",
                      "Mannequin"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "avatar_url",
                  "id",
                  "login",
                  "name",
                  "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"
              }
            ]
          },
          "raw_yaml": {
            "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",
          "sha",
          "created_at",
          "updated_at",
          "managed_by",
          "config",
          "raw_yaml"
        ],
        "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/{id}`](https://www.ellipsis.dev/docs/api/agents/get-agents-id): Get an agent
- [`PUT /v1/agents/{id}`](https://www.ellipsis.dev/docs/api/agents/put-agents-id): Update an agent
- [`DELETE /v1/agents/{id}`](https://www.ellipsis.dev/docs/api/agents/delete-agents-id): Delete an agent
- [`POST /v1/agents/{id}/link`](https://www.ellipsis.dev/docs/api/agents/post-agents-id-link): Link to GitHub
- [`GET /v1/agents/{id}/metrics`](https://www.ellipsis.dev/docs/api/agents/get-agents-id-metrics): Get agent usage
- [`POST /v1/agents/{id}/sessions`](https://www.ellipsis.dev/docs/api/agents/post-agents-id-sessions): Start an agent session
- [`POST /v1/agents/{id}/unlink`](https://www.ellipsis.dev/docs/api/agents/post-agents-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-id-link

## POST /v1/agents/{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.
Session token: Not supported by session 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
        },
        "conversation": {
          "interactive": bool
        },
        "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
            }
          ]
        },
        "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
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "check_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "check_suite": {
          "apps": [
            str
          ],
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "enabled": bool,
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "release": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "prerelease": bool,
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          },
          "tag": [
            str
          ]
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "status": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "type": "react",
        "workflow_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        }
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "name": 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,
    "raw_yaml": 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("...", 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('...', request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/agents/{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": "string"
                        },
                        "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"
                    }
                  ]
                },
                "conversation": {
                  "additionalProperties": false,
                  "properties": {
                    "interactive": {
                      "default": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "interactive"
                  ],
                  "type": "object"
                },
                "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": []
                  }
                },
                "metadata": {
                  "items": {
                    "type": "string"
                  },
                  "default": {},
                  "type": "object"
                },
                "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",
                "conversation",
                "environment",
                "metadata",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "enabled",
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "check_run": {
                          "type": "object"
                        },
                        "check_suite": {
                          "type": "object"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "release": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "status": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        },
                        "workflow_run": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "check_run",
                        "check_suite",
                        "enabled",
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "release",
                        "sentry",
                        "slack_channel",
                        "status",
                        "type",
                        "workflow_run"
                      ],
                      "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"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "name",
                "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"
            }
          ]
        },
        "raw_yaml": {
          "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",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config",
        "raw_yaml"
      ],
      "type": "object"
    },
    "path": {
      "type": "string"
    },
    "pull_request_url": {
      "type": "string"
    }
  },
  "required": [
    "agent",
    "path",
    "pull_request_url"
  ],
  "type": "object"
}
```

---

# Start an agent session

> Start a session from a saved agent. The body takes the fields of Start a session, all optional: each field you send replaces the agent value for that field, and each field you leave out keeps it. Send input when the agent declares an input schema.

Source: https://www.ellipsis.dev/docs/api/agents/post-agents-id-sessions

## POST /v1/agents/{id}/sessions

Start a session from a saved agent. The body takes the fields of Start a session, all optional: each field you send replaces the agent value for that field, and each field you leave out keeps it. Send input when the agent declares an input schema.

Required permissions: write:sessions.
API key: Supported.
CLI user token: Supported.
Session 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": {
    "session": 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
  },
  "conversation": {
    "interactive": bool
  },
  "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
    }
  ],
  "input": {
    "[str]": any
  },
  "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
      ]
    }
  },
  "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
          },
          "conversation": {
            "interactive": bool
          },
          "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
              }
            ]
          },
          "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
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "check_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "check_suite": {
            "apps": [
              str
            ],
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "enabled": bool,
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "release": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "prerelease": bool,
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            },
            "tag": [
              str
            ]
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "status": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "type": "react",
          "workflow_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          }
        }
      },
      "id": str
    },
    "archived": {
      "at": str,
      "by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "attribution": {
      "id": str,
      "type": str,
      "user": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "budget": int,
    "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
    },
    "conversation": {
      "interactive": bool,
      "prompting": {
        "blocked_reason": str,
        "detail": str,
        "enabled": bool,
        "surface_name": str
      },
      "state": str,
      "warm": bool
    },
    "cost": {
      "charged": int,
      "cpu": int,
      "fee": int,
      "llm": {
        "all": {
          "claude_subscription": int,
          "codex_subscription": int,
          "platform": int,
          "total": int
        },
        "by_model": [
          {
            "claude_subscription": int,
            "codex_subscription": int,
            "model": str,
            "platform": int,
            "total": int
          }
        ]
      },
      "memory": int,
      "total": int
    },
    "created_at": str,
    "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 | GithubWorkflowRunEvent | GithubPullRequestEvent |
    # GithubIssueEvent | GithubPushEvent | GithubCheckRunEvent |
    # GithubCheckSuiteEvent | GithubStatusEvent | GithubReleaseEvent |
    # LinearIssueEvent | SlackMessageEvent | SlackChannelCreatedEvent |
    # SentryAlertEvent
      "action": str,
      "actor": {
        "avatar_url": str,
        "is_bot": bool,
        "name": str
      },
      "branch": str,
      "conclusion": str,
      "head_sha": str,
      "name": str,
      "pull_request_number": int,
      "repository": str,
      "run_number": int,
      "type": "github.workflow_run",
      "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,
    "metadata": {
      "[str]": str
    },
    "output": {
      "json_schema": {
        "[str]": any
      },
      "result": {
        "[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": {
      "all": {
        "cache_creation": int,
        "cache_read": int,
        "input": int,
        "output": int,
        "total": int
      },
      "by_model": [
        {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "model": str,
          "output": int,
          "total": int
        }
      ]
    },
    "turn": {
      "cost": {
        "charged": int,
        "cpu": int,
        "fee": int,
        "llm": {
          "all": {
            "claude_subscription": int,
            "codex_subscription": int,
            "platform": int,
            "total": int
          },
          "by_model": [
            {
              "claude_subscription": int,
              "codex_subscription": int,
              "model": str,
              "platform": int,
              "total": int
            }
          ]
        },
        "memory": int,
        "total": int
      },
      "created_at": str,
      "detail": str,
      "ended_at": str,
      "id": str,
      "index": int,
      "reason": str,
      "started_at": str,
      "status": str,
      "stopped": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "name": str,
          "type": str
        }
      },
      "tokens": {
        "all": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "output": int,
          "total": int
        },
        "by_model": [
          {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": 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.StartAgentSessionRequest.model_validate(
    {
      "claude_code": {
        "prompt": "Focus on the failing tests."
      },
      "budget": {
        "session": 3
      }
    }
)

result = client.agents.start(
    "...",
    budget=request.budget,
    claude_code=request.claude_code,
)
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.start>[1] = {
  "claude_code": {
    "prompt": "Focus on the failing tests."
  },
  "budget": {
    "session": 3
  }
};

const result = await client.agents.start('...', request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/agents/{id}/sessions" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "claude_code": {
    "prompt": "Focus on the failing tests."
  },
  "budget": {
    "session": 3
  }
}'
```

### Request schema

```json
{
  "additionalProperties": false,
  "properties": {
    "budget": {
      "anyOf": [
        {
          "additionalProperties": false,
          "properties": {
            "session": {
              "anyOf": [
                {
                  "exclusiveMinimum": 0,
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        {
          "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": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "prompt": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "conversation": {
      "additionalProperties": false,
      "properties": {
        "interactive": {
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "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": {
              "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": {
              "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": {
              "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": {
      "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"
    },
    "input": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "items": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "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"
                }
              ]
            },
            "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"
        }
      ]
    },
    "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"
                        },
                        "conversation": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "budget",
                        "claude_code",
                        "codex",
                        "conversation",
                        "environment",
                        "metadata",
                        "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"
            }
          ]
        },
        "archived": {
          "anyOf": [
            {
              "properties": {
                "at": {
                  "format": "date-time",
                  "type": "string"
                },
                "by": {
                  "anyOf": [
                    {
                      "properties": {
                        "avatar_url": {
                          "type": "string"
                        },
                        "id": {
                          "type": "integer"
                        },
                        "login": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "avatar_url",
                        "id",
                        "login",
                        "name",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "at",
                "by"
              ],
              "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"
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "enum": [
                        "User",
                        "Organization",
                        "Bot",
                        "Mannequin"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "avatar_url",
                    "id",
                    "login",
                    "name",
                    "type"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "type",
            "user"
          ],
          "type": "object"
        },
        "budget": {
          "default": 0,
          "type": "integer"
        },
        "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": {
                  "type": "string"
                },
                "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": {
                  "type": "string"
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "model",
                "prompt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "conversation": {
          "properties": {
            "interactive": {
              "type": "boolean"
            },
            "prompting": {
              "properties": {
                "blocked_reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "mention_surface",
                        "non_interactive",
                        "harness_single_turn",
                        "budget_exhausted",
                        "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"
            },
            "state": {
              "enum": [
                "open",
                "closed"
              ],
              "type": "string"
            },
            "warm": {
              "type": "boolean"
            }
          },
          "required": [
            "interactive",
            "prompting",
            "state",
            "warm"
          ],
          "type": "object"
        },
        "cost": {
          "properties": {
            "charged": {
              "default": 0,
              "type": "integer"
            },
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "properties": {
                "all": {
                  "properties": {
                    "claude_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "codex_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "platform": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "claude_subscription",
                    "codex_subscription",
                    "platform",
                    "total"
                  ],
                  "type": "object"
                },
                "by_model": {
                  "items": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "model": {
                        "type": "string"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "model",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "all",
                "by_model"
              ],
              "type": "object"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "charged",
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "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": {
                      "enum": [
                        "requested",
                        "queued",
                        "waiting",
                        "pending",
                        "started",
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.check_run",
                      "default": "github.check_run",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "name",
                    "pull_request_number",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale",
                        "startup_failure"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "app": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.check_suite",
                      "default": "github.check_suite",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "app",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "pull_request_number",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "requested",
                        "queued",
                        "waiting",
                        "pending",
                        "started",
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale",
                        "startup_failure"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "run_number": {
                      "type": "integer"
                    },
                    "type": {
                      "const": "github.workflow_run",
                      "default": "github.workflow_run",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "name",
                    "pull_request_number",
                    "repository",
                    "run_number",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "pending",
                        "passed",
                        "failed",
                        "errored"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "context": {
                      "type": "string"
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.status",
                      "default": "github.status",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "context",
                    "head_sha",
                    "pull_request_number",
                    "repository",
                    "state",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "published"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "prerelease": {
                      "type": "boolean"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "tag": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.release",
                      "default": "github.release",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "name",
                    "prerelease",
                    "repository",
                    "tag",
                    "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"
        },
        "metadata": {
          "items": {
            "type": "string"
          },
          "default": {},
          "type": "object"
        },
        "output": {
          "anyOf": [
            {
              "properties": {
                "json_schema": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "result": {
                  "anyOf": [
                    {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "json_schema",
                "result"
              ],
              "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",
            "code_review",
            "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": {
            "all": {
              "properties": {
                "cache_creation": {
                  "default": 0,
                  "type": "integer"
                },
                "cache_read": {
                  "default": 0,
                  "type": "integer"
                },
                "input": {
                  "default": 0,
                  "type": "integer"
                },
                "output": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "cache_creation",
                "cache_read",
                "input",
                "output",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "model",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        },
        "turn": {
          "anyOf": [
            {
              "properties": {
                "cost": {
                  "properties": {
                    "charged": {
                      "default": 0,
                      "type": "integer"
                    },
                    "cpu": {
                      "default": 0,
                      "type": "integer"
                    },
                    "fee": {
                      "default": 0,
                      "type": "integer"
                    },
                    "llm": {
                      "properties": {
                        "all": {
                          "type": "object"
                        },
                        "by_model": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "all",
                        "by_model"
                      ],
                      "type": "object"
                    },
                    "memory": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "charged",
                    "cpu",
                    "fee",
                    "llm",
                    "memory",
                    "total"
                  ],
                  "type": "object"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "detail": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "ended_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "id": {
                  "type": "string"
                },
                "index": {
                  "type": "integer"
                },
                "reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "error",
                        "tool_call_failed",
                        "budget_hit",
                        "payment_required",
                        "blocked",
                        "contact_email_required",
                        "lifecycle_hook_failed",
                        "missing_repo_access",
                        "missing_token_permissions",
                        "missing_environment_variables",
                        "missing_github_integration",
                        "agent_unavailable",
                        "upstream_unavailable",
                        "unsupported_configuration",
                        "execution_disabled",
                        "interrupted"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "started_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "enum": [
                    "queued",
                    "preparing",
                    "running",
                    "completed",
                    "failed",
                    "stopped",
                    "cancelled"
                  ],
                  "type": "string"
                },
                "stopped": {
                  "anyOf": [
                    {
                      "properties": {
                        "at": {
                          "type": "string"
                        },
                        "by": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "at",
                        "by"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "tokens": {
                  "properties": {
                    "all": {
                      "properties": {
                        "cache_creation": {
                          "type": "integer"
                        },
                        "cache_read": {
                          "type": "integer"
                        },
                        "input": {
                          "type": "integer"
                        },
                        "output": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "cache_creation",
                        "cache_read",
                        "input",
                        "output",
                        "total"
                      ],
                      "type": "object"
                    },
                    "by_model": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "all",
                    "by_model"
                  ],
                  "type": "object"
                }
              },
              "required": [
                "cost",
                "created_at",
                "detail",
                "ended_at",
                "id",
                "index",
                "reason",
                "started_at",
                "status",
                "stopped",
                "tokens"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "agent",
        "archived",
        "attribution",
        "budget",
        "claude_code",
        "codex",
        "conversation",
        "cost",
        "created_at",
        "environment",
        "event",
        "git",
        "handler",
        "id",
        "metadata",
        "output",
        "parent",
        "permissions",
        "skills",
        "source",
        "summary",
        "tokens",
        "turn",
        "updated_at"
      ],
      "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-id-unlink

## POST /v1/agents/{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.
Session token: Not supported by session 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
        },
        "conversation": {
          "interactive": bool
        },
        "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
            }
          ]
        },
        "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
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "check_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "check_suite": {
          "apps": [
            str
          ],
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "enabled": bool,
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "release": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "prerelease": bool,
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          },
          "tag": [
            str
          ]
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "status": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "type": "react",
        "workflow_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        }
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "name": 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,
    "raw_yaml": 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/agents/{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": "string"
                        },
                        "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"
                    }
                  ]
                },
                "conversation": {
                  "additionalProperties": false,
                  "properties": {
                    "interactive": {
                      "default": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "interactive"
                  ],
                  "type": "object"
                },
                "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": []
                  }
                },
                "metadata": {
                  "items": {
                    "type": "string"
                  },
                  "default": {},
                  "type": "object"
                },
                "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",
                "conversation",
                "environment",
                "metadata",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "enabled",
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "check_run": {
                          "type": "object"
                        },
                        "check_suite": {
                          "type": "object"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "release": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "status": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        },
                        "workflow_run": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "check_run",
                        "check_suite",
                        "enabled",
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "release",
                        "sentry",
                        "slack_channel",
                        "status",
                        "type",
                        "workflow_run"
                      ],
                      "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"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "name",
                "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"
            }
          ]
        },
        "raw_yaml": {
          "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",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config",
        "raw_yaml"
      ],
      "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.
Session token: Not supported by session 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
      },
      "conversation": {
        "interactive": bool
      },
      "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
          }
        ]
      },
      "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
          ]
        }
      },
      "skills": [
        {
          "path": str,
          "repository": {
            "name": str,
            "owner": str,
            "ref": str
          }
        }
      ]
    },
    "trigger": { # null | ReactTrigger | CronTrigger
      "check_run": {
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "names": [
          str
        ],
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "check_suite": {
        "apps": [
          str
        ],
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "enabled": bool,
      "issue": {
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            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
            ]
          },
          "teams": [
            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
            ]
          },
          "teams": [
            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
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "paths": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "release": {
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "on": [
          str
        ],
        "prerelease": bool,
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        },
        "tag": [
          str
        ]
      },
      "sentry": {
        "on": [
          str
        ],
        "projects": [
          str
        ]
      },
      "slack_channel": {},
      "status": {
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "names": [
          str
        ],
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "type": "react",
      "workflow_run": {
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "names": [
          str
        ],
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            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
        },
        "conversation": {
          "interactive": bool
        },
        "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
            }
          ]
        },
        "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
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "check_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "check_suite": {
          "apps": [
            str
          ],
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "enabled": bool,
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "release": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "prerelease": bool,
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          },
          "tag": [
            str
          ]
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "status": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "type": "react",
        "workflow_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        }
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "name": 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,
    "raw_yaml": 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": {
            "model": "claude-opus-5-5",
            "prompt": "Run the tests and report failures."
          },
          "environment": "api-environment",
          "budget": {
            "session": 3
          },
          "permissions": {
            "github": {},
            "ellipsis": True
          },
          "skills": [],
          "conversation": {
            "interactive": True
          },
          "metadata": {}
        }
      }
    }
)

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": {
        "model": "claude-opus-5-5",
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "budget": {
        "session": 3
      },
      "permissions": {
        "github": {},
        "ellipsis": true
      },
      "skills": [],
      "conversation": {
        "interactive": true
      },
      "metadata": {}
    }
  }
};

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": {
        "model": "claude-opus-5-5",
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "budget": {
        "session": 3
      },
      "permissions": {
        "github": {},
        "ellipsis": true
      },
      "skills": [],
      "conversation": {
        "interactive": true
      },
      "metadata": {}
    }
  }
}'
```

### Request schema

```json
{
  "properties": {
    "agent": {
      "additionalProperties": false,
      "properties": {
        "ellipsis": {
          "additionalProperties": false,
          "properties": {
            "description": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "enabled": {
              "type": "boolean"
            },
            "kind": {
              "const": "agent",
              "type": "string"
            },
            "metadata": {
              "additionalProperties": false,
              "properties": {
                "annotations": {
                  "items": {
                    "type": "string"
                  },
                  "type": "object"
                },
                "labels": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "version": {
              "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": {
                      "type": "string"
                    },
                    "prompt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "settings": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "model"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "codex": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "effort": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "model": {
                      "type": "string"
                    },
                    "prompt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "model"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "conversation": {
              "additionalProperties": false,
              "properties": {
                "interactive": {
                  "type": "boolean"
                }
              },
              "type": "object"
            },
            "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": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "repositories": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "variables": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              ]
            },
            "metadata": {
              "items": {
                "type": "string"
              },
              "type": "object"
            },
            "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"
                    }
                  ]
                },
                "github": {
                  "additionalProperties": false,
                  "properties": {
                    "permissions": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repositories": {
                      "anyOf": [
                        {
                          "type": "array"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                }
              },
              "type": "object"
            },
            "skills": {
              "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": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "schedule": {
                      "type": "string"
                    },
                    "type": {
                      "const": "cron",
                      "default": "cron",
                      "type": "string"
                    }
                  },
                  "required": [
                    "schedule"
                  ],
                  "type": "object"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "check_run": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "check_suite": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "enabled": {
                      "type": "boolean"
                    },
                    "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"
                        }
                      ]
                    },
                    "release": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "sentry": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "slack_channel": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "react",
                      "default": "react",
                      "type": "string"
                    },
                    "workflow_run": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "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": "string"
                        },
                        "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"
                    }
                  ]
                },
                "conversation": {
                  "additionalProperties": false,
                  "properties": {
                    "interactive": {
                      "default": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "interactive"
                  ],
                  "type": "object"
                },
                "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": []
                  }
                },
                "metadata": {
                  "items": {
                    "type": "string"
                  },
                  "default": {},
                  "type": "object"
                },
                "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",
                "conversation",
                "environment",
                "metadata",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "enabled",
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "check_run": {
                          "type": "object"
                        },
                        "check_suite": {
                          "type": "object"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "release": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "status": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        },
                        "workflow_run": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "check_run",
                        "check_suite",
                        "enabled",
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "release",
                        "sentry",
                        "slack_channel",
                        "status",
                        "type",
                        "workflow_run"
                      ],
                      "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"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "name",
                "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"
            }
          ]
        },
        "raw_yaml": {
          "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",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config",
        "raw_yaml"
      ],
      "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-id

## PUT /v1/agents/{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.
Session token: Not supported by session 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
      },
      "conversation": {
        "interactive": bool
      },
      "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
          }
        ]
      },
      "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
          ]
        }
      },
      "skills": [
        {
          "path": str,
          "repository": {
            "name": str,
            "owner": str,
            "ref": str
          }
        }
      ]
    },
    "trigger": { # null | ReactTrigger | CronTrigger
      "check_run": {
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "names": [
          str
        ],
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "check_suite": {
        "apps": [
          str
        ],
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "enabled": bool,
      "issue": {
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            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
            ]
          },
          "teams": [
            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
            ]
          },
          "teams": [
            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
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "paths": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "release": {
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "on": [
          str
        ],
        "prerelease": bool,
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        },
        "tag": [
          str
        ]
      },
      "sentry": {
        "on": [
          str
        ],
        "projects": [
          str
        ]
      },
      "slack_channel": {},
      "status": {
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "names": [
          str
        ],
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            str
          ]
        }
      },
      "type": "react",
      "workflow_run": {
        "branch": [
          str
        ],
        "for": {
          "bots": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          },
          "teams": [
            str
          ],
          "users": { # bool | list[str]
            "exclude": [
              str
            ],
            "include": [ # bool
              str
            ]
          }
        },
        "names": [
          str
        ],
        "on": [
          str
        ],
        "repositories": { # list[str]
          "exclude": [
            str
          ],
          "include": [
            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
        },
        "conversation": {
          "interactive": bool
        },
        "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
            }
          ]
        },
        "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
            ]
          }
        },
        "skills": [
          {
            "path": str,
            "repository": {
              "name": str,
              "owner": str,
              "ref": str
            }
          }
        ]
      },
      "trigger": { # null | ReactTrigger | CronTrigger
        "check_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "check_suite": {
          "apps": [
            str
          ],
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "enabled": bool,
        "issue": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              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
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "release": {
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "on": [
            str
          ],
          "prerelease": bool,
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          },
          "tag": [
            str
          ]
        },
        "sentry": {
          "on": [
            str
          ],
          "projects": [
            str
          ]
        },
        "slack_channel": {},
        "status": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "type": "react",
        "workflow_run": {
          "branch": [
            str
          ],
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "names": [
            str
          ],
          "on": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        }
      }
    },
    "created_at": str,
    "display_name": str,
    "edited_by": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "name": 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,
    "raw_yaml": 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": {
            "model": "claude-opus-5-5",
            "prompt": "Run the tests and report failures."
          },
          "environment": "api-environment",
          "budget": {
            "session": 3
          },
          "permissions": {
            "github": {},
            "ellipsis": True
          },
          "skills": [],
          "conversation": {
            "interactive": True
          },
          "metadata": {}
        }
      }
    }
)

result = client.agents.update("...", 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": {
        "model": "claude-opus-5-5",
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "budget": {
        "session": 3
      },
      "permissions": {
        "github": {},
        "ellipsis": true
      },
      "skills": [],
      "conversation": {
        "interactive": true
      },
      "metadata": {}
    }
  }
};

const result = await client.agents.update('...', request);
console.log(result);
```

### cURL

```bash
curl -X PUT "https://api.ellipsis.dev/v1/agents/{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": {
        "model": "claude-opus-5-5",
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "budget": {
        "session": 3
      },
      "permissions": {
        "github": {},
        "ellipsis": true
      },
      "skills": [],
      "conversation": {
        "interactive": true
      },
      "metadata": {}
    }
  }
}'
```

### Request schema

```json
{
  "properties": {
    "agent": {
      "additionalProperties": false,
      "properties": {
        "ellipsis": {
          "additionalProperties": false,
          "properties": {
            "description": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "enabled": {
              "type": "boolean"
            },
            "kind": {
              "const": "agent",
              "type": "string"
            },
            "metadata": {
              "additionalProperties": false,
              "properties": {
                "annotations": {
                  "items": {
                    "type": "string"
                  },
                  "type": "object"
                },
                "labels": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "version": {
              "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": {
                      "type": "string"
                    },
                    "prompt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "settings": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "model"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "codex": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "effort": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "model": {
                      "type": "string"
                    },
                    "prompt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "model"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "conversation": {
              "additionalProperties": false,
              "properties": {
                "interactive": {
                  "type": "boolean"
                }
              },
              "type": "object"
            },
            "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": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "repositories": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "variables": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              ]
            },
            "metadata": {
              "items": {
                "type": "string"
              },
              "type": "object"
            },
            "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"
                    }
                  ]
                },
                "github": {
                  "additionalProperties": false,
                  "properties": {
                    "permissions": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repositories": {
                      "anyOf": [
                        {
                          "type": "array"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "type": "object"
                }
              },
              "type": "object"
            },
            "skills": {
              "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": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "schedule": {
                      "type": "string"
                    },
                    "type": {
                      "const": "cron",
                      "default": "cron",
                      "type": "string"
                    }
                  },
                  "required": [
                    "schedule"
                  ],
                  "type": "object"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "check_run": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "check_suite": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "enabled": {
                      "type": "boolean"
                    },
                    "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"
                        }
                      ]
                    },
                    "release": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "sentry": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "slack_channel": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "const": "react",
                      "default": "react",
                      "type": "string"
                    },
                    "workflow_run": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "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": "string"
                        },
                        "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"
                    }
                  ]
                },
                "conversation": {
                  "additionalProperties": false,
                  "properties": {
                    "interactive": {
                      "default": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "interactive"
                  ],
                  "type": "object"
                },
                "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": []
                  }
                },
                "metadata": {
                  "items": {
                    "type": "string"
                  },
                  "default": {},
                  "type": "object"
                },
                "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",
                "conversation",
                "environment",
                "metadata",
                "output",
                "permissions",
                "skills"
              ],
              "type": "object"
            },
            "trigger": {
              "anyOf": [
                {
                  "oneOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "schedule": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "enabled",
                        "schedule",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "check_run": {
                          "type": "object"
                        },
                        "check_suite": {
                          "type": "object"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "issue": {
                          "type": "object"
                        },
                        "linear_issue": {
                          "type": "object"
                        },
                        "pull_request": {
                          "type": "object"
                        },
                        "push": {
                          "type": "object"
                        },
                        "release": {
                          "type": "object"
                        },
                        "sentry": {
                          "type": "object"
                        },
                        "slack_channel": {
                          "type": "object"
                        },
                        "status": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        },
                        "workflow_run": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "check_run",
                        "check_suite",
                        "enabled",
                        "issue",
                        "linear_issue",
                        "pull_request",
                        "push",
                        "release",
                        "sentry",
                        "slack_channel",
                        "status",
                        "type",
                        "workflow_run"
                      ],
                      "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"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "name",
                "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"
            }
          ]
        },
        "raw_yaml": {
          "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",
        "sha",
        "created_at",
        "updated_at",
        "managed_by",
        "config",
        "raw_yaml"
      ],
      "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-id

## DELETE /v1/environments/{id}

Delete an API-managed environment. New sessions referencing it will fail.

Required permissions: delete:environments.
API key: Supported.
CLI user token: Supported.
Session token: Not supported by session 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl -X DELETE "https://api.ellipsis.dev/v1/environments/{id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

---

# Get an environment

> Read an environment definition.

Source: https://www.ellipsis.dev/docs/api/environments/get-environments-id

## GET /v1/environments/{id}

Read an environment definition.

Required permissions: read:environments.
API key: Supported.
CLI user token: Supported.
Session 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,
      "name": 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,
    "raw_yaml": 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/environments/{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"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "name",
                "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"
        },
        "raw_yaml": {
          "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",
        "raw_yaml"
      ],
      "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.
Session 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,
        "name": 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,
      "raw_yaml": 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"
                  },
                  "name": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "type": {
                    "enum": [
                      "User",
                      "Organization",
                      "Bot",
                      "Mannequin"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "avatar_url",
                  "id",
                  "login",
                  "name",
                  "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"
          },
          "raw_yaml": {
            "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",
          "raw_yaml"
        ],
        "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/{id}`](https://www.ellipsis.dev/docs/api/environments/get-environments-id): Get an environment
- [`PUT /v1/environments/{id}`](https://www.ellipsis.dev/docs/api/environments/put-environments-id): Update an environment
- [`DELETE /v1/environments/{id}`](https://www.ellipsis.dev/docs/api/environments/delete-environments-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.
Session token: Not supported by session 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,
      "name": 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,
    "raw_yaml": 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"
                  },
                  "type": "object"
                },
                "labels": {
                  "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": {
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ],
                "type": "object"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "args": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "command": {
                    "type": "string"
                  },
                  "env": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "command"
                ],
                "type": "object"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "headers": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "name": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "url"
                ],
                "type": "object"
              }
            ]
          },
          "type": "array"
        },
        "repositories": {
          "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": {
          "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"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "name",
                "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"
        },
        "raw_yaml": {
          "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",
        "raw_yaml"
      ],
      "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-id

## PUT /v1/environments/{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.
Session token: Not supported by session 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,
      "name": 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,
    "raw_yaml": 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("...", 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('...', request);
console.log(result);
```

### cURL

```bash
curl -X PUT "https://api.ellipsis.dev/v1/environments/{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"
                  },
                  "type": "object"
                },
                "labels": {
                  "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": {
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ],
                "type": "object"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "args": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "command": {
                    "type": "string"
                  },
                  "env": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "command"
                ],
                "type": "object"
              },
              {
                "additionalProperties": false,
                "properties": {
                  "headers": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "name": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "url"
                ],
                "type": "object"
              }
            ]
          },
          "type": "array"
        },
        "repositories": {
          "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": {
          "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"
                },
                "name": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "enum": [
                    "User",
                    "Organization",
                    "Bot",
                    "Mannequin"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "avatar_url",
                "id",
                "login",
                "name",
                "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"
        },
        "raw_yaml": {
          "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",
        "raw_yaml"
      ],
      "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-id-metrics

## GET /v1/handlers/{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.
Session 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": {
    "charged": int,
    "cpu": int,
    "fee": int,
    "llm": {
      "all": {
        "claude_subscription": int,
        "codex_subscription": int,
        "platform": int,
        "total": int
      },
      "by_model": [
        {
          "claude_subscription": int,
          "codex_subscription": int,
          "model": str,
          "platform": int,
          "total": int
        }
      ]
    },
    "memory": int,
    "total": int
  },
  "end": str,
  "handler_id": str,
  "sessions": {
    "active": int,
    "cancelled": int,
    "completed": int,
    "failed": int,
    "stopped": int,
    "total": int
  },
  "spend_windows": [
    {
      "limit": int,
      "platform_max": int,
      "spent": int,
      "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/{id}/metrics" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "cost": {
      "properties": {
        "charged": {
          "default": 0,
          "type": "integer"
        },
        "cpu": {
          "default": 0,
          "type": "integer"
        },
        "fee": {
          "default": 0,
          "type": "integer"
        },
        "llm": {
          "properties": {
            "all": {
              "properties": {
                "claude_subscription": {
                  "default": 0,
                  "type": "integer"
                },
                "codex_subscription": {
                  "default": 0,
                  "type": "integer"
                },
                "platform": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "claude_subscription",
                "codex_subscription",
                "platform",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "claude_subscription": {
                    "default": 0,
                    "type": "integer"
                  },
                  "codex_subscription": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "platform": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "claude_subscription",
                  "codex_subscription",
                  "model",
                  "platform",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        },
        "memory": {
          "default": 0,
          "type": "integer"
        },
        "total": {
          "default": 0,
          "type": "integer"
        }
      },
      "required": [
        "charged",
        "cpu",
        "fee",
        "llm",
        "memory",
        "total"
      ],
      "type": "object"
    },
    "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": {
            "type": "integer"
          },
          "platform_max": {
            "type": "integer"
          },
          "spent": {
            "type": "integer"
          },
          "window_days": {
            "type": "integer"
          }
        },
        "required": [
          "window_days",
          "spent",
          "limit",
          "platform_max"
        ],
        "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.
Session 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
              }
            ]
          },
          "metadata": {
            "[str]": 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,
        "name": 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"
                      },
                      "metadata": {
                        "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"
                      },
                      "name": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "name",
                      "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"
                      },
                      "metadata": {
                        "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"
                      },
                      "name": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "name",
                      "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"
                      },
                      "metadata": {
                        "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"
                      },
                      "name": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "name",
                      "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"
                      },
                      "metadata": {
                        "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"
                      },
                      "name": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "name",
                      "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/{id}/metrics`](https://www.ellipsis.dev/docs/api/handlers/get-handlers-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.
Session 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,
        "name": 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"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "type": {
                "enum": [
                  "User",
                  "Organization",
                  "Bot",
                  "Mannequin"
                ],
                "type": "string"
              }
            },
            "required": [
              "avatar_url",
              "id",
              "login",
              "name",
              "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.
Session 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,
    "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,
    "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"
            },
            "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"
            },
            "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: none; any valid credential.
API key: Supported.
CLI user token: Supported.
Session token: Requires the ellipsis:api scope; no permissions.ellipsis grant is needed.
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
  },
  "session_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"
        }
      ]
    },
    "session_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",
    "session_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 configs

> List the code review configs on the account, newest first: each kind: code_review file, its reviewers, the repository file it syncs from, and the state of that sync.

Source: https://www.ellipsis.dev/docs/api/reviews/get-reviews-configs

## GET /v1/reviews/configs

List the code review configs on the account, newest first: each kind: code_review file, its reviewers, the repository file it syncs from, and the state of that sync.

Required permissions: read:reviews.
API key: Supported.
CLI user token: Supported.
Session 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": [
    {
      "config": {
        "budget": {
          "session": float
        },
        "ellipsis": {
          "description": str,
          "enabled": bool,
          "kind": "code_review",
          "metadata": {
            "annotations": {
              "[str]": str
            },
            "labels": [
              str
            ]
          },
          "name": str,
          "version": str
        },
        "output": {
          "comments": {
            "max_per_review": int,
            "max_per_reviewer": int
          },
          "on_fail": str,
          "on_pass": str,
          "summary": bool
        },
        "pull_requests": {
          "base": [
            str
          ],
          "draft": bool,
          "for": {
            "bots": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            },
            "teams": [
              str
            ],
            "users": { # bool | list[str]
              "exclude": [
                str
              ],
              "include": [ # bool
                str
              ]
            }
          },
          "head": [
            str
          ],
          "labels": [
            str
          ],
          "paths": [
            str
          ],
          "repositories": { # list[str]
            "exclude": [
              str
            ],
            "include": [
              str
            ]
          }
        },
        "reviewers": [
          {
            "budget": {
              "session": 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
            },
            "comments": {
              "max": int
            },
            "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
                }
              ]
            },
            "name": str,
            "paths": [
              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,
        "name": str,
        "type": str
      },
      "id": str,
      "last_sync_error": str,
      "last_synced_commit_sha": str,
      "name": str,
      "raw_yaml": 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.reviews.configs.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.reviews.configs.list();
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": {
          "config": {
            "additionalProperties": false,
            "properties": {
              "budget": {
                "additionalProperties": false,
                "properties": {
                  "session": {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "type": "object"
              },
              "ellipsis": {
                "additionalProperties": false,
                "properties": {
                  "description": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "enabled": {
                    "default": true,
                    "type": "boolean"
                  },
                  "kind": {
                    "const": "code_review",
                    "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": [
                  "kind"
                ],
                "type": "object"
              },
              "output": {
                "additionalProperties": false,
                "properties": {
                  "comments": {
                    "additionalProperties": false,
                    "properties": {
                      "max_per_review": {
                        "type": "integer"
                      },
                      "max_per_reviewer": {
                        "type": "integer"
                      }
                    },
                    "type": "object"
                  },
                  "on_fail": {
                    "default": "comment",
                    "enum": [
                      "comment",
                      "request_changes"
                    ],
                    "type": "string"
                  },
                  "on_pass": {
                    "default": "silent",
                    "enum": [
                      "silent",
                      "comment",
                      "approve"
                    ],
                    "type": "string"
                  },
                  "summary": {
                    "default": false,
                    "type": "boolean"
                  }
                },
                "type": "object"
              },
              "pull_requests": {
                "additionalProperties": false,
                "properties": {
                  "base": {
                    "default": [],
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "draft": {
                    "anyOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "for": {
                    "additionalProperties": false,
                    "properties": {
                      "bots": {
                        "type": "object"
                      },
                      "teams": {
                        "type": "array"
                      },
                      "users": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "bots",
                      "teams",
                      "users"
                    ],
                    "type": "object"
                  },
                  "head": {
                    "default": [],
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "labels": {
                    "default": [],
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "paths": {
                    "default": [],
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "repositories": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "array"
                      }
                    ]
                  }
                },
                "type": "object"
              },
              "reviewers": {
                "items": {
                  "additionalProperties": false,
                  "allOf": [
                    {
                      "type": "object"
                    }
                  ],
                  "properties": {
                    "budget": {
                      "type": "object"
                    },
                    "claude_code": {
                      "type": "object"
                    },
                    "codex": {
                      "type": "object"
                    },
                    "comments": {
                      "type": "object"
                    },
                    "environment": {
                      "type": "object"
                    },
                    "name": {
                      "type": "string"
                    },
                    "paths": {
                      "type": "array"
                    },
                    "permissions": {
                      "type": "object"
                    },
                    "skills": {
                      "type": "array"
                    }
                  },
                  "required": [
                    "name"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "ellipsis",
              "reviewers"
            ],
            "type": "object"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "edited_by": {
            "anyOf": [
              {
                "properties": {
                  "avatar_url": {
                    "type": "string"
                  },
                  "id": {
                    "type": "integer"
                  },
                  "login": {
                    "type": "string"
                  },
                  "name": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "type": {
                    "enum": [
                      "User",
                      "Organization",
                      "Bot",
                      "Mannequin"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "avatar_url",
                  "id",
                  "login",
                  "name",
                  "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"
              }
            ]
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "raw_yaml": {
            "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",
          "config",
          "raw_yaml",
          "source_details"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "configs"
  ],
  "type": "object"
}
```

---

# Get a review

> Read a code review with its reviewers and every comment they returned, including the ones held back for anchoring outside the reviewed range.

Source: https://www.ellipsis.dev/docs/api/reviews/get-reviews-id

## GET /v1/reviews/{id}

Read a code review with its reviewers and every comment they returned, including the ones held back for anchoring outside the reviewed range.

Required permissions: read:reviews.
API key: Supported.
CLI user token: Supported.
Session 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
{
  "base_sha": str,
  "budget": int,
  "comments": [
    {
      "blocking": bool,
      "body": str,
      "id": str,
      "line": int,
      "path": str,
      "reviewer": str,
      "side": str,
      "start_line": int,
      "start_side": str,
      "status": str
    }
  ],
  "cost": {
    "charged": int,
    "cpu": int,
    "fee": int,
    "llm": {
      "all": {
        "claude_subscription": int,
        "codex_subscription": int,
        "platform": int,
        "total": int
      },
      "by_model": [
        {
          "claude_subscription": int,
          "codex_subscription": int,
          "model": str,
          "platform": int,
          "total": int
        }
      ]
    },
    "memory": int,
    "total": int
  },
  "created_at": str,
  "error": str,
  "event": str,
  "finalized_at": str,
  "findings": int,
  "github_review_id": int,
  "head_sha": str,
  "id": str,
  "pull_request": {
    "additions": int,
    "author": {
      "avatar_url": str,
      "id": int,
      "login": str,
      "type": str
    },
    "changed_files": int,
    "commits": int,
    "deletions": int,
    "number": int,
    "title": str,
    "url": str
  },
  "repository": {
    "id": int,
    "name": str,
    "owner": str
  },
  "reviewers": [
    {
      "error": str,
      "finished_at": str,
      "name": str,
      "range_base_sha": str,
      "reviewed_files": int,
      "reviewed_lines": int,
      "session_id": str,
      "status": str,
      "summary": str
    }
  ],
  "status": str,
  "tokens": {
    "all": {
      "cache_creation": int,
      "cache_read": int,
      "input": int,
      "output": int,
      "total": int
    },
    "by_model": [
      {
        "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.reviews.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.reviews.get('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/reviews/{id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "base_sha": {
      "type": "string"
    },
    "budget": {
      "type": "integer"
    },
    "comments": {
      "items": {
        "properties": {
          "blocking": {
            "type": "boolean"
          },
          "body": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "line": {
            "type": "integer"
          },
          "path": {
            "type": "string"
          },
          "reviewer": {
            "type": "string"
          },
          "side": {
            "type": "string"
          },
          "start_line": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "start_side": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "enum": [
              "eligible",
              "posted",
              "outside_range",
              "not_in_diff"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "reviewer",
          "path",
          "line",
          "side",
          "body",
          "blocking",
          "status"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "cost": {
      "properties": {
        "charged": {
          "default": 0,
          "type": "integer"
        },
        "cpu": {
          "default": 0,
          "type": "integer"
        },
        "fee": {
          "default": 0,
          "type": "integer"
        },
        "llm": {
          "properties": {
            "all": {
              "properties": {
                "claude_subscription": {
                  "default": 0,
                  "type": "integer"
                },
                "codex_subscription": {
                  "default": 0,
                  "type": "integer"
                },
                "platform": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "claude_subscription",
                "codex_subscription",
                "platform",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "claude_subscription": {
                    "default": 0,
                    "type": "integer"
                  },
                  "codex_subscription": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "platform": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "claude_subscription",
                  "codex_subscription",
                  "model",
                  "platform",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        },
        "memory": {
          "default": 0,
          "type": "integer"
        },
        "total": {
          "default": 0,
          "type": "integer"
        }
      },
      "required": [
        "charged",
        "cpu",
        "fee",
        "llm",
        "memory",
        "total"
      ],
      "type": "object"
    },
    "created_at": {
      "format": "date-time",
      "type": "string"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "event": {
      "anyOf": [
        {
          "enum": [
            "COMMENT",
            "APPROVE",
            "REQUEST_CHANGES"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "finalized_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "findings": {
      "type": "integer"
    },
    "github_review_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "head_sha": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "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"
            }
          ]
        },
        "changed_files": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "commits": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "deletions": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "number": {
          "type": "integer"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "number",
        "url"
      ],
      "type": "object"
    },
    "repository": {
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "owner": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "owner",
        "name"
      ],
      "type": "object"
    },
    "reviewers": {
      "items": {
        "properties": {
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "finished_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "range_base_sha": {
            "type": "string"
          },
          "reviewed_files": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "reviewed_lines": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "session_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "running",
              "completed",
              "failed"
            ],
            "type": "string"
          },
          "summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "name",
          "session_id",
          "range_base_sha",
          "status"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "status": {
      "enum": [
        "running",
        "posting",
        "posted",
        "empty",
        "failed"
      ],
      "type": "string"
    },
    "tokens": {
      "properties": {
        "all": {
          "properties": {
            "cache_creation": {
              "default": 0,
              "type": "integer"
            },
            "cache_read": {
              "default": 0,
              "type": "integer"
            },
            "input": {
              "default": 0,
              "type": "integer"
            },
            "output": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "cache_creation",
            "cache_read",
            "input",
            "output",
            "total"
          ],
          "type": "object"
        },
        "by_model": {
          "items": {
            "properties": {
              "cache_creation": {
                "default": 0,
                "type": "integer"
              },
              "cache_read": {
                "default": 0,
                "type": "integer"
              },
              "input": {
                "default": 0,
                "type": "integer"
              },
              "model": {
                "type": "string"
              },
              "output": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "cache_creation",
              "cache_read",
              "input",
              "model",
              "output",
              "total"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "all",
        "by_model"
      ],
      "type": "object"
    }
  },
  "required": [
    "id",
    "repository",
    "pull_request",
    "base_sha",
    "head_sha",
    "status",
    "findings",
    "created_at",
    "reviewers",
    "comments",
    "cost",
    "budget",
    "tokens"
  ],
  "type": "object"
}
```

---

# List reviews

> List code reviews newest first. Filter by repository, pull request number, and status, and page with limit and cursor.

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

## GET /v1/reviews

List code reviews newest first. Filter by repository, pull request number, and status, and page with limit and cursor.

Required permissions: read:reviews.
API key: Supported.
CLI user token: Supported.
Session 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": [
    {
      "base_sha": str,
      "created_at": str,
      "error": str,
      "event": str,
      "finalized_at": str,
      "findings": int,
      "github_review_id": int,
      "head_sha": str,
      "id": str,
      "pull_request": {
        "additions": int,
        "author": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "type": str
        },
        "changed_files": int,
        "commits": int,
        "deletions": int,
        "number": int,
        "title": str,
        "url": str
      },
      "repository": {
        "id": int,
        "name": str,
        "owner": str
      },
      "status": 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": {
          "base_sha": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "event": {
            "anyOf": [
              {
                "enum": [
                  "COMMENT",
                  "APPROVE",
                  "REQUEST_CHANGES"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "finalized_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "findings": {
            "type": "integer"
          },
          "github_review_id": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "head_sha": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "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"
                  }
                ]
              },
              "changed_files": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "commits": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "deletions": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "number": {
                "type": "integer"
              },
              "title": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "url": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "number",
              "url"
            ],
            "type": "object"
          },
          "repository": {
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "owner": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "owner",
              "name"
            ],
            "type": "object"
          },
          "status": {
            "enum": [
              "running",
              "posting",
              "posted",
              "empty",
              "failed"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "repository",
          "pull_request",
          "base_sha",
          "head_sha",
          "status",
          "findings",
          "created_at"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "reviews"
  ],
  "type": "object"
}
```

---

# Reviews

> Code reviews run one reviewer session per push and post one review on the pull request. List reviews and read every comment a reviewer returned.

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

- [`GET /v1/reviews`](https://www.ellipsis.dev/docs/api/reviews/get-reviews): List reviews
- [`GET /v1/reviews/{id}`](https://www.ellipsis.dev/docs/api/reviews/get-reviews-id): Get a review
- [`GET /v1/reviews/configs`](https://www.ellipsis.dev/docs/api/reviews/get-reviews-configs): List review configs

---

# 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.
Session token: Not supported by session 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.
Session 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.
Session token: Not supported by session 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 changes

> Read the changes produced by a session.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-id-diff

## GET /v1/sessions/{id}/diff

Read the changes produced by a session.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Session 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{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-id-download

## GET /v1/sessions/{id}/download

Download the session transcript.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Session 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{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"
}
```

---

# Get commits and pull requests

> Read commits and pull requests associated with a session.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-id-git

## GET /v1/sessions/{id}/git

Read commits and pull requests associated with a session.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Session 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,
                "name": 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{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"
}
```

---

# 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-id-records

## GET /v1/sessions/{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.
Session 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,
      "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,
      "turn_id": str
    }
  ],
  "next_cursor": str,
  "records": [ # list[ClaudeSessionRecord | ClaudeNativeSessionRecord |
  # CodexSessionRecord | CodexAppServerSessionRecord | SessionClosedRecord |
  # MessageReceivedRecord | MessageDeliveredRecord | MessageRequeuedRecord |
  # TurnQueuedRecord | TurnStartedRecord | TurnEndedRecord |
  # EnvironmentPhaseRecord | EnvironmentOutputRecord | EnvironmentReadyRecord |
  # 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,
      "session_id": str,
      "session_message_id": str,
      "source": "codex",
      "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("..."):
    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('...')) {
  console.log(item);
}
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{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"
              }
            ]
          },
          "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"
          },
          "turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "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"
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "const": "claude_code",
                "default": "claude_code",
                "type": "string"
              },
              "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",
              "turn_id",
              "session_message_id",
              "feed_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"
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "const": "claude_code",
                "default": "claude_code",
                "type": "string"
              },
              "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",
              "turn_id",
              "session_message_id",
              "feed_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"
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "const": "codex",
                "default": "codex",
                "type": "string"
              },
              "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",
              "turn_id",
              "session_message_id",
              "feed_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"
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "const": "codex",
                "default": "codex",
                "type": "string"
              },
              "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",
              "turn_id",
              "session_message_id",
              "feed_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": {},
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "session_closed",
                    "default": "session_closed",
                    "type": "string"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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"
                      },
                      "turn_id": {
                        "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"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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"
                      },
                      "requeued_turn_id": {
                        "type": "object"
                      },
                      "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"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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": {
                      "limit": {
                        "type": "integer"
                      },
                      "sessions_alive": {
                        "type": "integer"
                      },
                      "turn_id": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "turn_id",
                      "sessions_alive",
                      "limit"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "turn_queued",
                    "default": "turn_queued",
                    "type": "string"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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"
                      },
                      "reason": {
                        "type": "object"
                      },
                      "status": {
                        "type": "string"
                      },
                      "turn_id": {
                        "type": "string"
                      },
                      "turn_index": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "turn_id",
                      "turn_index",
                      "status"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "turn_ended",
                    "default": "turn_ended",
                    "type": "string"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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": "environment_phase",
                    "default": "environment_phase",
                    "type": "string"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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": "environment_output",
                    "default": "environment_output",
                    "type": "string"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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"
                      },
                      "repositories": {
                        "type": "array"
                      }
                    },
                    "required": [
                      "repositories"
                    ],
                    "type": "object"
                  },
                  "record_format": {
                    "const": "ellipsis_lifecycle@1",
                    "default": "ellipsis_lifecycle@1",
                    "type": "string"
                  },
                  "record_type": {
                    "const": "environment_ready",
                    "default": "environment_ready",
                    "type": "string"
                  },
                  "session_id": {
                    "type": "string"
                  },
                  "session_message_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "source": {
                    "const": "lifecycle",
                    "default": "lifecycle",
                    "type": "string"
                  },
                  "tokens_info": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tools": {
                    "anyOf": [
                      {
                        "type": "array"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "turn_id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "session_id",
                  "turn_id",
                  "session_message_id",
                  "feed_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"
              },
              "session_id": {
                "type": "string"
              },
              "session_message_id": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "source": {
                "type": "string"
              },
              "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",
              "turn_id",
              "session_message_id",
              "feed_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"
}
```

---

# List turns

> Read every turn and message of a session, oldest first. A turn is pending until the agent starts on it, running while it works, then completed, failed, stopped, or cancelled.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-id-turns

## GET /v1/sessions/{id}/turns

Read every turn and message of a session, oldest first. A turn is pending until the agent starts on it, running while it works, then completed, failed, stopped, or cancelled.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Session 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
{
  "messages": [
    {
      "author": str,
      "body": str,
      "created_at": str,
      "delivered_at": 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,
      "turn_id": str
    }
  ],
  "turns": [
    {
      "cost": {
        "charged": int,
        "cpu": int,
        "fee": int,
        "llm": {
          "all": {
            "claude_subscription": int,
            "codex_subscription": int,
            "platform": int,
            "total": int
          },
          "by_model": [
            {
              "claude_subscription": int,
              "codex_subscription": int,
              "model": str,
              "platform": int,
              "total": int
            }
          ]
        },
        "memory": int,
        "total": int
      },
      "created_at": str,
      "detail": str,
      "ended_at": str,
      "id": str,
      "index": int,
      "reason": str,
      "started_at": str,
      "status": str,
      "stopped": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "name": str,
          "type": str
        }
      },
      "tokens": {
        "all": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "output": int,
          "total": int
        },
        "by_model": [
          {
            "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.turns.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.sessions.turns.list('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{id}/turns" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "messages": {
      "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"
              }
            ]
          },
          "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"
          },
          "turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "session_id",
          "status",
          "body",
          "created_at"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "turns": {
      "items": {
        "properties": {
          "cost": {
            "properties": {
              "charged": {
                "default": 0,
                "type": "integer"
              },
              "cpu": {
                "default": 0,
                "type": "integer"
              },
              "fee": {
                "default": 0,
                "type": "integer"
              },
              "llm": {
                "properties": {
                  "all": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "by_model": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "all",
                  "by_model"
                ],
                "type": "object"
              },
              "memory": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "charged",
              "cpu",
              "fee",
              "llm",
              "memory",
              "total"
            ],
            "type": "object"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "detail": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "ended_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string"
          },
          "index": {
            "type": "integer"
          },
          "reason": {
            "anyOf": [
              {
                "enum": [
                  "error",
                  "tool_call_failed",
                  "budget_hit",
                  "payment_required",
                  "blocked",
                  "contact_email_required",
                  "lifecycle_hook_failed",
                  "missing_repo_access",
                  "missing_token_permissions",
                  "missing_environment_variables",
                  "missing_github_integration",
                  "agent_unavailable",
                  "upstream_unavailable",
                  "unsupported_configuration",
                  "execution_disabled",
                  "interrupted"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "started_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "enum": [
              "queued",
              "preparing",
              "running",
              "completed",
              "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"
              }
            ]
          },
          "tokens": {
            "properties": {
              "all": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "by_model": {
                "items": {
                  "properties": {
                    "cache_creation": {
                      "type": "integer"
                    },
                    "cache_read": {
                      "type": "integer"
                    },
                    "input": {
                      "type": "integer"
                    },
                    "model": {
                      "type": "string"
                    },
                    "output": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "cache_creation",
                    "cache_read",
                    "input",
                    "model",
                    "output",
                    "total"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "all",
              "by_model"
            ],
            "type": "object"
          }
        },
        "required": [
          "cost",
          "created_at",
          "detail",
          "ended_at",
          "id",
          "index",
          "reason",
          "started_at",
          "status",
          "stopped",
          "tokens"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "turns",
    "messages"
  ],
  "type": "object"
}
```

---

# Get a session

> Read a session: its conversation, current turn, cost, and settings.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-id

## GET /v1/sessions/{id}

Read a session: its conversation, current turn, cost, and settings.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Session 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
          },
          "conversation": {
            "interactive": bool
          },
          "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
              }
            ]
          },
          "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
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "check_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "check_suite": {
            "apps": [
              str
            ],
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "enabled": bool,
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "release": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "prerelease": bool,
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            },
            "tag": [
              str
            ]
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "status": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "type": "react",
          "workflow_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          }
        }
      },
      "id": str
    },
    "archived": {
      "at": str,
      "by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "attribution": {
      "id": str,
      "type": str,
      "user": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "budget": int,
    "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
    },
    "conversation": {
      "interactive": bool,
      "prompting": {
        "blocked_reason": str,
        "detail": str,
        "enabled": bool,
        "surface_name": str
      },
      "state": str,
      "warm": bool
    },
    "cost": {
      "charged": int,
      "cpu": int,
      "fee": int,
      "llm": {
        "all": {
          "claude_subscription": int,
          "codex_subscription": int,
          "platform": int,
          "total": int
        },
        "by_model": [
          {
            "claude_subscription": int,
            "codex_subscription": int,
            "model": str,
            "platform": int,
            "total": int
          }
        ]
      },
      "memory": int,
      "total": int
    },
    "created_at": str,
    "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 | GithubWorkflowRunEvent | GithubPullRequestEvent |
    # GithubIssueEvent | GithubPushEvent | GithubCheckRunEvent |
    # GithubCheckSuiteEvent | GithubStatusEvent | GithubReleaseEvent |
    # LinearIssueEvent | SlackMessageEvent | SlackChannelCreatedEvent |
    # SentryAlertEvent
      "action": str,
      "actor": {
        "avatar_url": str,
        "is_bot": bool,
        "name": str
      },
      "branch": str,
      "conclusion": str,
      "head_sha": str,
      "name": str,
      "pull_request_number": int,
      "repository": str,
      "run_number": int,
      "type": "github.workflow_run",
      "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,
    "metadata": {
      "[str]": str
    },
    "output": {
      "json_schema": {
        "[str]": any
      },
      "result": {
        "[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": {
      "all": {
        "cache_creation": int,
        "cache_read": int,
        "input": int,
        "output": int,
        "total": int
      },
      "by_model": [
        {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "model": str,
          "output": int,
          "total": int
        }
      ]
    },
    "turn": {
      "cost": {
        "charged": int,
        "cpu": int,
        "fee": int,
        "llm": {
          "all": {
            "claude_subscription": int,
            "codex_subscription": int,
            "platform": int,
            "total": int
          },
          "by_model": [
            {
              "claude_subscription": int,
              "codex_subscription": int,
              "model": str,
              "platform": int,
              "total": int
            }
          ]
        },
        "memory": int,
        "total": int
      },
      "created_at": str,
      "detail": str,
      "ended_at": str,
      "id": str,
      "index": int,
      "reason": str,
      "started_at": str,
      "status": str,
      "stopped": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "name": str,
          "type": str
        }
      },
      "tokens": {
        "all": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "output": int,
          "total": int
        },
        "by_model": [
          {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": int
          }
        ]
      }
    },
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

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

result = client.sessions.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.sessions.get('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{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"
                        },
                        "conversation": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "budget",
                        "claude_code",
                        "codex",
                        "conversation",
                        "environment",
                        "metadata",
                        "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"
            }
          ]
        },
        "archived": {
          "anyOf": [
            {
              "properties": {
                "at": {
                  "format": "date-time",
                  "type": "string"
                },
                "by": {
                  "anyOf": [
                    {
                      "properties": {
                        "avatar_url": {
                          "type": "string"
                        },
                        "id": {
                          "type": "integer"
                        },
                        "login": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "avatar_url",
                        "id",
                        "login",
                        "name",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "at",
                "by"
              ],
              "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"
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "enum": [
                        "User",
                        "Organization",
                        "Bot",
                        "Mannequin"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "avatar_url",
                    "id",
                    "login",
                    "name",
                    "type"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "type",
            "user"
          ],
          "type": "object"
        },
        "budget": {
          "default": 0,
          "type": "integer"
        },
        "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": {
                  "type": "string"
                },
                "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": {
                  "type": "string"
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "model",
                "prompt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "conversation": {
          "properties": {
            "interactive": {
              "type": "boolean"
            },
            "prompting": {
              "properties": {
                "blocked_reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "mention_surface",
                        "non_interactive",
                        "harness_single_turn",
                        "budget_exhausted",
                        "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"
            },
            "state": {
              "enum": [
                "open",
                "closed"
              ],
              "type": "string"
            },
            "warm": {
              "type": "boolean"
            }
          },
          "required": [
            "interactive",
            "prompting",
            "state",
            "warm"
          ],
          "type": "object"
        },
        "cost": {
          "properties": {
            "charged": {
              "default": 0,
              "type": "integer"
            },
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "properties": {
                "all": {
                  "properties": {
                    "claude_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "codex_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "platform": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "claude_subscription",
                    "codex_subscription",
                    "platform",
                    "total"
                  ],
                  "type": "object"
                },
                "by_model": {
                  "items": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "model": {
                        "type": "string"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "model",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "all",
                "by_model"
              ],
              "type": "object"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "charged",
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "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": {
                      "enum": [
                        "requested",
                        "queued",
                        "waiting",
                        "pending",
                        "started",
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.check_run",
                      "default": "github.check_run",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "name",
                    "pull_request_number",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale",
                        "startup_failure"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "app": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.check_suite",
                      "default": "github.check_suite",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "app",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "pull_request_number",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "requested",
                        "queued",
                        "waiting",
                        "pending",
                        "started",
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale",
                        "startup_failure"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "run_number": {
                      "type": "integer"
                    },
                    "type": {
                      "const": "github.workflow_run",
                      "default": "github.workflow_run",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "name",
                    "pull_request_number",
                    "repository",
                    "run_number",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "pending",
                        "passed",
                        "failed",
                        "errored"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "context": {
                      "type": "string"
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.status",
                      "default": "github.status",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "context",
                    "head_sha",
                    "pull_request_number",
                    "repository",
                    "state",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "published"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "prerelease": {
                      "type": "boolean"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "tag": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.release",
                      "default": "github.release",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "name",
                    "prerelease",
                    "repository",
                    "tag",
                    "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"
        },
        "metadata": {
          "items": {
            "type": "string"
          },
          "default": {},
          "type": "object"
        },
        "output": {
          "anyOf": [
            {
              "properties": {
                "json_schema": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "result": {
                  "anyOf": [
                    {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "json_schema",
                "result"
              ],
              "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",
            "code_review",
            "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": {
            "all": {
              "properties": {
                "cache_creation": {
                  "default": 0,
                  "type": "integer"
                },
                "cache_read": {
                  "default": 0,
                  "type": "integer"
                },
                "input": {
                  "default": 0,
                  "type": "integer"
                },
                "output": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "cache_creation",
                "cache_read",
                "input",
                "output",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "model",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        },
        "turn": {
          "anyOf": [
            {
              "properties": {
                "cost": {
                  "properties": {
                    "charged": {
                      "default": 0,
                      "type": "integer"
                    },
                    "cpu": {
                      "default": 0,
                      "type": "integer"
                    },
                    "fee": {
                      "default": 0,
                      "type": "integer"
                    },
                    "llm": {
                      "properties": {
                        "all": {
                          "type": "object"
                        },
                        "by_model": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "all",
                        "by_model"
                      ],
                      "type": "object"
                    },
                    "memory": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "charged",
                    "cpu",
                    "fee",
                    "llm",
                    "memory",
                    "total"
                  ],
                  "type": "object"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "detail": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "ended_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "id": {
                  "type": "string"
                },
                "index": {
                  "type": "integer"
                },
                "reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "error",
                        "tool_call_failed",
                        "budget_hit",
                        "payment_required",
                        "blocked",
                        "contact_email_required",
                        "lifecycle_hook_failed",
                        "missing_repo_access",
                        "missing_token_permissions",
                        "missing_environment_variables",
                        "missing_github_integration",
                        "agent_unavailable",
                        "upstream_unavailable",
                        "unsupported_configuration",
                        "execution_disabled",
                        "interrupted"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "started_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "enum": [
                    "queued",
                    "preparing",
                    "running",
                    "completed",
                    "failed",
                    "stopped",
                    "cancelled"
                  ],
                  "type": "string"
                },
                "stopped": {
                  "anyOf": [
                    {
                      "properties": {
                        "at": {
                          "type": "string"
                        },
                        "by": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "at",
                        "by"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "tokens": {
                  "properties": {
                    "all": {
                      "properties": {
                        "cache_creation": {
                          "type": "integer"
                        },
                        "cache_read": {
                          "type": "integer"
                        },
                        "input": {
                          "type": "integer"
                        },
                        "output": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "cache_creation",
                        "cache_read",
                        "input",
                        "output",
                        "total"
                      ],
                      "type": "object"
                    },
                    "by_model": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "all",
                    "by_model"
                  ],
                  "type": "object"
                }
              },
              "required": [
                "cost",
                "created_at",
                "detail",
                "ended_at",
                "id",
                "index",
                "reason",
                "started_at",
                "status",
                "stopped",
                "tokens"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "agent",
        "archived",
        "attribution",
        "budget",
        "claude_code",
        "codex",
        "conversation",
        "cost",
        "created_at",
        "environment",
        "event",
        "git",
        "handler",
        "id",
        "metadata",
        "output",
        "parent",
        "permissions",
        "skills",
        "source",
        "summary",
        "tokens",
        "turn",
        "updated_at"
      ],
      "type": "object"
    }
  },
  "required": [
    "session"
  ],
  "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.
Session 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
              },
              "conversation": {
                "interactive": bool
              },
              "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
                  }
                ]
              },
              "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
                  ]
                }
              },
              "skills": [
                {
                  "path": str,
                  "repository": {
                    "name": str,
                    "owner": str,
                    "ref": str
                  }
                }
              ]
            },
            "trigger": { # null | ReactTrigger | CronTrigger
              "check_run": {
                "branch": [
                  str
                ],
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "teams": [
                    str
                  ],
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "names": [
                  str
                ],
                "on": [
                  str
                ],
                "repositories": { # list[str]
                  "exclude": [
                    str
                  ],
                  "include": [
                    str
                  ]
                }
              },
              "check_suite": {
                "apps": [
                  str
                ],
                "branch": [
                  str
                ],
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "teams": [
                    str
                  ],
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "on": [
                  str
                ],
                "repositories": { # list[str]
                  "exclude": [
                    str
                  ],
                  "include": [
                    str
                  ]
                }
              },
              "enabled": bool,
              "issue": {
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "teams": [
                    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
                    ]
                  },
                  "teams": [
                    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
                    ]
                  },
                  "teams": [
                    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
                    ]
                  },
                  "teams": [
                    str
                  ],
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "paths": [
                  str
                ],
                "repositories": { # list[str]
                  "exclude": [
                    str
                  ],
                  "include": [
                    str
                  ]
                }
              },
              "release": {
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "teams": [
                    str
                  ],
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "on": [
                  str
                ],
                "prerelease": bool,
                "repositories": { # list[str]
                  "exclude": [
                    str
                  ],
                  "include": [
                    str
                  ]
                },
                "tag": [
                  str
                ]
              },
              "sentry": {
                "on": [
                  str
                ],
                "projects": [
                  str
                ]
              },
              "slack_channel": {},
              "status": {
                "branch": [
                  str
                ],
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "teams": [
                    str
                  ],
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "names": [
                  str
                ],
                "on": [
                  str
                ],
                "repositories": { # list[str]
                  "exclude": [
                    str
                  ],
                  "include": [
                    str
                  ]
                }
              },
              "type": "react",
              "workflow_run": {
                "branch": [
                  str
                ],
                "for": {
                  "bots": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  },
                  "teams": [
                    str
                  ],
                  "users": { # bool | list[str]
                    "exclude": [
                      str
                    ],
                    "include": [ # bool
                      str
                    ]
                  }
                },
                "names": [
                  str
                ],
                "on": [
                  str
                ],
                "repositories": { # list[str]
                  "exclude": [
                    str
                  ],
                  "include": [
                    str
                  ]
                }
              }
            }
          },
          "id": str
        },
        "archived": {
          "at": str,
          "by": {
            "avatar_url": str,
            "id": int,
            "login": str,
            "name": str,
            "type": str
          }
        },
        "attribution": {
          "id": str,
          "type": str,
          "user": {
            "avatar_url": str,
            "id": int,
            "login": str,
            "name": str,
            "type": str
          }
        },
        "budget": int,
        "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
        },
        "conversation": {
          "interactive": bool,
          "prompting": {
            "blocked_reason": str,
            "detail": str,
            "enabled": bool,
            "surface_name": str
          },
          "state": str,
          "warm": bool
        },
        "cost": {
          "charged": int,
          "cpu": int,
          "fee": int,
          "llm": {
            "all": {
              "claude_subscription": int,
              "codex_subscription": int,
              "platform": int,
              "total": int
            },
            "by_model": [
              {
                "claude_subscription": int,
                "codex_subscription": int,
                "model": str,
                "platform": int,
                "total": int
              }
            ]
          },
          "memory": int,
          "total": int
        },
        "created_at": str,
        "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 | GithubWorkflowRunEvent | GithubPullRequestEvent |
        # GithubIssueEvent | GithubPushEvent | GithubCheckRunEvent |
        # GithubCheckSuiteEvent | GithubStatusEvent | GithubReleaseEvent |
        # LinearIssueEvent | SlackMessageEvent | SlackChannelCreatedEvent |
        # SentryAlertEvent
          "action": str,
          "actor": {
            "avatar_url": str,
            "is_bot": bool,
            "name": str
          },
          "branch": str,
          "conclusion": str,
          "head_sha": str,
          "name": str,
          "pull_request_number": int,
          "repository": str,
          "run_number": int,
          "type": "github.workflow_run",
          "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,
        "metadata": {
          "[str]": str
        },
        "output": {
          "json_schema": {
            "[str]": any
          },
          "result": {
            "[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": {
          "all": {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "output": int,
            "total": int
          },
          "by_model": [
            {
              "cache_creation": int,
              "cache_read": int,
              "input": int,
              "model": str,
              "output": int,
              "total": int
            }
          ]
        },
        "turn": {
          "cost": {
            "charged": int,
            "cpu": int,
            "fee": int,
            "llm": {
              "all": {
                "claude_subscription": int,
                "codex_subscription": int,
                "platform": int,
                "total": int
              },
              "by_model": [
                {
                  "claude_subscription": int,
                  "codex_subscription": int,
                  "model": str,
                  "platform": int,
                  "total": int
                }
              ]
            },
            "memory": int,
            "total": int
          },
          "created_at": str,
          "detail": str,
          "ended_at": str,
          "id": str,
          "index": int,
          "reason": str,
          "started_at": str,
          "status": str,
          "stopped": {
            "at": str,
            "by": {
              "avatar_url": str,
              "id": int,
              "login": str,
              "name": str,
              "type": str
            }
          },
          "tokens": {
            "all": {
              "cache_creation": int,
              "cache_read": int,
              "input": int,
              "output": int,
              "total": int
            },
            "by_model": [
              {
                "cache_creation": int,
                "cache_read": int,
                "input": int,
                "model": str,
                "output": int,
                "total": int
              }
            ]
          }
        },
        "updated_at": str
      }
    }
  ]
}
```

### 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"
                  }
                ]
              },
              "archived": {
                "anyOf": [
                  {
                    "properties": {
                      "at": {
                        "type": "string"
                      },
                      "by": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "at",
                      "by"
                    ],
                    "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": "integer"
              },
              "claude_code": {
                "anyOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "effort": {
                        "type": "object"
                      },
                      "fallback_model": {
                        "type": "object"
                      },
                      "max_turns": {
                        "type": "object"
                      },
                      "model": {
                        "type": "string"
                      },
                      "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"
                  }
                ]
              },
              "conversation": {
                "properties": {
                  "interactive": {
                    "type": "boolean"
                  },
                  "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"
                  },
                  "state": {
                    "enum": [
                      "open",
                      "closed"
                    ],
                    "type": "string"
                  },
                  "warm": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "interactive",
                  "prompting",
                  "state",
                  "warm"
                ],
                "type": "object"
              },
              "cost": {
                "properties": {
                  "charged": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cpu": {
                    "default": 0,
                    "type": "integer"
                  },
                  "fee": {
                    "default": 0,
                    "type": "integer"
                  },
                  "llm": {
                    "properties": {
                      "all": {
                        "type": "object"
                      },
                      "by_model": {
                        "type": "array"
                      }
                    },
                    "required": [
                      "all",
                      "by_model"
                    ],
                    "type": "object"
                  },
                  "memory": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "charged",
                  "cpu",
                  "fee",
                  "llm",
                  "memory",
                  "total"
                ],
                "type": "object"
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "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": "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"
              },
              "metadata": {
                "items": {
                  "type": "string"
                },
                "default": {},
                "type": "object"
              },
              "output": {
                "anyOf": [
                  {
                    "properties": {
                      "json_schema": {
                        "type": "object"
                      },
                      "result": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "json_schema",
                      "result"
                    ],
                    "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",
                  "code_review",
                  "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": {
                  "all": {
                    "properties": {
                      "cache_creation": {
                        "type": "integer"
                      },
                      "cache_read": {
                        "type": "integer"
                      },
                      "input": {
                        "type": "integer"
                      },
                      "output": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "cache_creation",
                      "cache_read",
                      "input",
                      "output",
                      "total"
                    ],
                    "type": "object"
                  },
                  "by_model": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "all",
                  "by_model"
                ],
                "type": "object"
              },
              "turn": {
                "anyOf": [
                  {
                    "properties": {
                      "cost": {
                        "type": "object"
                      },
                      "created_at": {
                        "type": "string"
                      },
                      "detail": {
                        "type": "object"
                      },
                      "ended_at": {
                        "type": "object"
                      },
                      "id": {
                        "type": "string"
                      },
                      "index": {
                        "type": "integer"
                      },
                      "reason": {
                        "type": "object"
                      },
                      "started_at": {
                        "type": "object"
                      },
                      "status": {
                        "type": "string"
                      },
                      "stopped": {
                        "type": "object"
                      },
                      "tokens": {
                        "type": "object"
                      }
                    },
                    "required": [
                      "cost",
                      "created_at",
                      "detail",
                      "ended_at",
                      "id",
                      "index",
                      "reason",
                      "started_at",
                      "status",
                      "stopped",
                      "tokens"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "updated_at": {
                "format": "date-time",
                "type": "string"
              }
            },
            "required": [
              "agent",
              "archived",
              "attribution",
              "budget",
              "claude_code",
              "codex",
              "conversation",
              "cost",
              "created_at",
              "environment",
              "event",
              "git",
              "handler",
              "id",
              "metadata",
              "output",
              "parent",
              "permissions",
              "skills",
              "source",
              "summary",
              "tokens",
              "turn",
              "updated_at"
            ],
            "type": "object"
          }
        },
        "required": [
          "session",
          "matched",
          "recap_snippet",
          "record_hits",
          "record_hit_count"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "type": "object"
}
```

---

# Get a turn

> Read one turn. Poll it after sending a message: the message is answered when the turn status is completed, failed, stopped, or cancelled.

Source: https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-turns-id

## GET /v1/sessions/{session_id}/turns/{id}

Read one turn. Poll it after sending a message: the message is answered when the turn status is completed, failed, stopped, or cancelled.

Required permissions: read:sessions.
API key: Supported.
CLI user token: Supported.
Session 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
{
  "turn": {
    "cost": {
      "charged": int,
      "cpu": int,
      "fee": int,
      "llm": {
        "all": {
          "claude_subscription": int,
          "codex_subscription": int,
          "platform": int,
          "total": int
        },
        "by_model": [
          {
            "claude_subscription": int,
            "codex_subscription": int,
            "model": str,
            "platform": int,
            "total": int
          }
        ]
      },
      "memory": int,
      "total": int
    },
    "created_at": str,
    "detail": str,
    "ended_at": str,
    "id": str,
    "index": int,
    "reason": str,
    "started_at": str,
    "status": str,
    "stopped": {
      "at": str,
      "by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "tokens": {
      "all": {
        "cache_creation": int,
        "cache_read": int,
        "input": int,
        "output": int,
        "total": int
      },
      "by_model": [
        {
          "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.turns.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.turns.get("session_example", '...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/turns/{id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
```

### Response schema

```json
{
  "properties": {
    "turn": {
      "properties": {
        "cost": {
          "properties": {
            "charged": {
              "default": 0,
              "type": "integer"
            },
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "properties": {
                "all": {
                  "properties": {
                    "claude_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "codex_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "platform": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "claude_subscription",
                    "codex_subscription",
                    "platform",
                    "total"
                  ],
                  "type": "object"
                },
                "by_model": {
                  "items": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "model": {
                        "type": "string"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "model",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "all",
                "by_model"
              ],
              "type": "object"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "charged",
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "detail": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "ended_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "index": {
          "type": "integer"
        },
        "reason": {
          "anyOf": [
            {
              "enum": [
                "error",
                "tool_call_failed",
                "budget_hit",
                "payment_required",
                "blocked",
                "contact_email_required",
                "lifecycle_hook_failed",
                "missing_repo_access",
                "missing_token_permissions",
                "missing_environment_variables",
                "missing_github_integration",
                "agent_unavailable",
                "upstream_unavailable",
                "unsupported_configuration",
                "execution_disabled",
                "interrupted"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "started_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "enum": [
            "queued",
            "preparing",
            "running",
            "completed",
            "failed",
            "stopped",
            "cancelled"
          ],
          "type": "string"
        },
        "stopped": {
          "anyOf": [
            {
              "properties": {
                "at": {
                  "format": "date-time",
                  "type": "string"
                },
                "by": {
                  "anyOf": [
                    {
                      "properties": {
                        "avatar_url": {
                          "type": "string"
                        },
                        "id": {
                          "type": "integer"
                        },
                        "login": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "avatar_url",
                        "id",
                        "login",
                        "name",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "at",
                "by"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "tokens": {
          "properties": {
            "all": {
              "properties": {
                "cache_creation": {
                  "default": 0,
                  "type": "integer"
                },
                "cache_read": {
                  "default": 0,
                  "type": "integer"
                },
                "input": {
                  "default": 0,
                  "type": "integer"
                },
                "output": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "cache_creation",
                "cache_read",
                "input",
                "output",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "model",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        }
      },
      "required": [
        "cost",
        "created_at",
        "detail",
        "ended_at",
        "id",
        "index",
        "reason",
        "started_at",
        "status",
        "stopped",
        "tokens"
      ],
      "type": "object"
    }
  },
  "required": [
    "turn"
  ],
  "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.
Session 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
            },
            "conversation": {
              "interactive": bool
            },
            "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
                }
              ]
            },
            "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
                ]
              }
            },
            "skills": [
              {
                "path": str,
                "repository": {
                  "name": str,
                  "owner": str,
                  "ref": str
                }
              }
            ]
          },
          "trigger": { # null | ReactTrigger | CronTrigger
            "check_run": {
              "branch": [
                str
              ],
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "teams": [
                  str
                ],
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "names": [
                str
              ],
              "on": [
                str
              ],
              "repositories": { # list[str]
                "exclude": [
                  str
                ],
                "include": [
                  str
                ]
              }
            },
            "check_suite": {
              "apps": [
                str
              ],
              "branch": [
                str
              ],
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "teams": [
                  str
                ],
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "on": [
                str
              ],
              "repositories": { # list[str]
                "exclude": [
                  str
                ],
                "include": [
                  str
                ]
              }
            },
            "enabled": bool,
            "issue": {
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "teams": [
                  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
                  ]
                },
                "teams": [
                  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
                  ]
                },
                "teams": [
                  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
                  ]
                },
                "teams": [
                  str
                ],
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "paths": [
                str
              ],
              "repositories": { # list[str]
                "exclude": [
                  str
                ],
                "include": [
                  str
                ]
              }
            },
            "release": {
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "teams": [
                  str
                ],
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "on": [
                str
              ],
              "prerelease": bool,
              "repositories": { # list[str]
                "exclude": [
                  str
                ],
                "include": [
                  str
                ]
              },
              "tag": [
                str
              ]
            },
            "sentry": {
              "on": [
                str
              ],
              "projects": [
                str
              ]
            },
            "slack_channel": {},
            "status": {
              "branch": [
                str
              ],
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "teams": [
                  str
                ],
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "names": [
                str
              ],
              "on": [
                str
              ],
              "repositories": { # list[str]
                "exclude": [
                  str
                ],
                "include": [
                  str
                ]
              }
            },
            "type": "react",
            "workflow_run": {
              "branch": [
                str
              ],
              "for": {
                "bots": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                },
                "teams": [
                  str
                ],
                "users": { # bool | list[str]
                  "exclude": [
                    str
                  ],
                  "include": [ # bool
                    str
                  ]
                }
              },
              "names": [
                str
              ],
              "on": [
                str
              ],
              "repositories": { # list[str]
                "exclude": [
                  str
                ],
                "include": [
                  str
                ]
              }
            }
          }
        },
        "id": str
      },
      "archived": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "name": str,
          "type": str
        }
      },
      "attribution": {
        "id": str,
        "type": str,
        "user": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "name": str,
          "type": str
        }
      },
      "budget": int,
      "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
      },
      "conversation": {
        "interactive": bool,
        "prompting": {
          "blocked_reason": str,
          "detail": str,
          "enabled": bool,
          "surface_name": str
        },
        "state": str,
        "warm": bool
      },
      "cost": {
        "charged": int,
        "cpu": int,
        "fee": int,
        "llm": {
          "all": {
            "claude_subscription": int,
            "codex_subscription": int,
            "platform": int,
            "total": int
          },
          "by_model": [
            {
              "claude_subscription": int,
              "codex_subscription": int,
              "model": str,
              "platform": int,
              "total": int
            }
          ]
        },
        "memory": int,
        "total": int
      },
      "created_at": str,
      "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 | GithubWorkflowRunEvent | GithubPullRequestEvent |
      # GithubIssueEvent | GithubPushEvent | GithubCheckRunEvent |
      # GithubCheckSuiteEvent | GithubStatusEvent | GithubReleaseEvent |
      # LinearIssueEvent | SlackMessageEvent | SlackChannelCreatedEvent |
      # SentryAlertEvent
        "action": str,
        "actor": {
          "avatar_url": str,
          "is_bot": bool,
          "name": str
        },
        "branch": str,
        "conclusion": str,
        "head_sha": str,
        "name": str,
        "pull_request_number": int,
        "repository": str,
        "run_number": int,
        "type": "github.workflow_run",
        "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,
      "metadata": {
        "[str]": str
      },
      "output": {
        "json_schema": {
          "[str]": any
        },
        "result": {
          "[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": {
        "all": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "output": int,
          "total": int
        },
        "by_model": [
          {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": int
          }
        ]
      },
      "turn": {
        "cost": {
          "charged": int,
          "cpu": int,
          "fee": int,
          "llm": {
            "all": {
              "claude_subscription": int,
              "codex_subscription": int,
              "platform": int,
              "total": int
            },
            "by_model": [
              {
                "claude_subscription": int,
                "codex_subscription": int,
                "model": str,
                "platform": int,
                "total": int
              }
            ]
          },
          "memory": int,
          "total": int
        },
        "created_at": str,
        "detail": str,
        "ended_at": str,
        "id": str,
        "index": int,
        "reason": str,
        "started_at": str,
        "status": str,
        "stopped": {
          "at": str,
          "by": {
            "avatar_url": str,
            "id": int,
            "login": str,
            "name": str,
            "type": str
          }
        },
        "tokens": {
          "all": {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "output": int,
            "total": int
          },
          "by_model": [
            {
              "cache_creation": int,
              "cache_read": int,
              "input": int,
              "model": str,
              "output": int,
              "total": int
            }
          ]
        }
      },
      "updated_at": str
    }
  ],
  "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"
              }
            ]
          },
          "archived": {
            "anyOf": [
              {
                "properties": {
                  "at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "by": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "at",
                  "by"
                ],
                "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"
                      },
                      "name": {
                        "type": "object"
                      },
                      "type": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "avatar_url",
                      "id",
                      "login",
                      "name",
                      "type"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "id",
              "type",
              "user"
            ],
            "type": "object"
          },
          "budget": {
            "default": 0,
            "type": "integer"
          },
          "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": {
                    "type": "string"
                  },
                  "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": {
                    "type": "string"
                  },
                  "prompt": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "effort",
                  "model",
                  "prompt"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "conversation": {
            "properties": {
              "interactive": {
                "type": "boolean"
              },
              "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"
              },
              "state": {
                "enum": [
                  "open",
                  "closed"
                ],
                "type": "string"
              },
              "warm": {
                "type": "boolean"
              }
            },
            "required": [
              "interactive",
              "prompting",
              "state",
              "warm"
            ],
            "type": "object"
          },
          "cost": {
            "properties": {
              "charged": {
                "default": 0,
                "type": "integer"
              },
              "cpu": {
                "default": 0,
                "type": "integer"
              },
              "fee": {
                "default": 0,
                "type": "integer"
              },
              "llm": {
                "properties": {
                  "all": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "by_model": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "all",
                  "by_model"
                ],
                "type": "object"
              },
              "memory": {
                "default": 0,
                "type": "integer"
              },
              "total": {
                "default": 0,
                "type": "integer"
              }
            },
            "required": [
              "charged",
              "cpu",
              "fee",
              "llm",
              "memory",
              "total"
            ],
            "type": "object"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "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": "string"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "branch": {
                        "type": "object"
                      },
                      "conclusion": {
                        "type": "object"
                      },
                      "head_sha": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "pull_request_number": {
                        "type": "object"
                      },
                      "repository": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "branch",
                      "conclusion",
                      "head_sha",
                      "name",
                      "pull_request_number",
                      "repository",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "action": {
                        "type": "string"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "app": {
                        "type": "object"
                      },
                      "branch": {
                        "type": "object"
                      },
                      "conclusion": {
                        "type": "object"
                      },
                      "head_sha": {
                        "type": "string"
                      },
                      "pull_request_number": {
                        "type": "object"
                      },
                      "repository": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "app",
                      "branch",
                      "conclusion",
                      "head_sha",
                      "pull_request_number",
                      "repository",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "action": {
                        "type": "string"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "branch": {
                        "type": "object"
                      },
                      "conclusion": {
                        "type": "object"
                      },
                      "head_sha": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "pull_request_number": {
                        "type": "object"
                      },
                      "repository": {
                        "type": "string"
                      },
                      "run_number": {
                        "type": "integer"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "branch",
                      "conclusion",
                      "head_sha",
                      "name",
                      "pull_request_number",
                      "repository",
                      "run_number",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "action": {
                        "type": "string"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "branch": {
                        "type": "object"
                      },
                      "context": {
                        "type": "string"
                      },
                      "head_sha": {
                        "type": "string"
                      },
                      "pull_request_number": {
                        "type": "object"
                      },
                      "repository": {
                        "type": "string"
                      },
                      "state": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "branch",
                      "context",
                      "head_sha",
                      "pull_request_number",
                      "repository",
                      "state",
                      "type",
                      "url"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "action": {
                        "type": "string"
                      },
                      "actor": {
                        "type": "object"
                      },
                      "name": {
                        "type": "object"
                      },
                      "prerelease": {
                        "type": "boolean"
                      },
                      "repository": {
                        "type": "string"
                      },
                      "tag": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "actor",
                      "name",
                      "prerelease",
                      "repository",
                      "tag",
                      "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"
          },
          "metadata": {
            "items": {
              "type": "string"
            },
            "default": {},
            "type": "object"
          },
          "output": {
            "anyOf": [
              {
                "properties": {
                  "json_schema": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "result": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "json_schema",
                  "result"
                ],
                "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",
              "code_review",
              "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": {
              "all": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "by_model": {
                "items": {
                  "properties": {
                    "cache_creation": {
                      "type": "integer"
                    },
                    "cache_read": {
                      "type": "integer"
                    },
                    "input": {
                      "type": "integer"
                    },
                    "model": {
                      "type": "string"
                    },
                    "output": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "cache_creation",
                    "cache_read",
                    "input",
                    "model",
                    "output",
                    "total"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "all",
              "by_model"
            ],
            "type": "object"
          },
          "turn": {
            "anyOf": [
              {
                "properties": {
                  "cost": {
                    "properties": {
                      "charged": {
                        "type": "integer"
                      },
                      "cpu": {
                        "type": "integer"
                      },
                      "fee": {
                        "type": "integer"
                      },
                      "llm": {
                        "type": "object"
                      },
                      "memory": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "charged",
                      "cpu",
                      "fee",
                      "llm",
                      "memory",
                      "total"
                    ],
                    "type": "object"
                  },
                  "created_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "detail": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "ended_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "id": {
                    "type": "string"
                  },
                  "index": {
                    "type": "integer"
                  },
                  "reason": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "started_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "status": {
                    "enum": [
                      "queued",
                      "preparing",
                      "running",
                      "completed",
                      "failed",
                      "stopped",
                      "cancelled"
                    ],
                    "type": "string"
                  },
                  "stopped": {
                    "anyOf": [
                      {
                        "type": "object"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tokens": {
                    "properties": {
                      "all": {
                        "type": "object"
                      },
                      "by_model": {
                        "type": "array"
                      }
                    },
                    "required": [
                      "all",
                      "by_model"
                    ],
                    "type": "object"
                  }
                },
                "required": [
                  "cost",
                  "created_at",
                  "detail",
                  "ended_at",
                  "id",
                  "index",
                  "reason",
                  "started_at",
                  "status",
                  "stopped",
                  "tokens"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "agent",
          "archived",
          "attribution",
          "budget",
          "claude_code",
          "codex",
          "conversation",
          "cost",
          "created_at",
          "environment",
          "event",
          "git",
          "handler",
          "id",
          "metadata",
          "output",
          "parent",
          "permissions",
          "skills",
          "source",
          "summary",
          "tokens",
          "turn",
          "updated_at"
        ],
        "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

## 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

## Other endpoints

- [`GET /v1/sessions/{id}`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-id): Get a session
- [`GET /v1/sessions/{id}/diff`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-id-diff): Get changes
- [`GET /v1/sessions/{id}/download`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-id-download): Download a transcript
- [`GET /v1/sessions/{id}/git`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-id-git): Get commits and pull requests
- [`POST /v1/sessions/{id}/messages`](https://www.ellipsis.dev/docs/api/sessions/post-sessions-id-messages): Send a message
- [`GET /v1/sessions/{id}/records`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-id-records): List records
- [`POST /v1/sessions/{id}/stop`](https://www.ellipsis.dev/docs/api/sessions/post-sessions-id-stop): Stop a session
- [`GET /v1/sessions/{id}/turns`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-id-turns): List turns
- [`GET /v1/sessions/{session_id}/turns/{id}`](https://www.ellipsis.dev/docs/api/sessions/get-sessions-session_id-turns-id): Get a turn

---

# Send a message

> Send a follow-up to a conversation. The response carries the message and the turn that answers it; a message sent while a turn runs is answered after it. Reuse an idempotency key when retrying the same message.

Source: https://www.ellipsis.dev/docs/api/sessions/post-sessions-id-messages

## POST /v1/sessions/{id}/messages

Send a follow-up to a conversation. The response carries the message and the turn that answers it; a message sent while a turn runs is answered after it. Reuse an idempotency key when retrying the same message.

Required permissions: write:sessions.
API key: Supported.
CLI user token: Supported.
Session 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,
    "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,
    "turn_id": str
  },
  "turn": {
    "cost": {
      "charged": int,
      "cpu": int,
      "fee": int,
      "llm": {
        "all": {
          "claude_subscription": int,
          "codex_subscription": int,
          "platform": int,
          "total": int
        },
        "by_model": [
          {
            "claude_subscription": int,
            "codex_subscription": int,
            "model": str,
            "platform": int,
            "total": int
          }
        ]
      },
      "memory": int,
      "total": int
    },
    "created_at": str,
    "detail": str,
    "ended_at": str,
    "id": str,
    "index": int,
    "reason": str,
    "started_at": str,
    "status": str,
    "stopped": {
      "at": str,
      "by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "tokens": {
      "all": {
        "cache_creation": int,
        "cache_read": int,
        "input": int,
        "output": int,
        "total": int
      },
      "by_model": [
        {
          "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.SendSessionMessageRequest.model_validate(
    {
      "message": "Add a regression test.",
      "idempotency_key": "add-test"
    }
)

result = client.sessions.send_message(
    "...",
    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('...', request);
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/sessions/{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"
            }
          ]
        },
        "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"
        },
        "turn_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "session_id",
        "status",
        "body",
        "created_at"
      ],
      "type": "object"
    },
    "turn": {
      "properties": {
        "cost": {
          "properties": {
            "charged": {
              "default": 0,
              "type": "integer"
            },
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "properties": {
                "all": {
                  "properties": {
                    "claude_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "codex_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "platform": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "claude_subscription",
                    "codex_subscription",
                    "platform",
                    "total"
                  ],
                  "type": "object"
                },
                "by_model": {
                  "items": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "model": {
                        "type": "string"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "model",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "all",
                "by_model"
              ],
              "type": "object"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "charged",
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "detail": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "ended_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "index": {
          "type": "integer"
        },
        "reason": {
          "anyOf": [
            {
              "enum": [
                "error",
                "tool_call_failed",
                "budget_hit",
                "payment_required",
                "blocked",
                "contact_email_required",
                "lifecycle_hook_failed",
                "missing_repo_access",
                "missing_token_permissions",
                "missing_environment_variables",
                "missing_github_integration",
                "agent_unavailable",
                "upstream_unavailable",
                "unsupported_configuration",
                "execution_disabled",
                "interrupted"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "started_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "enum": [
            "queued",
            "preparing",
            "running",
            "completed",
            "failed",
            "stopped",
            "cancelled"
          ],
          "type": "string"
        },
        "stopped": {
          "anyOf": [
            {
              "properties": {
                "at": {
                  "format": "date-time",
                  "type": "string"
                },
                "by": {
                  "anyOf": [
                    {
                      "properties": {
                        "avatar_url": {
                          "type": "string"
                        },
                        "id": {
                          "type": "integer"
                        },
                        "login": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "avatar_url",
                        "id",
                        "login",
                        "name",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "at",
                "by"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "tokens": {
          "properties": {
            "all": {
              "properties": {
                "cache_creation": {
                  "default": 0,
                  "type": "integer"
                },
                "cache_read": {
                  "default": 0,
                  "type": "integer"
                },
                "input": {
                  "default": 0,
                  "type": "integer"
                },
                "output": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "cache_creation",
                "cache_read",
                "input",
                "output",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "model",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        }
      },
      "required": [
        "cost",
        "created_at",
        "detail",
        "ended_at",
        "id",
        "index",
        "reason",
        "started_at",
        "status",
        "stopped",
        "tokens"
      ],
      "type": "object"
    }
  },
  "required": [
    "message",
    "turn"
  ],
  "type": "object"
}
```

---

# Stop a session

> Stop the turn in progress. The turn ends stopped and the conversation stays open; the recorded history remains available.

Source: https://www.ellipsis.dev/docs/api/sessions/post-sessions-id-stop

## POST /v1/sessions/{id}/stop

Stop the turn in progress. The turn ends stopped and the conversation stays open; the recorded history remains available.

Required permissions: write:sessions.
API key: Supported.
CLI user token: Supported.
Session 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
          },
          "conversation": {
            "interactive": bool
          },
          "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
              }
            ]
          },
          "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
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "check_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "check_suite": {
            "apps": [
              str
            ],
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "enabled": bool,
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "release": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "prerelease": bool,
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            },
            "tag": [
              str
            ]
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "status": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "type": "react",
          "workflow_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          }
        }
      },
      "id": str
    },
    "archived": {
      "at": str,
      "by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "attribution": {
      "id": str,
      "type": str,
      "user": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "budget": int,
    "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
    },
    "conversation": {
      "interactive": bool,
      "prompting": {
        "blocked_reason": str,
        "detail": str,
        "enabled": bool,
        "surface_name": str
      },
      "state": str,
      "warm": bool
    },
    "cost": {
      "charged": int,
      "cpu": int,
      "fee": int,
      "llm": {
        "all": {
          "claude_subscription": int,
          "codex_subscription": int,
          "platform": int,
          "total": int
        },
        "by_model": [
          {
            "claude_subscription": int,
            "codex_subscription": int,
            "model": str,
            "platform": int,
            "total": int
          }
        ]
      },
      "memory": int,
      "total": int
    },
    "created_at": str,
    "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 | GithubWorkflowRunEvent | GithubPullRequestEvent |
    # GithubIssueEvent | GithubPushEvent | GithubCheckRunEvent |
    # GithubCheckSuiteEvent | GithubStatusEvent | GithubReleaseEvent |
    # LinearIssueEvent | SlackMessageEvent | SlackChannelCreatedEvent |
    # SentryAlertEvent
      "action": str,
      "actor": {
        "avatar_url": str,
        "is_bot": bool,
        "name": str
      },
      "branch": str,
      "conclusion": str,
      "head_sha": str,
      "name": str,
      "pull_request_number": int,
      "repository": str,
      "run_number": int,
      "type": "github.workflow_run",
      "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,
    "metadata": {
      "[str]": str
    },
    "output": {
      "json_schema": {
        "[str]": any
      },
      "result": {
        "[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": {
      "all": {
        "cache_creation": int,
        "cache_read": int,
        "input": int,
        "output": int,
        "total": int
      },
      "by_model": [
        {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "model": str,
          "output": int,
          "total": int
        }
      ]
    },
    "turn": {
      "cost": {
        "charged": int,
        "cpu": int,
        "fee": int,
        "llm": {
          "all": {
            "claude_subscription": int,
            "codex_subscription": int,
            "platform": int,
            "total": int
          },
          "by_model": [
            {
              "claude_subscription": int,
              "codex_subscription": int,
              "model": str,
              "platform": int,
              "total": int
            }
          ]
        },
        "memory": int,
        "total": int
      },
      "created_at": str,
      "detail": str,
      "ended_at": str,
      "id": str,
      "index": int,
      "reason": str,
      "started_at": str,
      "status": str,
      "stopped": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "name": str,
          "type": str
        }
      },
      "tokens": {
        "all": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "output": int,
          "total": int
        },
        "by_model": [
          {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": int
          }
        ]
      }
    },
    "updated_at": str
  }
}
```

### Python

```python
import os

from ellipsis import Ellipsis

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

result = client.sessions.stop("...")
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('...');
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/sessions/{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"
                        },
                        "conversation": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "budget",
                        "claude_code",
                        "codex",
                        "conversation",
                        "environment",
                        "metadata",
                        "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"
            }
          ]
        },
        "archived": {
          "anyOf": [
            {
              "properties": {
                "at": {
                  "format": "date-time",
                  "type": "string"
                },
                "by": {
                  "anyOf": [
                    {
                      "properties": {
                        "avatar_url": {
                          "type": "string"
                        },
                        "id": {
                          "type": "integer"
                        },
                        "login": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "avatar_url",
                        "id",
                        "login",
                        "name",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "at",
                "by"
              ],
              "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"
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "enum": [
                        "User",
                        "Organization",
                        "Bot",
                        "Mannequin"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "avatar_url",
                    "id",
                    "login",
                    "name",
                    "type"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "type",
            "user"
          ],
          "type": "object"
        },
        "budget": {
          "default": 0,
          "type": "integer"
        },
        "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": {
                  "type": "string"
                },
                "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": {
                  "type": "string"
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "model",
                "prompt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "conversation": {
          "properties": {
            "interactive": {
              "type": "boolean"
            },
            "prompting": {
              "properties": {
                "blocked_reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "mention_surface",
                        "non_interactive",
                        "harness_single_turn",
                        "budget_exhausted",
                        "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"
            },
            "state": {
              "enum": [
                "open",
                "closed"
              ],
              "type": "string"
            },
            "warm": {
              "type": "boolean"
            }
          },
          "required": [
            "interactive",
            "prompting",
            "state",
            "warm"
          ],
          "type": "object"
        },
        "cost": {
          "properties": {
            "charged": {
              "default": 0,
              "type": "integer"
            },
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "properties": {
                "all": {
                  "properties": {
                    "claude_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "codex_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "platform": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "claude_subscription",
                    "codex_subscription",
                    "platform",
                    "total"
                  ],
                  "type": "object"
                },
                "by_model": {
                  "items": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "model": {
                        "type": "string"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "model",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "all",
                "by_model"
              ],
              "type": "object"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "charged",
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "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": {
                      "enum": [
                        "requested",
                        "queued",
                        "waiting",
                        "pending",
                        "started",
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.check_run",
                      "default": "github.check_run",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "name",
                    "pull_request_number",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale",
                        "startup_failure"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "app": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.check_suite",
                      "default": "github.check_suite",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "app",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "pull_request_number",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "requested",
                        "queued",
                        "waiting",
                        "pending",
                        "started",
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale",
                        "startup_failure"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "run_number": {
                      "type": "integer"
                    },
                    "type": {
                      "const": "github.workflow_run",
                      "default": "github.workflow_run",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "name",
                    "pull_request_number",
                    "repository",
                    "run_number",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "pending",
                        "passed",
                        "failed",
                        "errored"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "context": {
                      "type": "string"
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.status",
                      "default": "github.status",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "context",
                    "head_sha",
                    "pull_request_number",
                    "repository",
                    "state",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "published"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "prerelease": {
                      "type": "boolean"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "tag": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.release",
                      "default": "github.release",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "name",
                    "prerelease",
                    "repository",
                    "tag",
                    "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"
        },
        "metadata": {
          "items": {
            "type": "string"
          },
          "default": {},
          "type": "object"
        },
        "output": {
          "anyOf": [
            {
              "properties": {
                "json_schema": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "result": {
                  "anyOf": [
                    {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "json_schema",
                "result"
              ],
              "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",
            "code_review",
            "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": {
            "all": {
              "properties": {
                "cache_creation": {
                  "default": 0,
                  "type": "integer"
                },
                "cache_read": {
                  "default": 0,
                  "type": "integer"
                },
                "input": {
                  "default": 0,
                  "type": "integer"
                },
                "output": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "cache_creation",
                "cache_read",
                "input",
                "output",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "model",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        },
        "turn": {
          "anyOf": [
            {
              "properties": {
                "cost": {
                  "properties": {
                    "charged": {
                      "default": 0,
                      "type": "integer"
                    },
                    "cpu": {
                      "default": 0,
                      "type": "integer"
                    },
                    "fee": {
                      "default": 0,
                      "type": "integer"
                    },
                    "llm": {
                      "properties": {
                        "all": {
                          "type": "object"
                        },
                        "by_model": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "all",
                        "by_model"
                      ],
                      "type": "object"
                    },
                    "memory": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "charged",
                    "cpu",
                    "fee",
                    "llm",
                    "memory",
                    "total"
                  ],
                  "type": "object"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "detail": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "ended_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "id": {
                  "type": "string"
                },
                "index": {
                  "type": "integer"
                },
                "reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "error",
                        "tool_call_failed",
                        "budget_hit",
                        "payment_required",
                        "blocked",
                        "contact_email_required",
                        "lifecycle_hook_failed",
                        "missing_repo_access",
                        "missing_token_permissions",
                        "missing_environment_variables",
                        "missing_github_integration",
                        "agent_unavailable",
                        "upstream_unavailable",
                        "unsupported_configuration",
                        "execution_disabled",
                        "interrupted"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "started_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "enum": [
                    "queued",
                    "preparing",
                    "running",
                    "completed",
                    "failed",
                    "stopped",
                    "cancelled"
                  ],
                  "type": "string"
                },
                "stopped": {
                  "anyOf": [
                    {
                      "properties": {
                        "at": {
                          "type": "string"
                        },
                        "by": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "at",
                        "by"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "tokens": {
                  "properties": {
                    "all": {
                      "properties": {
                        "cache_creation": {
                          "type": "integer"
                        },
                        "cache_read": {
                          "type": "integer"
                        },
                        "input": {
                          "type": "integer"
                        },
                        "output": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "cache_creation",
                        "cache_read",
                        "input",
                        "output",
                        "total"
                      ],
                      "type": "object"
                    },
                    "by_model": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "all",
                    "by_model"
                  ],
                  "type": "object"
                }
              },
              "required": [
                "cost",
                "created_at",
                "detail",
                "ended_at",
                "id",
                "index",
                "reason",
                "started_at",
                "status",
                "stopped",
                "tokens"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "agent",
        "archived",
        "attribution",
        "budget",
        "claude_code",
        "codex",
        "conversation",
        "cost",
        "created_at",
        "environment",
        "event",
        "git",
        "handler",
        "id",
        "metadata",
        "output",
        "parent",
        "permissions",
        "skills",
        "source",
        "summary",
        "tokens",
        "turn",
        "updated_at"
      ],
      "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 default environment. Set conversation.interactive to false to run once. The response carries the turn that answers the prompt.

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 default environment. Set conversation.interactive to false to run once. The response carries the turn that answers the prompt.

Required permissions: write:sessions.
API key: Supported.
CLI user token: Supported.
Session 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": {
    "session": 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
  },
  "conversation": {
    "interactive": bool
  },
  "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
    }
  ],
  "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
      ]
    }
  },
  "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
          },
          "conversation": {
            "interactive": bool
          },
          "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
              }
            ]
          },
          "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
              ]
            }
          },
          "skills": [
            {
              "path": str,
              "repository": {
                "name": str,
                "owner": str,
                "ref": str
              }
            }
          ]
        },
        "trigger": { # null | ReactTrigger | CronTrigger
          "check_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "check_suite": {
            "apps": [
              str
            ],
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "enabled": bool,
          "issue": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                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
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "paths": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "release": {
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "on": [
              str
            ],
            "prerelease": bool,
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            },
            "tag": [
              str
            ]
          },
          "sentry": {
            "on": [
              str
            ],
            "projects": [
              str
            ]
          },
          "slack_channel": {},
          "status": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          },
          "type": "react",
          "workflow_run": {
            "branch": [
              str
            ],
            "for": {
              "bots": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              },
              "teams": [
                str
              ],
              "users": { # bool | list[str]
                "exclude": [
                  str
                ],
                "include": [ # bool
                  str
                ]
              }
            },
            "names": [
              str
            ],
            "on": [
              str
            ],
            "repositories": { # list[str]
              "exclude": [
                str
              ],
              "include": [
                str
              ]
            }
          }
        }
      },
      "id": str
    },
    "archived": {
      "at": str,
      "by": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "attribution": {
      "id": str,
      "type": str,
      "user": {
        "avatar_url": str,
        "id": int,
        "login": str,
        "name": str,
        "type": str
      }
    },
    "budget": int,
    "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
    },
    "conversation": {
      "interactive": bool,
      "prompting": {
        "blocked_reason": str,
        "detail": str,
        "enabled": bool,
        "surface_name": str
      },
      "state": str,
      "warm": bool
    },
    "cost": {
      "charged": int,
      "cpu": int,
      "fee": int,
      "llm": {
        "all": {
          "claude_subscription": int,
          "codex_subscription": int,
          "platform": int,
          "total": int
        },
        "by_model": [
          {
            "claude_subscription": int,
            "codex_subscription": int,
            "model": str,
            "platform": int,
            "total": int
          }
        ]
      },
      "memory": int,
      "total": int
    },
    "created_at": str,
    "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 | GithubWorkflowRunEvent | GithubPullRequestEvent |
    # GithubIssueEvent | GithubPushEvent | GithubCheckRunEvent |
    # GithubCheckSuiteEvent | GithubStatusEvent | GithubReleaseEvent |
    # LinearIssueEvent | SlackMessageEvent | SlackChannelCreatedEvent |
    # SentryAlertEvent
      "action": str,
      "actor": {
        "avatar_url": str,
        "is_bot": bool,
        "name": str
      },
      "branch": str,
      "conclusion": str,
      "head_sha": str,
      "name": str,
      "pull_request_number": int,
      "repository": str,
      "run_number": int,
      "type": "github.workflow_run",
      "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,
    "metadata": {
      "[str]": str
    },
    "output": {
      "json_schema": {
        "[str]": any
      },
      "result": {
        "[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": {
      "all": {
        "cache_creation": int,
        "cache_read": int,
        "input": int,
        "output": int,
        "total": int
      },
      "by_model": [
        {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "model": str,
          "output": int,
          "total": int
        }
      ]
    },
    "turn": {
      "cost": {
        "charged": int,
        "cpu": int,
        "fee": int,
        "llm": {
          "all": {
            "claude_subscription": int,
            "codex_subscription": int,
            "platform": int,
            "total": int
          },
          "by_model": [
            {
              "claude_subscription": int,
              "codex_subscription": int,
              "model": str,
              "platform": int,
              "total": int
            }
          ]
        },
        "memory": int,
        "total": int
      },
      "created_at": str,
      "detail": str,
      "ended_at": str,
      "id": str,
      "index": int,
      "reason": str,
      "started_at": str,
      "status": str,
      "stopped": {
        "at": str,
        "by": {
          "avatar_url": str,
          "id": int,
          "login": str,
          "name": str,
          "type": str
        }
      },
      "tokens": {
        "all": {
          "cache_creation": int,
          "cache_read": int,
          "input": int,
          "output": int,
          "total": int
        },
        "by_model": [
          {
            "cache_creation": int,
            "cache_read": int,
            "input": int,
            "model": str,
            "output": int,
            "total": 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.StartSessionRequest.model_validate(
    {
      "claude_code": {
        "model": "claude-opus-5-5",
        "prompt": "Run the tests and report failures."
      },
      "environment": "api-environment",
      "conversation": {
        "interactive": False
      },
      "budget": {
        "session": 3
      }
    }
)

result = client.sessions.start(
    budget=request.budget,
    claude_code=request.claude_code,
    conversation=request.conversation,
    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.sessions.start>[0] = {
  "claude_code": {
    "model": "claude-opus-5-5",
    "prompt": "Run the tests and report failures."
  },
  "environment": "api-environment",
  "conversation": {
    "interactive": false
  },
  "budget": {
    "session": 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": {
    "model": "claude-opus-5-5",
    "prompt": "Run the tests and report failures."
  },
  "environment": "api-environment",
  "conversation": {
    "interactive": false
  },
  "budget": {
    "session": 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": [
        {
          "additionalProperties": false,
          "properties": {
            "session": {
              "anyOf": [
                {
                  "exclusiveMinimum": 0,
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        {
          "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": {
              "type": "string"
            },
            "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"
                }
              ]
            }
          },
          "required": [
            "model"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "codex": {
      "anyOf": [
        {
          "additionalProperties": false,
          "properties": {
            "effort": {
              "anyOf": [
                {
                  "enum": [
                    "none",
                    "low",
                    "medium",
                    "high",
                    "xhigh",
                    "max"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "model": {
              "type": "string"
            },
            "prompt": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "model"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "conversation": {
      "additionalProperties": false,
      "properties": {
        "interactive": {
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "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": {
              "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": {
              "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": {
              "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": {
      "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"
    },
    "metadata": {
      "items": {
        "type": "string"
      },
      "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"
                }
              ]
            },
            "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"
        }
      ]
    },
    "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"
                        },
                        "conversation": {
                          "type": "object"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "budget",
                        "claude_code",
                        "codex",
                        "conversation",
                        "environment",
                        "metadata",
                        "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"
            }
          ]
        },
        "archived": {
          "anyOf": [
            {
              "properties": {
                "at": {
                  "format": "date-time",
                  "type": "string"
                },
                "by": {
                  "anyOf": [
                    {
                      "properties": {
                        "avatar_url": {
                          "type": "string"
                        },
                        "id": {
                          "type": "integer"
                        },
                        "login": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object"
                        },
                        "type": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "avatar_url",
                        "id",
                        "login",
                        "name",
                        "type"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "at",
                "by"
              ],
              "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"
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "enum": [
                        "User",
                        "Organization",
                        "Bot",
                        "Mannequin"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "avatar_url",
                    "id",
                    "login",
                    "name",
                    "type"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "type",
            "user"
          ],
          "type": "object"
        },
        "budget": {
          "default": 0,
          "type": "integer"
        },
        "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": {
                  "type": "string"
                },
                "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": {
                  "type": "string"
                },
                "prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "effort",
                "model",
                "prompt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "conversation": {
          "properties": {
            "interactive": {
              "type": "boolean"
            },
            "prompting": {
              "properties": {
                "blocked_reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "mention_surface",
                        "non_interactive",
                        "harness_single_turn",
                        "budget_exhausted",
                        "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"
            },
            "state": {
              "enum": [
                "open",
                "closed"
              ],
              "type": "string"
            },
            "warm": {
              "type": "boolean"
            }
          },
          "required": [
            "interactive",
            "prompting",
            "state",
            "warm"
          ],
          "type": "object"
        },
        "cost": {
          "properties": {
            "charged": {
              "default": 0,
              "type": "integer"
            },
            "cpu": {
              "default": 0,
              "type": "integer"
            },
            "fee": {
              "default": 0,
              "type": "integer"
            },
            "llm": {
              "properties": {
                "all": {
                  "properties": {
                    "claude_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "codex_subscription": {
                      "default": 0,
                      "type": "integer"
                    },
                    "platform": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "claude_subscription",
                    "codex_subscription",
                    "platform",
                    "total"
                  ],
                  "type": "object"
                },
                "by_model": {
                  "items": {
                    "properties": {
                      "claude_subscription": {
                        "type": "integer"
                      },
                      "codex_subscription": {
                        "type": "integer"
                      },
                      "model": {
                        "type": "string"
                      },
                      "platform": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "claude_subscription",
                      "codex_subscription",
                      "model",
                      "platform",
                      "total"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "all",
                "by_model"
              ],
              "type": "object"
            },
            "memory": {
              "default": 0,
              "type": "integer"
            },
            "total": {
              "default": 0,
              "type": "integer"
            }
          },
          "required": [
            "charged",
            "cpu",
            "fee",
            "llm",
            "memory",
            "total"
          ],
          "type": "object"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "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": {
                      "enum": [
                        "requested",
                        "queued",
                        "waiting",
                        "pending",
                        "started",
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.check_run",
                      "default": "github.check_run",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "name",
                    "pull_request_number",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale",
                        "startup_failure"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "app": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.check_suite",
                      "default": "github.check_suite",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "app",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "pull_request_number",
                    "repository",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "requested",
                        "queued",
                        "waiting",
                        "pending",
                        "started",
                        "passed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped",
                        "neutral",
                        "action_required",
                        "stale",
                        "startup_failure"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conclusion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "run_number": {
                      "type": "integer"
                    },
                    "type": {
                      "const": "github.workflow_run",
                      "default": "github.workflow_run",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "conclusion",
                    "head_sha",
                    "name",
                    "pull_request_number",
                    "repository",
                    "run_number",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "pending",
                        "passed",
                        "failed",
                        "errored"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "branch": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "context": {
                      "type": "string"
                    },
                    "head_sha": {
                      "type": "string"
                    },
                    "pull_request_number": {
                      "anyOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repository": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.status",
                      "default": "github.status",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "branch",
                    "context",
                    "head_sha",
                    "pull_request_number",
                    "repository",
                    "state",
                    "type",
                    "url"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "action": {
                      "enum": [
                        "published"
                      ],
                      "type": "string"
                    },
                    "actor": {
                      "anyOf": [
                        {
                          "type": "object"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "prerelease": {
                      "type": "boolean"
                    },
                    "repository": {
                      "type": "string"
                    },
                    "tag": {
                      "type": "string"
                    },
                    "type": {
                      "const": "github.release",
                      "default": "github.release",
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "action",
                    "actor",
                    "name",
                    "prerelease",
                    "repository",
                    "tag",
                    "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"
        },
        "metadata": {
          "items": {
            "type": "string"
          },
          "default": {},
          "type": "object"
        },
        "output": {
          "anyOf": [
            {
              "properties": {
                "json_schema": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "result": {
                  "anyOf": [
                    {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "json_schema",
                "result"
              ],
              "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",
            "code_review",
            "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": {
            "all": {
              "properties": {
                "cache_creation": {
                  "default": 0,
                  "type": "integer"
                },
                "cache_read": {
                  "default": 0,
                  "type": "integer"
                },
                "input": {
                  "default": 0,
                  "type": "integer"
                },
                "output": {
                  "default": 0,
                  "type": "integer"
                },
                "total": {
                  "default": 0,
                  "type": "integer"
                }
              },
              "required": [
                "cache_creation",
                "cache_read",
                "input",
                "output",
                "total"
              ],
              "type": "object"
            },
            "by_model": {
              "items": {
                "properties": {
                  "cache_creation": {
                    "default": 0,
                    "type": "integer"
                  },
                  "cache_read": {
                    "default": 0,
                    "type": "integer"
                  },
                  "input": {
                    "default": 0,
                    "type": "integer"
                  },
                  "model": {
                    "type": "string"
                  },
                  "output": {
                    "default": 0,
                    "type": "integer"
                  },
                  "total": {
                    "default": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "cache_creation",
                  "cache_read",
                  "input",
                  "model",
                  "output",
                  "total"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "all",
            "by_model"
          ],
          "type": "object"
        },
        "turn": {
          "anyOf": [
            {
              "properties": {
                "cost": {
                  "properties": {
                    "charged": {
                      "default": 0,
                      "type": "integer"
                    },
                    "cpu": {
                      "default": 0,
                      "type": "integer"
                    },
                    "fee": {
                      "default": 0,
                      "type": "integer"
                    },
                    "llm": {
                      "properties": {
                        "all": {
                          "type": "object"
                        },
                        "by_model": {
                          "type": "array"
                        }
                      },
                      "required": [
                        "all",
                        "by_model"
                      ],
                      "type": "object"
                    },
                    "memory": {
                      "default": 0,
                      "type": "integer"
                    },
                    "total": {
                      "default": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "charged",
                    "cpu",
                    "fee",
                    "llm",
                    "memory",
                    "total"
                  ],
                  "type": "object"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "detail": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "ended_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "id": {
                  "type": "string"
                },
                "index": {
                  "type": "integer"
                },
                "reason": {
                  "anyOf": [
                    {
                      "enum": [
                        "error",
                        "tool_call_failed",
                        "budget_hit",
                        "payment_required",
                        "blocked",
                        "contact_email_required",
                        "lifecycle_hook_failed",
                        "missing_repo_access",
                        "missing_token_permissions",
                        "missing_environment_variables",
                        "missing_github_integration",
                        "agent_unavailable",
                        "upstream_unavailable",
                        "unsupported_configuration",
                        "execution_disabled",
                        "interrupted"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "started_at": {
                  "anyOf": [
                    {
                      "format": "date-time",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "enum": [
                    "queued",
                    "preparing",
                    "running",
                    "completed",
                    "failed",
                    "stopped",
                    "cancelled"
                  ],
                  "type": "string"
                },
                "stopped": {
                  "anyOf": [
                    {
                      "properties": {
                        "at": {
                          "type": "string"
                        },
                        "by": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "at",
                        "by"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "tokens": {
                  "properties": {
                    "all": {
                      "properties": {
                        "cache_creation": {
                          "type": "integer"
                        },
                        "cache_read": {
                          "type": "integer"
                        },
                        "input": {
                          "type": "integer"
                        },
                        "output": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "cache_creation",
                        "cache_read",
                        "input",
                        "output",
                        "total"
                      ],
                      "type": "object"
                    },
                    "by_model": {
                      "items": {
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "all",
                    "by_model"
                  ],
                  "type": "object"
                }
              },
              "required": [
                "cost",
                "created_at",
                "detail",
                "ended_at",
                "id",
                "index",
                "reason",
                "started_at",
                "status",
                "stopped",
                "tokens"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "agent",
        "archived",
        "attribution",
        "budget",
        "claude_code",
        "codex",
        "conversation",
        "cost",
        "created_at",
        "environment",
        "event",
        "git",
        "handler",
        "id",
        "metadata",
        "output",
        "parent",
        "permissions",
        "skills",
        "source",
        "summary",
        "tokens",
        "turn",
        "updated_at"
      ],
      "type": "object"
    }
  },
  "required": [
    "session"
  ],
  "type": "object"
}
```

---

# Delete a webhook

> Delete a webhook and cancel outstanding deliveries.

Source: https://www.ellipsis.dev/docs/api/webhook-endpoints/delete-webhooks-id

## DELETE /v1/webhooks/{id}

Delete a webhook and cancel outstanding deliveries.

Required permissions: delete:webhooks.
API key: Supported.
CLI user token: Supported.
Session token: Not supported by session 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl -X DELETE "https://api.ellipsis.dev/v1/webhooks/{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-id

## GET /v1/webhooks/deliveries/{id}

Inspect the event payload and delivery attempts.

Required permissions: read:webhooks.
API key: Supported.
CLI user token: Supported.
Session token: Not supported by session 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
                },
                "conversation": {
                  "interactive": bool
                },
                "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
                    }
                  ]
                },
                "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
                    ]
                  }
                },
                "skills": [
                  {
                    "path": str,
                    "repository": {
                      "name": str,
                      "owner": str,
                      "ref": str
                    }
                  }
                ]
              },
              "trigger": { # null | ReactTrigger | CronTrigger
                "check_run": {
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "names": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "check_suite": {
                  "apps": [
                    str
                  ],
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "enabled": bool,
                "issue": {
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      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
                      ]
                    },
                    "teams": [
                      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
                      ]
                    },
                    "teams": [
                      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
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "paths": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "release": {
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "on": [
                    str
                  ],
                  "prerelease": bool,
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  },
                  "tag": [
                    str
                  ]
                },
                "sentry": {
                  "on": [
                    str
                  ],
                  "projects": [
                    str
                  ]
                },
                "slack_channel": {},
                "status": {
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "names": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "type": "react",
                "workflow_run": {
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "names": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                }
              }
            },
            "id": str
          },
          "archived": {
            "at": str,
            "by": {
              "avatar_url": str,
              "id": int,
              "login": str,
              "name": str,
              "type": str
            }
          },
          "attribution": {
            "id": str,
            "type": str,
            "user": {
              "avatar_url": str,
              "id": int,
              "login": str,
              "name": str,
              "type": str
            }
          },
          "budget": int,
          "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
          },
          "conversation": {
            "interactive": bool,
            "prompting": {
              "blocked_reason": str,
              "detail": str,
              "enabled": bool,
              "surface_name": str
            },
            "state": str,
            "warm": bool
          },
          "cost": {
            "charged": int,
            "cpu": int,
            "fee": int,
            "llm": {
              "all": {
                "claude_subscription": int,
                "codex_subscription": int,
                "platform": int,
                "total": int
              },
              "by_model": [
                {
                  "claude_subscription": int,
                  "codex_subscription": int,
                  "model": str,
                  "platform": int,
                  "total": int
                }
              ]
            },
            "memory": int,
            "total": int
          },
          "created_at": str,
          "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 | GithubWorkflowRunEvent | GithubPullRequestEvent |
          # GithubIssueEvent | GithubPushEvent | GithubCheckRunEvent |
          # GithubCheckSuiteEvent | GithubStatusEvent | GithubReleaseEvent |
          # LinearIssueEvent | SlackMessageEvent | SlackChannelCreatedEvent |
          # SentryAlertEvent
            "action": str,
            "actor": {
              "avatar_url": str,
              "is_bot": bool,
              "name": str
            },
            "branch": str,
            "conclusion": str,
            "head_sha": str,
            "name": str,
            "pull_request_number": int,
            "repository": str,
            "run_number": int,
            "type": "github.workflow_run",
            "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,
          "metadata": {
            "[str]": str
          },
          "output": {
            "json_schema": {
              "[str]": any
            },
            "result": {
              "[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": {
            "all": {
              "cache_creation": int,
              "cache_read": int,
              "input": int,
              "output": int,
              "total": int
            },
            "by_model": [
              {
                "cache_creation": int,
                "cache_read": int,
                "input": int,
                "model": str,
                "output": int,
                "total": int
              }
            ]
          },
          "turn": {
            "cost": {
              "charged": int,
              "cpu": int,
              "fee": int,
              "llm": {
                "all": {
                  "claude_subscription": int,
                  "codex_subscription": int,
                  "platform": int,
                  "total": int
                },
                "by_model": [
                  {
                    "claude_subscription": int,
                    "codex_subscription": int,
                    "model": str,
                    "platform": int,
                    "total": int
                  }
                ]
              },
              "memory": int,
              "total": int
            },
            "created_at": str,
            "detail": str,
            "ended_at": str,
            "id": str,
            "index": int,
            "reason": str,
            "started_at": str,
            "status": str,
            "stopped": {
              "at": str,
              "by": {
                "avatar_url": str,
                "id": int,
                "login": str,
                "name": str,
                "type": str
              }
            },
            "tokens": {
              "all": {
                "cache_creation": int,
                "cache_read": int,
                "input": int,
                "output": int,
                "total": int
              },
              "by_model": [
                {
                  "cache_creation": int,
                  "cache_read": int,
                  "input": int,
                  "model": str,
                  "output": int,
                  "total": int
                }
              ]
            }
          },
          "updated_at": str
        }
      },
      "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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/webhooks/deliveries/{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"
                        },
                        "archived": {
                          "type": "object"
                        },
                        "attribution": {
                          "type": "object"
                        },
                        "budget": {
                          "type": "integer"
                        },
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "object"
                        },
                        "conversation": {
                          "type": "object"
                        },
                        "cost": {
                          "type": "object"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "event": {
                          "type": "object"
                        },
                        "git": {
                          "type": "object"
                        },
                        "handler": {
                          "type": "object"
                        },
                        "id": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "parent": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        },
                        "source": {
                          "type": "string"
                        },
                        "summary": {
                          "type": "object"
                        },
                        "tokens": {
                          "type": "object"
                        },
                        "turn": {
                          "type": "object"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "agent",
                        "archived",
                        "attribution",
                        "budget",
                        "claude_code",
                        "codex",
                        "conversation",
                        "cost",
                        "created_at",
                        "environment",
                        "event",
                        "git",
                        "handler",
                        "id",
                        "metadata",
                        "output",
                        "parent",
                        "permissions",
                        "skills",
                        "source",
                        "summary",
                        "tokens",
                        "turn",
                        "updated_at"
                      ],
                      "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.
Session token: Not supported by session 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-id

## GET /v1/webhooks/{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.
Session token: Not supported by session 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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl "https://api.ellipsis.dev/v1/webhooks/{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.
Session token: Not supported by session 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/{id}`](https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks-id): Get a webhook
- [`PUT /v1/webhooks/{id}`](https://www.ellipsis.dev/docs/api/webhook-endpoints/put-webhooks-id): Update a webhook
- [`DELETE /v1/webhooks/{id}`](https://www.ellipsis.dev/docs/api/webhook-endpoints/delete-webhooks-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/{id}`](https://www.ellipsis.dev/docs/api/webhook-endpoints/get-webhooks-deliveries-id): Get a delivery
- [`POST /v1/webhooks/{id}/ping`](https://www.ellipsis.dev/docs/api/webhook-endpoints/post-webhooks-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-id-ping

## POST /v1/webhooks/{id}/ping

Send a signed webhook.ping. The receiver must return HTTP 200.

Required permissions: write:webhooks.
API key: Supported.
CLI user token: Supported.
Session token: Not supported by session 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
                },
                "conversation": {
                  "interactive": bool
                },
                "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
                    }
                  ]
                },
                "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
                    ]
                  }
                },
                "skills": [
                  {
                    "path": str,
                    "repository": {
                      "name": str,
                      "owner": str,
                      "ref": str
                    }
                  }
                ]
              },
              "trigger": { # null | ReactTrigger | CronTrigger
                "check_run": {
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "names": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "check_suite": {
                  "apps": [
                    str
                  ],
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "enabled": bool,
                "issue": {
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      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
                      ]
                    },
                    "teams": [
                      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
                      ]
                    },
                    "teams": [
                      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
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "paths": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "release": {
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "on": [
                    str
                  ],
                  "prerelease": bool,
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  },
                  "tag": [
                    str
                  ]
                },
                "sentry": {
                  "on": [
                    str
                  ],
                  "projects": [
                    str
                  ]
                },
                "slack_channel": {},
                "status": {
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "names": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                },
                "type": "react",
                "workflow_run": {
                  "branch": [
                    str
                  ],
                  "for": {
                    "bots": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    },
                    "teams": [
                      str
                    ],
                    "users": { # bool | list[str]
                      "exclude": [
                        str
                      ],
                      "include": [ # bool
                        str
                      ]
                    }
                  },
                  "names": [
                    str
                  ],
                  "on": [
                    str
                  ],
                  "repositories": { # list[str]
                    "exclude": [
                      str
                    ],
                    "include": [
                      str
                    ]
                  }
                }
              }
            },
            "id": str
          },
          "archived": {
            "at": str,
            "by": {
              "avatar_url": str,
              "id": int,
              "login": str,
              "name": str,
              "type": str
            }
          },
          "attribution": {
            "id": str,
            "type": str,
            "user": {
              "avatar_url": str,
              "id": int,
              "login": str,
              "name": str,
              "type": str
            }
          },
          "budget": int,
          "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
          },
          "conversation": {
            "interactive": bool,
            "prompting": {
              "blocked_reason": str,
              "detail": str,
              "enabled": bool,
              "surface_name": str
            },
            "state": str,
            "warm": bool
          },
          "cost": {
            "charged": int,
            "cpu": int,
            "fee": int,
            "llm": {
              "all": {
                "claude_subscription": int,
                "codex_subscription": int,
                "platform": int,
                "total": int
              },
              "by_model": [
                {
                  "claude_subscription": int,
                  "codex_subscription": int,
                  "model": str,
                  "platform": int,
                  "total": int
                }
              ]
            },
            "memory": int,
            "total": int
          },
          "created_at": str,
          "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 | GithubWorkflowRunEvent | GithubPullRequestEvent |
          # GithubIssueEvent | GithubPushEvent | GithubCheckRunEvent |
          # GithubCheckSuiteEvent | GithubStatusEvent | GithubReleaseEvent |
          # LinearIssueEvent | SlackMessageEvent | SlackChannelCreatedEvent |
          # SentryAlertEvent
            "action": str,
            "actor": {
              "avatar_url": str,
              "is_bot": bool,
              "name": str
            },
            "branch": str,
            "conclusion": str,
            "head_sha": str,
            "name": str,
            "pull_request_number": int,
            "repository": str,
            "run_number": int,
            "type": "github.workflow_run",
            "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,
          "metadata": {
            "[str]": str
          },
          "output": {
            "json_schema": {
              "[str]": any
            },
            "result": {
              "[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": {
            "all": {
              "cache_creation": int,
              "cache_read": int,
              "input": int,
              "output": int,
              "total": int
            },
            "by_model": [
              {
                "cache_creation": int,
                "cache_read": int,
                "input": int,
                "model": str,
                "output": int,
                "total": int
              }
            ]
          },
          "turn": {
            "cost": {
              "charged": int,
              "cpu": int,
              "fee": int,
              "llm": {
                "all": {
                  "claude_subscription": int,
                  "codex_subscription": int,
                  "platform": int,
                  "total": int
                },
                "by_model": [
                  {
                    "claude_subscription": int,
                    "codex_subscription": int,
                    "model": str,
                    "platform": int,
                    "total": int
                  }
                ]
              },
              "memory": int,
              "total": int
            },
            "created_at": str,
            "detail": str,
            "ended_at": str,
            "id": str,
            "index": int,
            "reason": str,
            "started_at": str,
            "status": str,
            "stopped": {
              "at": str,
              "by": {
                "avatar_url": str,
                "id": int,
                "login": str,
                "name": str,
                "type": str
              }
            },
            "tokens": {
              "all": {
                "cache_creation": int,
                "cache_read": int,
                "input": int,
                "output": int,
                "total": int
              },
              "by_model": [
                {
                  "cache_creation": int,
                  "cache_read": int,
                  "input": int,
                  "model": str,
                  "output": int,
                  "total": int
                }
              ]
            }
          },
          "updated_at": str
        }
      },
      "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("...")
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('...');
console.log(result);
```

### cURL

```bash
curl -X POST "https://api.ellipsis.dev/v1/webhooks/{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"
                        },
                        "archived": {
                          "type": "object"
                        },
                        "attribution": {
                          "type": "object"
                        },
                        "budget": {
                          "type": "integer"
                        },
                        "claude_code": {
                          "type": "object"
                        },
                        "codex": {
                          "type": "object"
                        },
                        "conversation": {
                          "type": "object"
                        },
                        "cost": {
                          "type": "object"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "environment": {
                          "type": "object"
                        },
                        "event": {
                          "type": "object"
                        },
                        "git": {
                          "type": "object"
                        },
                        "handler": {
                          "type": "object"
                        },
                        "id": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "output": {
                          "type": "object"
                        },
                        "parent": {
                          "type": "object"
                        },
                        "permissions": {
                          "type": "object"
                        },
                        "skills": {
                          "type": "array"
                        },
                        "source": {
                          "type": "string"
                        },
                        "summary": {
                          "type": "object"
                        },
                        "tokens": {
                          "type": "object"
                        },
                        "turn": {
                          "type": "object"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "agent",
                        "archived",
                        "attribution",
                        "budget",
                        "claude_code",
                        "codex",
                        "conversation",
                        "cost",
                        "created_at",
                        "environment",
                        "event",
                        "git",
                        "handler",
                        "id",
                        "metadata",
                        "output",
                        "parent",
                        "permissions",
                        "skills",
                        "source",
                        "summary",
                        "tokens",
                        "turn",
                        "updated_at"
                      ],
                      "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.
Session token: Not supported by session 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-id

## PUT /v1/webhooks/{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.
Session token: Not supported by session 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("...", 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('...', request);
console.log(result);
```

### cURL

```bash
curl -X PUT "https://api.ellipsis.dev/v1/webhooks/{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"
}
```

---

# 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.