RecoupGet a free auditFree audit

API REFERENCE

Create Session

On this page
POST/api/sessions

Creates a new agent session and an initial empty chat in a single transaction. The session is created in the provisioning lifecycle state — a separate orchestration step claims it and starts the sandbox.

Authentication

x-api-key in header

BearerAuth bearer

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/sessions' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "string",
  "organizationId": "YOUR_ID",
  "artistId": "YOUR_ID"
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/sessions' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "string",
  "organizationId": "YOUR_ID",
  "artistId": "YOUR_ID"
}'

Request body

application/json

titlestring

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

organizationIdstring

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>).

format: uuid

artistIdstring

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.

format: uuid

Responses

200Session and initial chat created successfully.

application/json

sessionobjectrequired

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).

Properties for session
idstringrequired

Session id (nanoid).

userIdstringrequired

Owning account id. Named userId here for compatibility with existing clients; on the server side this is the account_id foreign key into the accounts table.

format: uuid

titlestringrequired
statusstring · enumrequired

Values: "running", "completed", "failed", "archived"

repoOwnerstringnullable

GitHub repo owner if the session is bound to a repository.

repoNamestringnullable
branchstringnullable
cloneUrlstringnullable

Clone URL the sandbox should fetch from.

isNewBranchbooleanrequired

Always present on session responses. True when this session created and pushed a new branch (not committing back to the original); false otherwise.

globalSkillRefsarray<object>required

Skills attached to the agent at provision time.

Item properties for globalSkillRefs

object

Additional properties

Additional keys are allowed.

sandboxStateobjectnullable

Sandbox runtime state (Vercel Sandbox).

lifecycleStatestring · enumnullable

Lifecycle orchestration state for the sandbox.

Values: "provisioning", "active", "hibernating", "hibernated", "restoring", "archived", "failed"

lifecycleVersionintegerrequired

Optimistic concurrency token for lifecycle transitions.

lastActivityAtstringnullable

format: date-time

sandboxExpiresAtstringnullable

format: date-time

hibernateAfterstringnullable

format: date-time

lifecycleRunIdstringnullable
lifecycleErrorstringnullable
linesAddedintegernullable

Lines added across the session's diff. Defaults to 0; null when stats have not been computed.

linesRemovedintegernullable

Lines removed across the session's diff. Defaults to 0; null when stats have not been computed.

snapshotUrlstringnullable
snapshotCreatedAtstringnullable

format: date-time

snapshotSizeBytesintegernullable
cachedDiffobjectnullable
cachedDiffUpdatedAtstringnullable

format: date-time

createdAtstringrequired

format: date-time

updatedAtstringrequired

format: date-time

artistIdstring | nullrequired

Artist account id this session was created in the context of, or null when no artist was associated. Set via POST /api/sessions { artistId }; surfaces here for clients (e.g. the chat sidebar) that filter sessions/chats by artist.

format: uuid

chatobjectrequired
Properties for chat
idstringrequired

Chat id (nanoid).

sessionIdstringrequired

Owning session id.

titlestringrequired

Display title for the chat. The initial chat created with a session is titled New chat.

modelIdstringrequired

AI Gateway model identifier the chat is configured to use (e.g. openai/gpt-5.4).

activeStreamIdstringnullable

Id of an in-flight assistant stream, if one is active.

lastAssistantMessageAtstringnullable

Timestamp of the most recent assistant message in this chat.

format: date-time

createdAtstringrequired

format: date-time

updatedAtstringrequired

format: date-time

400Invalid request body — either malformed JSON or a field failed validation.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

401Unauthorized — invalid or missing API key / Bearer token.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

500Server error — the session could not be persisted.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download sessions.json
View operation source
json
{
  "summary": "Create session",
  "description": "Creates a new agent session and an initial empty chat in a single transaction. The session is created in the `provisioning` lifecycle state — a separate orchestration step claims it and starts the sandbox.",
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateSessionRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Session and initial chat created successfully.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateSessionResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request body — either malformed JSON or a field failed validation.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — invalid or missing API key / Bearer token.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Server error — the session could not be persisted.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}