Skip to main content
POST
Create a session

Authorizations

Authorization
string
header
required

A gbr_pat_ access token. Scopes are recorded on the token when it is minted.

Headers

Idempotency-Key
string

Retrying with the same key replays the first answer instead of acting again.

Maximum string length: 255

Body

application/json

Everything optional. A session with only a model is a complete session.

agent
object

What runs, and how freely. Omit every field and the organization's default connection runs it.

environment
object

What the workspace starts with.

parent_session_id
string

The session this one comes from. Read back as parent_session_id, and GET /v1/sessions?root= returns the whole tree under one — which is how a crew of sessions is addressed without a second noun. Recorded rather than enforced: the parent may be deleted afterwards and this still answers where the session came from. POST /v1/sessions/{id}/fork records the same relation on its own.

metadata
object

Your own labels. Returned unchanged; never interpreted.

input
string

An opening message. All or nothing — if it cannot be accepted the session is not created either.

title
string

A label for people.

Response

Create a session, optionally with an opening message.

object
string
required

Always session. Names the shape, so a value can be identified without knowing which call returned it.

Allowed value: "session"
id
string
required

Ours, not yours. Use metadata to carry your own identifier.

status
enum<string>
required

idle accepts input. working is running a turn. requires_action is waiting on you — see required_actions. failed is the last turn's outcome, not a dead session.

Available options:
idle,
working,
requires_action,
failed
created_at
integer
required

Unix milliseconds.

updated_at
integer
required

Unix milliseconds. Moves on any change, including the workspace waking.

agent
object
required

What is running, and how freely.

environment
object
required

The workspace: its state, where the agent works, and the repository bound to it.

preview
object
required

Addresses for whatever the agent is serving. See preview.md.

title
string | null

A label for people. Set it yourself; nothing derives one.

source
enum<string> | null

Which door created this session. Null on sessions predating the field.

Available options:
api,
console,
cli,
null
created_by_token
string | null

The id of the access token that created it — never its secret.

parent_session_id
string | null

The session this one was branched from, or null when it was created directly. Recorded at creation and never cleared: the source may be edited or deleted afterwards and this still answers "where did this session come from", which is the first question asked when two sessions behave differently. The column has existed since the fork endpoint shipped; only the fork response could see it, so a session read back later had no way to say it was a branch.

required_actions
object[]

Everything the session is waiting on you for. Authoritative — not a replay of events, so a caller that restarted gets the same complete answer.