RecoupGet a free auditFree audit

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.

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 PATCH \
  --url 'https://recoup-api.vercel.app/api/sessions/{sessionId}' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "string",
  "status": "running",
  "linesAdded": 0,
  "linesRemoved": 0
}'

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

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"
          }
        }
      }
    }
  }
}