> ## 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. # Update Session > Rename a session, change lifecycle status, or update line counters. ## OpenAPI ````yaml api-reference/openapi/sessions.json PATCH /api/sessions/{sessionId} 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/{sessionId}: patch: summary: Update session description: >- Renames a session or changes its status (e.g. archive / unarchive). All body fields are optional; omitted fields are left unchanged. operationId: patchSessionById parameters: - name: sessionId in: path required: true description: The id of the session to update. schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/PatchSessionBody' responses: '200': description: Session updated successfully. content: application/json: schema: $ref: '#/components/schemas/GetSessionResponse' '400': description: Bad request — malformed JSON body. 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' '403': description: Forbidden — the authenticated account does not own this session. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found — no session exists with the given id. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error — the session could not be updated. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: PatchSessionBody: type: object description: >- All fields are optional; an empty object `{}` is valid and leaves the session unchanged. properties: title: type: string description: New display title for the session (rename). status: type: string enum: - running - completed - failed - archived description: >- Lifecycle status (matches the DB CHECK). `running` is active / unarchived; `completed` and `failed` are terminal; `archived` archives the row. Use `running` to unarchive from `archived`. linesAdded: type: integer minimum: 0 description: Updates the persisted `lines_added` column on the session (≥ 0). linesRemoved: type: integer minimum: 0 description: Updates the persisted `lines_removed` column on the session (≥ 0). GetSessionResponse: type: object required: - session properties: session: $ref: '#/components/schemas/Session' 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. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key BearerAuth: type: http scheme: bearer ````