Sessions
Sessions endpoints of the Ellipsis REST API.
| Method | Path |
|---|---|
| POST | /v1/sessions |
The daily driver: a prompt, optionally where to run it (`environment`) and the run's own settings, in the AutomationConfig vocabulary. What you send is what runs: omit `environment` and the session runs in the built-in basic sandbox. A missing model or budget comes from the organization's settings, so `{"prompt": "..."}` alone is a complete request. `prompt` is the first message; omit it and the session starts idle, waiting for one. 400 when `interactive` is false and there is no prompt, or when `budget` exceeds the organization's per-session ceiling. To run a saved automation, use POST /v1/automations/{automation_id}/sessions.
curl -X POST "https://api.ellipsis.dev/v1/sessions" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"..."}'import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.sessions.start(prompt="...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.sessions.start({ prompt: '...' });
console.log(result);Request
Body parameters
The most this session may spend, in US dollars. Omitted, the organization's default applies. Above the organization's per-session ceiling is a 400.
The Claude-harness block: `{"model": ...}` to pick this session's model, plus system/effort/fallback_model/max_turns/settings. Omit the model to run the organization's default.
The Codex-harness block. Its presence selects the Codex harness, exactly as in a saved automation; a request may not carry both `claude` and `codex`.
Where the session runs. A STRING is a saved environment's name or `env_...` id, substituted wholesale. An OBJECT is the whole environment for this session — `{}` is the bare sandbox. Omitted, the session runs in the built-in basic sandbox — nothing outside the request picks the environment.
falsebooleanSkip the image cache for this session's initial provision: a fresh full build whose snapshot then refreshes the cache for later runs. The CLI's `--rebuild`.
truebooleanWhether the session stays open for messages after its first turn. Set false for a one-shot run that does its job and closes without holding a warm sandbox; a one-shot run must carry a prompt, since nothing can ever be sent to it later. Sessions on the Codex harness are one-shot regardless.
{}objectArbitrary string key/value metadata stored on the session.
The structured-output exit contract for this session.
What the session may touch, per minted credential.
The session's first message. Omit it and the session starts idle: the sandbox spins up, the agent waits at the prompt, and the first message you send opens turn 0.
Repositories to check out in addition to the environment's own, as `owner/name` or a bare `name` (the account's). Each is added only when the resolved environment does not already have it — the CLI sends the repository it is standing in this way, whatever environment the session runs in.
Skills installed for this session.
Response
| Method | Path |
|---|---|
| GET | /v1/sessions |
Optionally filtered by automation (id or name), source, time window, attributed author, repository, and whether the session is still going.
Query parameters
An automation id, or its name: only sessions that automation started.
50integerA GitHub account id (see GET /v1/integrations/github/members); scopes the list to sessions attributed to that developer.
"owner/name" (exact) or a bare repo name. Sessions whose repository is named only inside their agent config — dashboard starts, cron — do not match.
falsebooleanKeep only sessions whose conversation is still going — live or idle — dropping the ones that completed, errored, or were stopped or cancelled. A session parked between turns counts as unfinished.
curl "https://api.ellipsis.dev/v1/sessions" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
for item in client.sessions.list():
print(item)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
for await (const item of client.sessions.list()) {
console.log(item);
}Request
Response
| Method | Path |
|---|---|
| GET | /v1/sessions/{session_id} |
The public wire shape — the same shape the stream's session frames carry, with attributed_user and stopped_by_user resolved at read time. The heavy near-static blobs (config snapshot, input/output) live on the detail endpoints, not here.
Path parameters
curl "https://api.ellipsis.dev/v1/sessions/{session_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.sessions.get("...")
print(result)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);Request
Response
| Method | Path |
|---|---|
| GET | /v1/sessions/{session_id}/diff |
One unified-diff section per changed file, captured from the sandbox's working tree when the session ended. The per-file counts ride on the session itself (`git.repos[].files`); this is the text behind them. Empty when the tree was clean. A sandbox token may read only its own session's diff.
Path parameters
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/diff" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.sessions.diff("...")
print(result)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);Request
Response
| Method | Path |
|---|---|
| GET | /v1/sessions/{session_id}/export |
The complete, ordered history of the session (agent output, tool calls, thinking, lifecycle events, sandbox output, message events) as an ordered manifest of presigned segment URLs. Segments are gzip members: download in order and concatenate for one file. The JSON API never carries the bytes (same two-step as files). /records is the paged live view of the same data.
Path parameters
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/export" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.sessions.export("...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.sessions.export('...');
console.log(result);Request
Response
| Method | Path |
|---|---|
| POST | /v1/sessions/{session_id}/messages |
409 for react/cron, non-interactive, and closed sessions. Returns the created message so the caller can track it by id; a retried send with the same idempotency_key returns the original message.
Path parameters
curl -X POST "https://api.ellipsis.dev/v1/sessions/{session_id}/messages" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message":"..."}'import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.sessions.send_message("...", "...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.sessions.sendMessage('...', { message: '...' });
console.log(result);Request
Body parameters
Optional retry-safety key, unique per (session, key): a retry with the same key returns the original message — no duplicate message, no double turn, no double spend. The SDK auto-generates one per send.
The message text.
Response
| Method | Path |
|---|---|
| GET | /v1/sessions/{session_id}/output |
The payload the agent submitted through its config-declared output.json_schema, as the raw JSON body with no envelope. 404 while the session is still running (poll GET /v1/sessions/{id}), when the agent declares no output block, or when no execution produced output.
Path parameters
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/output" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.sessions.output("...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.sessions.output('...');
console.log(result);Request
Response
| Method | Path |
|---|---|
| GET | /v1/sessions/{session_id}/records |
Pagination is opt-in (cursor/limit); a bare call returns the full retained transcript. Available to sandbox tokens too: an agent answering "did X look into Y?" needs to read the sessions it finds, and any org member sees the same transcript in the dashboard.
Path parameters
Query parameters
curl "https://api.ellipsis.dev/v1/sessions/{session_id}/records" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
for item in client.sessions.records("..."):
print(item)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
for await (const item of client.sessions.records('...')) {
console.log(item);
}Request
Response
| Method | Path |
|---|---|
| POST | /v1/sessions/{session_id}/stop |
stopped_by is recorded only when the caller's credential maps to a GitHub account.
Path parameters
curl -X POST "https://api.ellipsis.dev/v1/sessions/{session_id}/stop" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.sessions.stop("...")
print(result)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);