POST /sessions
Start a cloud agent session.
| 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.