POST
Create agent session

Authorizations

Authorization
string
header
required

An opaque BMA personal or organization bearer token.

Path Parameters

orgID
string
required

Organization ID (org_...).

Pattern: ^org_[a-z2-7]{26}$
projectID
string
required

Project ID (proj_...).

Pattern: ^proj_[a-z2-7]{26}$
agentID
string
required

Agent ID (agt_...).

Pattern: ^agt_[a-z2-7]{26}$

Body

application/json
agent_config_id
string
Pattern: ^acfg_[a-z2-7]{26}$
config_source
object

Compiled and saved as this session's immutable config in the create transaction. The session's machine sources, model and instruction come from this source; they do not change the shared agent or its other sessions.

environment_id
string<uuid>
idempotency_key
string

Replays the original session for this agent. A replay with a different pinned config, environment or metadata is a 409 conflict.

Required string length: 1 - 200
model_override
object

Creates a session-scoped credential override in the same transaction as the session and its machines. Raw keys are never returned; the override is revoked on archive.

metadata
object
resources
object[]

Project files to mount into the new session, as with POST .../resources. A replay of an idempotent create mounts nothing new.

Maximum array length: 500

Response

Agent session created.

session
object
required