RecoupGet a free auditFree audit

API REFERENCE

Get Session

On this page
GET/api/sessions/{sessionId}

Returns a single agent session by its id.

Authentication

x-api-key in header

BearerAuth bearer

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/sessions/YOUR_SESSION_ID' \
  --header 'x-api-key: YOUR_API_KEY'

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 GET \
  --url 'https://recoup-api.vercel.app/api/sessions/{sessionId}'

Parameters

Path parameters

sessionIdstringrequired

The id of the session to fetch.

Responses

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

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.

Full specification

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

Download sessions.json
View operation source
json
{
  "summary": "Get session by id",
  "description": "Returns a single agent session by its id.",
  "parameters": [
    {
      "name": "sessionId",
      "in": "path",
      "required": true,
      "description": "The id of the session to fetch.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Session retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GetSessionResponse"
          }
        }
      }
    },
    "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"
          }
        }
      }
    }
  }
}