API REFERENCE

Update Session

On this page

PATCH/api/sessions/{sessionId}

Renames a session or changes its status (e.g. archive / unarchive). All body fields are optional; omitted fields are left unchanged.

Authentication

x-api-key in header

BearerAuth bearer

Request

cURL

curl --request PATCH \
  --url 'https://api.recoupable.dev/api/sessions/YOUR_SESSION_ID' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "string",
  "status": "running",
  "linesAdded": 0,
  "linesRemoved": 0
}'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

sessionIdstringrequired

The id of the session to update.

Request body

application/json

titlestring

New display title for the session (rename).

statusstring · enum

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.

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

linesAddedinteger

Updates the persisted lines_added column on the session (≥ 0).

minimum: 0

linesRemovedinteger

Updates the persisted lines_removed column on the session (≥ 0).

minimum: 0

Responses

200Session updated 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

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

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

400Bad request — malformed JSON body.

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.

403Forbidden — the authenticated account does not own this session.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

404Not found — no session exists with the given id.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

500Internal server error — the session could not be updated.

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

{
  "operationId": "patchSessionById",
  "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.",
  "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"
          }
        }
      }
    }
  }
}