Start an agent session
POST /v1/agents/{agent_id}/sessions- Permission
write:sessions- Tokens
- API key, CLI user token, Session token
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.
Path parameters
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 options for this session. Sent fields replace the agent's; naming Claude Code on a Codex agent replaces its harness and requires a model. Set at most one of claude_code or codex.
Codex options for this session. Sent fields replace the agent's; naming Codex on a Claude Code agent replaces its harness and requires a model. Set at most 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.
The typed payload for an agent that declares input.json_schema. Required when the agent declares a schema; rejected when it does not. Validated against the schema and rendered through input.message, or as formatted JSON if no template is set, and added after the prompt. The rendered message must be non-empty.
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.