> ## Documentation Index > Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create Session > 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. ## OpenAPI ````yaml api-reference/openapi/sessions.json POST /api/sessions openapi: 3.1.0 info: title: Recoup API - Sessions description: >- Sessions — sandboxed runs of an LLM-driven agent with tool use, lifecycle hooks, and persistence. Each session pairs one Vercel Sandbox with one or more chat threads. license: name: MIT version: 1.0.0 servers: - url: https://api.recoupable.dev security: - ApiKeyAuth: [] - BearerAuth: [] paths: /api/sessions: post: 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' components: schemas: CreateSessionRequest: type: object description: >- All fields are optional. An empty body is valid and creates a personal session — the server provisions (or reuses) a workspace repo at `recoupable/` for the authenticated user. Include `organizationId` to create an org session instead — the server provisions (or reuses) `recoupable/`. The caller never constructs repo URLs. properties: title: type: string description: >- Display title for the session. When omitted, the server generates one. organizationId: type: string format: uuid description: >- Recoupable organization id. When provided, the session is created against the org's workspace repo (`recoupable/`) and the caller must have access to that organization. When omitted, the session is personal and uses the caller's own workspace repo (`recoupable/`). artistId: type: string format: uuid description: >- 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. CreateSessionResponse: type: object required: - session - chat properties: session: $ref: '#/components/schemas/Session' chat: $ref: '#/components/schemas/Chat' Error: type: object required: - status - error properties: status: type: string enum: - error description: Always `"error"` for error responses. error: type: string description: Human-readable error message. Session: type: object description: >- Agent session returned by [`POST /api/sessions`](/api-reference/sessions/create), [`GET /api/sessions/{sessionId}`](/api-reference/sessions/get), and [`PATCH /api/sessions/{sessionId}`](/api-reference/sessions/patch). 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). required: - id - userId - artistId - title - status - isNewBranch - globalSkillRefs - lifecycleVersion - createdAt - updatedAt properties: id: type: string description: Session id (nanoid). userId: type: string format: uuid description: >- 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. title: type: string status: type: string enum: - running - completed - failed - archived repoOwner: type: string nullable: true description: GitHub repo owner if the session is bound to a repository. repoName: type: string nullable: true branch: type: string nullable: true cloneUrl: type: string nullable: true description: Clone URL the sandbox should fetch from. isNewBranch: type: boolean description: >- Always present on session responses. True when this session created and pushed a new branch (not committing back to the original); false otherwise. globalSkillRefs: type: array description: Skills attached to the agent at provision time. items: type: object additionalProperties: true sandboxState: type: object nullable: true additionalProperties: true description: Sandbox runtime state (Vercel Sandbox). lifecycleState: type: string nullable: true enum: - provisioning - active - hibernating - hibernated - restoring - archived - failed description: Lifecycle orchestration state for the sandbox. lifecycleVersion: type: integer description: Optimistic concurrency token for lifecycle transitions. lastActivityAt: type: string format: date-time nullable: true sandboxExpiresAt: type: string format: date-time nullable: true hibernateAfter: type: string format: date-time nullable: true lifecycleRunId: type: string nullable: true lifecycleError: type: string nullable: true linesAdded: type: integer nullable: true description: >- Lines added across the session's diff. Defaults to 0; null when stats have not been computed. linesRemoved: type: integer nullable: true description: >- Lines removed across the session's diff. Defaults to 0; null when stats have not been computed. snapshotUrl: type: string nullable: true snapshotCreatedAt: type: string format: date-time nullable: true snapshotSizeBytes: type: integer nullable: true cachedDiff: type: object nullable: true additionalProperties: true cachedDiffUpdatedAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time artistId: type: - string - 'null' format: uuid description: >- 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. Chat: type: object required: - id - sessionId - title - modelId - createdAt - updatedAt properties: id: type: string description: Chat id (nanoid). sessionId: type: string description: Owning session id. title: type: string description: >- Display title for the chat. The initial chat created with a session is titled `New chat`. modelId: type: string description: >- AI Gateway model identifier the chat is configured to use (e.g. `openai/gpt-5.4`). activeStreamId: type: string nullable: true description: Id of an in-flight assistant stream, if one is active. lastAssistantMessageAt: type: string format: date-time nullable: true description: Timestamp of the most recent assistant message in this chat. createdAt: type: string format: date-time updatedAt: type: string format: date-time securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key BearerAuth: type: http scheme: bearer ````