Start a session
POST /v1/sessions- Permission
write:sessions- Tokens
- API key, CLI user token, Session token
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.
Request
Spend limit for this session: `session` is the most it may spend, in US dollars. Omitted, an agent session keeps the agent's limit and a raw session takes the organization's default. Above the organization's per-session ceiling is a 400. `day`, `week`, and `month` are agent-wide limits and are rejected with a 422.
Claude Code input and native options. Set exactly one of claude_code or codex.
Codex input and native options. Set exactly one of claude_code or codex.
Conversation settings. Omitted, a raw session is interactive and an agent session keeps the agent's setting. State, warmth, prompting, and the turn are server-owned response fields.
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, and `{}` is the bare environment. Nothing is merged: what you send is the whole environment. Omitted, a raw session runs in the built-in basic environment and an agent session keeps the agent's own environment.
Skip the image cache for this session's initial provision: a fresh full build whose snapshot then refreshes the cache for later sessions.
Images attached to the first message, base64 inline. Requires the model's images capability, which is not currently certified. Each becomes an `[Image #N]` placeholder in the prompt and an image block on turn 0. Up to 10, 5 MiB each; PNG, JPEG, GIF, or WebP.
Arbitrary string key/value metadata stored on the session. On an agent session it replaces the agent's metadata; keys are never merged.
The structured-output exit contract for this session.
What the session may touch, per minted credential.
Skills installed for this session.
Response
The session.