Skip to main content
POST
Create session

Authorizations

x-api-key
string
header
required

Body

application/json

All fields are optional. An empty body is valid and creates a personal session — the server provisions (or reuses) a workspace repo at recoupable/<accountId> for the authenticated user. Include organizationId to create an org session instead — the server provisions (or reuses) recoupable/<organizationId>. The caller never constructs repo URLs.

title
string

Display title for the session. When omitted, the server generates one.

organizationId
string<uuid>

Recoupable organization id. When provided, the session is created against the org's workspace repo (recoupable/<organizationId>) and the caller must have access to that organization. When omitted, the session is personal and uses the caller's own workspace repo (recoupable/<accountId>).

artistId
string<uuid>

Artist account id to associate the session with. When provided, the session is created in the context of that artist — used by the chat sidebar to filter chats by artist. Optional; omit for a session with no artist context.

Response

Session and initial chat created successfully.

session
object
required

Agent session returned by POST /api/sessions, GET /api/sessions/{sessionId}, and PATCH /api/sessions/{sessionId}. The api serializes every field listed in required on each response, including isNewBranch (boolean, from the non-null sessions.is_new_branch column) and artistId (UUID or null).

chat
object
required