Skip to main content
POST
/
api
/
sessions
Create session
curl --request POST \
  --url https://api.recoupable.com/api/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "title": "<string>",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "artistId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "session": {
    "id": "<string>",
    "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "title": "<string>",
    "isNewBranch": true,
    "globalSkillRefs": [
      {}
    ],
    "lifecycleVersion": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "artistId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "repoOwner": "<string>",
    "repoName": "<string>",
    "branch": "<string>",
    "cloneUrl": "<string>",
    "sandboxState": {},
    "lastActivityAt": "2023-11-07T05:31:56Z",
    "sandboxExpiresAt": "2023-11-07T05:31:56Z",
    "hibernateAfter": "2023-11-07T05:31:56Z",
    "lifecycleRunId": "<string>",
    "lifecycleError": "<string>",
    "linesAdded": 123,
    "linesRemoved": 123,
    "snapshotUrl": "<string>",
    "snapshotCreatedAt": "2023-11-07T05:31:56Z",
    "snapshotSizeBytes": 123,
    "cachedDiff": {},
    "cachedDiffUpdatedAt": "2023-11-07T05:31:56Z"
  },
  "chat": {
    "id": "<string>",
    "sessionId": "<string>",
    "title": "<string>",
    "modelId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "activeStreamId": "<string>",
    "lastAssistantMessageAt": "2023-11-07T05:31:56Z"
  }
}

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