Start Agent Session

Start a new agent session. Provide at most one of config_id, config, or template_id; with none, the customer's default-config ladder resolves the config. 400 when idle_start is combined with prompt or handoff, or when a handoff is combined with any config source or override.

Start a new agent session.

Provide at most one of config_id, config, or template_id; with none, the customer's default-config ladder resolves the config. 400 when idle_start is combined with prompt or handoff, or when a handoff is combined with any config source or override.

Authorization

HTTPBearer

AuthorizationBearer <token>

In: header

Header Parameters

user-agent?string|null

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Parameters for starting a new agent session.

config?|

An inline agent config to run under.

config_id?|

A saved agent config id to run under.

config_override?|

Optional partial-config override merged onto the chosen config and re-validated (e.g. {"limits": {"run": 5.0}} to raise just this run's budget). Merged onto config_id/template_id or the platform default; with an inline config, set fields directly instead. Mutually exclusive with config_override_yaml.

config_override_yaml?|

The same partial-config override as a YAML/JSON string (e.g. read from a file). Mutually exclusive with config_override.

force_rebuild?Force Rebuild

Skip the image cache for this session's initial provision: a fresh full build whose snapshot then refreshes the cache for later runs. A wake of a durable session provisions through the cache as usual. The CLI's --rebuild.

Defaultfalse

handoff?|

Laptop-to-cloud handoff parameters. When set, the built-in handoff config is used and config_id/config/template_id must be omitted.

idle_start?Idle Start

Start the session with no initial message: the sandbox spins up, the agent starts idle at the prompt, and the first message sent to the session opens turn 0. Mutually exclusive with prompt and handoff. Ignored when the resolved config is not interactive (an ephemeral run keeps its kickoff — it can never receive a message).

Defaultfalse

metadata?

Arbitrary string key/value metadata stored on the session.

Default{}

prompt?|

Per-run instructions appended to the initial query after the config's shared system prompt. Applies regardless of which config source is used. For a handoff, this is the developer's handoff note.

repository?|

The "owner/name" repository the client is standing in (the CLI's detected git remote). Selects the repo rung of the defaults ladder, and is merged into the sandbox repository set (cloned at its default branch) regardless of which config source is used. An unknown or foreign repo is ignored.

template_id?|

A maintained run-on-demand template slug (e.g. "ellipsis-helper"), resolved server-side to its config. At most one of config_id, config, or template_id may be set; if none is, the run resolves the customer's default-config ladder (repo default, then account default, then the platform default config).

Response Body

`application/json`

curl -X POST "https://example.com/v1/sessions" \  -H "Content-Type: application/json" \  -d '{}'

{  "agent_config_id": "string",  "attributed_user": {    "avatar_url": "string",    "id": 0,    "login": "string",    "type": "User"  },  "attribution_id": "string",  "attribution_type": "github_user",  "client_version": "string",  "config_override": {},  "context_repository": "string",  "cost_fee": 0,  "cost_sandbox_cpu": 0,  "cost_sandbox_memory": 0,  "cost_tokens": 0,  "created_at": "2019-08-24T14:15:22Z",  "customer_id": "string",  "default_resolution": "repo_default",  "exit_status": "completed",  "harness": "claude_code",  "id": "string",  "last_activity_at": "2019-08-24T14:15:22Z",  "last_message_at": "2019-08-24T14:15:22Z",  "live_summary": "string",  "metadata": {},  "output_prs": [    {      "gh_pr_id": 0,      "number": 0,      "repo_full_name": "string",      "title": "string",      "url": "string"    }  ],  "parent_agent_session_id": "string",  "parent_kind": "continuation",  "prompt": "string",  "prompting": {    "blocked_reason": "mention_surface",    "detail": "string",    "enabled": true,    "surface_name": "string"  },  "replayed_from_session_id": "string",  "resolution_source": "repo_default",  "resolved_budget_cents": 0,  "resolved_budget_source": "system",  "resolved_config_name": "string",  "sandbox_id": "string",  "session_key": "string",  "session_state": "idle",  "source": "react",  "status": "scheduled",  "status_reason": "string",  "stopped_at": "2019-08-24T14:15:22Z",  "stopped_by": 0,  "stopped_by_user": {    "avatar_url": "string",    "id": 0,    "login": "string",    "type": "User"  },  "surface": {    "run": "scheduled",    "session": "alive",    "status": "string"  },  "tokens_cache_creation": 0,  "tokens_cache_read": 0,  "tokens_input": 0,  "tokens_model": "string",  "tokens_output": 0,  "tokens_total": 0,  "updated_at": "2019-08-24T14:15:22Z",  "webhook_id": "string",  "webhook_type": "github.issue"}

Authorization

Header Parameters

Request Body

Response Body

201application/json

422application/json

`application/json`

`application/json`