Skip to main content
POST
Start a session in a workspace

Authorizations

Authorization
string
header
required

Account API key: key id as the username, secret as the password.

Path Parameters

workspace_id_or_name
string
required

Body

application/json
session_type
enum<string>
required

The only value a key may pass.

Available options:
chat
agent_id
string<uuid>
required
initial_prompt
string
required

Response

Successful response

id
string<uuid>
created_at
string<date-time>
updated_at
string<date-time>
initiator_id
string<uuid>

The user who started this agent test session.

test_type
enum<string>

Eval trials run as agent-test sessions; this separates them from sessions a person started from the agent editor.

Available options:
MANUAL,
EVAL
version_override_id
string<uuid>

The specific agent version being tested in this session.

workspace_id
string<uuid>

The workspace this session belongs to.

context_id
string<uuid> | null

The context used in this session, if available.

context_override_id
string<uuid> | null

Optional context override for testing purposes.

interrupted_at
string<date-time> | null

Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed.

interrupted_by_id
string<uuid> | null

User who interrupted this session.

seed_context
string | null

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.