CAcaveman

POST /projects/{projectId}/agent-runs

POST /api/v1/projects/{projectId}/agent-runs on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the run_agent action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic. Native user endpoint. Scoped agent sessions and workload credentials cannot call this operation. Organization budget edits additionally require billing:write. Interactive grants bind current membership and role; input, audit, run and outbox admission commit atomically. Reuse the same request identity, input and deadline on retries.

post/projects/{projectId}/agent-runs

Request

  • Base URL
    https://api.caveman.so/api/v1
  • URL
    https://api.caveman.so/api/v1/projects/{projectId}/agent-runs
  • Auth
    • OAuth 2
      Authorization code: /api/v1/oauth/authorize
      Token URL: /api/v1/oauth/token scopes: proposal:draft
    • or HTTP bearer
    • or API key in cookie cave_access
    • or API key in cookie __Secure-cave_identity.session_token

Request body

parent_run_idstring uuid
request_idstring uuid required
deadlinestring date-time
fixboolean

Ask for a repair case instead of an answer.

modelstring

provider/model from GET ask/models. Omitted: the parent turn's model on a follow-up, else the default.

Response

Native operation persisted.

principal_idstring required
result_refstring uuid nullable required
idstring uuid required
organization_idstring uuid required
project_idstring uuid required
case_idstring uuid required
generationinteger required
grant_idstring uuid nullable

Null: runs admit without a grant (ADR 0069). Set only on runs of the retired executor.

grant_revisioninteger nullable
definition_idstring required
definition_versionstring required
definition_digeststring required
origin'chat' | 'pull_request' | 'trace' | 'monitor' | 'deployment' | 'scan' | 'optimization' required
input_refstring uuid required
budget_keysstring[] required
status'queued' | 'running' | 'completed' | 'incomplete' | 'cancelled' | 'stale' required
reasonstring required
deadlinestring date-time required
created_atstring date-time required
model_idstring nullable
model_versionstring nullable
modelstring

The model the run was admitted on, the same as model_id; absent when the run stamped none.

Changes

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