CAcaveman

Start a Caveman Code session

POST /api/v1/code/sessions on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.

post/code/sessions

Request

  • Base URL
    https://api.caveman.so/api/v1
  • URL
    https://api.caveman.so/api/v1/code/sessions
  • Auth
    • OAuth 2
      Authorization code: /api/v1/oauth/authorize
      Token URL: /api/v1/oauth/token scopes: code:write
    • or HTTP bearer
    • or API key in cookie cave_access
    • or API key in cookie __Secure-cave_identity.session_token

Request body

request_idstring required

Idempotent per caller: a retry returns the session the first call started.

repostring required

owner/name: the repository the session's computer checks out.

base_branchstring
taskstring required

The first user message.

titlestring
engine'caveman' | 'claude-agent' | 'codex'
modelstring

A model id or a class: fast, base, frontier or auto.

budget_usdnumber
filesstring[]
metadataobject

Response

The session

idstring uuid required
organization_idstring uuid
workspace_idstring uuid required
computer_idstring uuid nullable
origin'person' | 'api' | 'automation' required
service_account_idstring uuid nullable
repostring
branchstring
enginestring
modelstring
titlestring
status'starting' | 'running' | 'requires_action' | 'idle' | 'terminated' required
stop_reason'end_turn' | 'requires_action' | 'budget_reached' | 'error' | 'interrupted' | 'null' nullable
created_atstring date-time required
updated_atstring date-time required
ended_atstring date-time nullable
metadataobject required

Changes

No recorded changes to this operation across all 1 revision of this API.