Start a session in a workspace
Requires sessions:write on a workspace the key’s account owns. chat is the only session_type a key may create — time, webhook, api_trigger, and agent_test sessions are a 403. The key is recorded as the session’s initiator (serialized type: "api_key"), and the agent begins executing initial_prompt immediately.
Authorizations
Account API key: key id as the username, secret as the password.
Path Parameters
Body
Response
Successful response
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
The user who started this agent test session.
Eval trials run as agent-test sessions; this separates them from sessions a person started from the agent editor.
MANUAL, EVAL The specific agent version being tested in this session.
The workspace this session belongs to.
The context used in this session, if available.
Optional context override for testing purposes.
Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed.
User who interrupted this session.
Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context.