{ "openapi": "3.1.0", "info": { "title": "Caveman Cloud API", "version": "1.0.0", "x-caveman-generated-operation-count": 238, "summary": "Programmatic control plane for Caveman Cloud: AI traffic telemetry, spend attribution, optimization policy, evals, and signed savings evidence.", "description": "The Caveman Cloud control plane. It is the API behind the dashboard at https://caveman.so, the `caveman` CLI, and the Caveman MCP server.\n\n**Base URL** — `https://api.caveman.so/api/v1`. `GET /health/live` and `GET /health/ready` sit outside the prefix.\n\n**Authentication** — every authenticated call carries one access token, presented either as `Authorization: Bearer ` or as the `cave_access` cookie. Cookie-authenticated mutations additionally require the `x-cave-csrf: ui` header. Tokens are minted by `POST /auth/login` or by the RFC 8628 device-authorization grant (`POST /auth/device/code` then `POST /auth/device/token`); see https://caveman.so/.well-known/oauth-authorization-server.\n\n**Scopes** — a token may be narrowed to a subset of the caller's role permissions. Authorization is the intersection of the two: a scope never grants authority the role lacks. Each operation lists the scopes it requires under `x-caveman-required-scopes`.\n\n**Errors** — every failure returns the `ErrorEnvelope` JSON body with a stable `error.code`. Match on the code, never on the message.\n\n**Without credentials** — `GET /system/version` and `GET /providers/catalog` are unauthenticated.", "contact": { "name": "Caveman", "email": "contact@caveman.so", "url": "https://caveman.so/contact" }, "license": { "name": "Proprietary", "url": "https://caveman.so/terms" } }, "servers": [ { "url": "https://api.caveman.so/api/v1", "description": "Caveman Cloud (managed)" }, { "url": "/api/v1", "description": "Same-origin or self-hosted control plane" } ], "paths": { "/admin/clickhouse-usage": { "get": { "summary": "GET /admin/clickhouse-usage", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "getAdminClickhouseUsage", "description": "GET /api/v1/admin/clickhouse-usage on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/admin/orgs": { "post": { "summary": "POST /admin/orgs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "postAdminOrgs", "description": "POST /api/v1/admin/orgs on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/admin/orgs/{orgId}/plan": { "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /admin/orgs/{orgId}/plan", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "patchAdminOrgsOrgIdPlan", "description": "PATCH /api/v1/admin/orgs/{orgId}/plan on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/artifacts": { "get": { "summary": "GET /artifacts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getArtifacts", "description": "GET /api/v1/artifacts on the Caveman Cloud control plane. Requires the artifact:read_metadata scope. Not exposed to autonomous agents: Deletes, exports or changes the retention of tenant data. Irreversible or data-egress; requires a human actor in the audit trail.", "security": [ { "oauth2": [ "artifact:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "artifact:read_metadata" ] } }, "/artifacts/{artifactId}": { "parameters": [ { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /artifacts/{artifactId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteArtifactsArtifactId", "description": "DELETE /api/v1/artifacts/{artifactId} on the Caveman Cloud control plane. Requires the artifact:delete scope. Not exposed to autonomous agents: Deletes, exports or changes the retention of tenant data. Irreversible or data-egress; requires a human actor in the audit trail.", "security": [ { "oauth2": [ "artifact:delete" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "artifact:delete" ] }, "get": { "summary": "GET /artifacts/{artifactId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getArtifactsArtifactId", "description": "GET /api/v1/artifacts/{artifactId} on the Caveman Cloud control plane. Requires the artifact:read_metadata scope. Not exposed to autonomous agents: Deletes, exports or changes the retention of tenant data. Irreversible or data-egress; requires a human actor in the audit trail.", "security": [ { "oauth2": [ "artifact:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "artifact:read_metadata" ] } }, "/audit-logs": { "get": { "summary": "Append-only audit logs", "responses": { "200": { "description": "Audit log page" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getAuditLogs", "description": "GET /api/v1/audit-logs on the Caveman Cloud control plane. Requires the auditlog:read scope. Exposed to autonomous agents as the list action of the caveman_audit tool (read access). The tenant audit trail: who changed what, when, and from where. An agent reads it to confirm its own writes actually landed. Separate from caveman_policy because reading it requires an owner/admin-level scope that the rest of policy reading does not.", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "auditlog:read" ] } }, "/audits": { "get": { "summary": "GET /audits", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getAudits", "description": "GET /api/v1/audits on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Audits are a governance artifact with a named human owner.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /audits", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postAudits", "description": "POST /api/v1/audits on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Audits are a governance artifact with a named human owner.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/audits/{auditId}": { "parameters": [ { "name": "auditId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /audits/{auditId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getAuditsAuditId", "description": "GET /api/v1/audits/{auditId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Audits are a governance artifact with a named human owner.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/audits/{auditId}/findings": { "parameters": [ { "name": "auditId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /audits/{auditId}/findings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getAuditsAuditIdFindings", "description": "GET /api/v1/audits/{auditId}/findings on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Audits are a governance artifact with a named human owner.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/auth/bootstrap-owner": { "post": { "summary": "Create first owner once", "responses": { "200": { "description": "Owner created" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "postAuthBootstrapOwner", "description": "POST /api/v1/auth/bootstrap-owner on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/device/ack": { "post": { "summary": "Acknowledge durable device credentials", "responses": { "200": { "description": "Credential envelope persisted and replay marker purged" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postAuthDeviceAck", "description": "POST /api/v1/auth/device/ack on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Mints or approves a credential. An agent must never be able to widen its own access — this is the escalation boundary that makes scoped agent connections meaningful.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/auth/device/approve": { "post": { "summary": "POST /auth/device/approve", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postAuthDeviceApprove", "description": "POST /api/v1/auth/device/approve on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Mints or approves a credential. An agent must never be able to widen its own access — this is the escalation boundary that makes scoped agent connections meaningful.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/auth/device/code": { "post": { "summary": "POST /auth/device/code", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "postAuthDeviceCode", "description": "POST /api/v1/auth/device/code on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/device/token": { "post": { "summary": "POST /auth/device/token", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "postAuthDeviceToken", "description": "POST /api/v1/auth/device/token on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/login": { "post": { "summary": "Log in", "responses": { "200": { "description": "Access and refresh tokens" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "postAuthLogin", "description": "POST /api/v1/auth/login on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/logout": { "post": { "summary": "POST /auth/logout", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "postAuthLogout", "description": "POST /api/v1/auth/logout on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/me": { "get": { "summary": "GET /auth/me", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getAuthMe", "description": "GET /api/v1/auth/me on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the whoami action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/auth/oidc/{provider}/callback": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /auth/oidc/{provider}/callback", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "getAuthOidcProviderCallback", "description": "GET /api/v1/auth/oidc/{provider}/callback on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/oidc/{provider}/start": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /auth/oidc/{provider}/start", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "getAuthOidcProviderStart", "description": "GET /api/v1/auth/oidc/{provider}/start on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/organizations": { "get": { "summary": "List active workspace memberships", "description": "GET /api/v1/auth/organizations on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Moves the caller across the organization boundary. A project-scoped agent session must never leave its tenant.", "responses": { "200": { "description": "Active memberships visible to the authenticated account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMembership" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Authentication required." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getAuthOrganizations", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/auth/password/change": { "post": { "summary": "POST /auth/password/change", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postAuthPasswordChange", "description": "POST /api/v1/auth/password/change on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Mints or approves a credential. An agent must never be able to widen its own access — this is the escalation boundary that makes scoped agent connections meaningful.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/auth/password/reset/confirm": { "post": { "summary": "Confirm a password reset", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "new_password" ], "properties": { "token": { "type": "string" }, "new_password": { "type": "string", "minLength": 12, "maxLength": 1024 } } } } } }, "responses": { "200": { "description": "Password reset and existing sessions revoked" }, "400": { "description": "Weak password or invalid, expired, or consumed token" }, "429": { "description": "Rate limited" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "operationId": "postAuthPasswordResetConfirm", "description": "POST /api/v1/auth/password/reset/confirm on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/password/reset/request": { "post": { "summary": "Request a password reset email", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "202": { "description": "Enumeration-neutral reset request accepted" }, "429": { "description": "Rate limited" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "operationId": "postAuthPasswordResetRequest", "description": "POST /api/v1/auth/password/reset/request on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/refresh": { "post": { "summary": "POST /auth/refresh", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "postAuthRefresh", "description": "POST /api/v1/auth/refresh on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/saml/{provider}/acs": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /auth/saml/{provider}/acs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [], "operationId": "postAuthSamlProviderAcs", "description": "POST /api/v1/auth/saml/{provider}/acs on the Caveman Cloud control plane. Unauthenticated but rate-limited; it establishes or ends a session rather than reading tenant data. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/saml/{provider}/metadata": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /auth/saml/{provider}/metadata", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [], "operationId": "getAuthSamlProviderMetadata", "description": "GET /api/v1/auth/saml/{provider}/metadata on the Caveman Cloud control plane. Unauthenticated, or authenticated by a request signature rather than a session. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/auth/switch-organization": { "post": { "summary": "Rotate the session into another workspace", "description": "POST /api/v1/auth/switch-organization on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Moves the caller across the organization boundary. A project-scoped agent session must never leave its tenant.", "parameters": [ { "name": "x-cave-csrf", "in": "header", "required": false, "description": "Required as ui for cookie-authenticated browser requests; omit for bearer Authorization requests.", "schema": { "type": "string", "enum": [ "ui" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id" ], "properties": { "organization_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Session rotated into the selected active membership.", "headers": { "Set-Cookie": { "description": "HttpOnly cave_access and cave_refresh replacement cookies for browser clients.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Malformed target organization id or JSON body." }, "401": { "description": "Authentication required or the bound session is no longer valid." }, "403": { "description": "Target organization is not an active membership of the authenticated user, or browser CSRF header is missing." }, "500": { "description": "Session rotation or token signing failed; no replacement credentials are returned." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postAuthSwitchOrganization", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/billing/account": { "get": { "summary": "GET /billing/account", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getBillingAccount", "description": "GET /api/v1/billing/account on the Caveman Cloud control plane. Requires the billing:read scope. Not exposed to autonomous agents: Changes billing, spend ceilings, or the money contract. Human-only regardless of agent competence.", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/billing/portal": { "post": { "summary": "POST /billing/portal", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postBillingPortal", "description": "POST /api/v1/billing/portal on the Caveman Cloud control plane. Requires the billing:write scope. Not exposed to autonomous agents: Changes billing, spend ceilings, or the money contract. Human-only regardless of agent competence.", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/cave-plan": { "get": { "summary": "GET /cave-plan", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getCavePlan", "description": "GET /api/v1/cave-plan on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the org_plan action of the caveman_plan tool (read access). The ranked list of where this project is wasting money and what would fix it, plus the Cave Score. This is the agent's work queue.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/data-requests": { "get": { "summary": "GET /data-requests", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getDataRequests", "description": "GET /api/v1/data-requests on the Caveman Cloud control plane. Requires the auditlog:read scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "auditlog:read" ] }, "post": { "summary": "POST /data-requests", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postDataRequests", "description": "POST /api/v1/data-requests on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/data-requests/{requestId}": { "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /data-requests/{requestId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getDataRequestsRequestId", "description": "GET /api/v1/data-requests/{requestId} on the Caveman Cloud control plane. Requires the auditlog:read scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "auditlog:read" ] } }, "/data-requests/{requestId}/download": { "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /data-requests/{requestId}/download", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getDataRequestsRequestIdDownload", "description": "GET /api/v1/data-requests/{requestId}/download on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/data-sources/catalog": { "get": { "summary": "GET /data-sources/catalog", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getDataSourcesCatalog", "description": "GET /api/v1/data-sources/catalog on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the data_source_catalog action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/eval-evidence": { "get": { "summary": "GET /eval-evidence", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getEvalEvidence", "description": "GET /api/v1/eval-evidence on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_evidence action of the caveman_evals tool (read access). Eval suites, their cases, and the evidence produced by running them.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/eval-evidence/batches": { "post": { "summary": "POST /eval-evidence/batches", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postEvalEvidenceBatches", "description": "POST /api/v1/eval-evidence/batches on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the ingest_evidence action of the caveman_evals_write tool (write access). Create eval suites, replace their case sets, ingest external eval evidence in batches, and run a baseline. Evidence ingest supports dry_run — always dry-run first.", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/eval-suites": { "get": { "summary": "GET /eval-suites", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getEvalSuites", "description": "GET /api/v1/eval-suites on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_suites action of the caveman_evals tool (read access). Eval suites, their cases, and the evidence produced by running them.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /eval-suites", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postEvalSuites", "description": "POST /api/v1/eval-suites on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the create_suite action of the caveman_evals_write tool (write access). Create eval suites, replace their case sets, ingest external eval evidence in batches, and run a baseline. Evidence ingest supports dry_run — always dry-run first.", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/eval-suites/{suiteId}": { "parameters": [ { "name": "suiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /eval-suites/{suiteId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getEvalSuitesSuiteId", "description": "GET /api/v1/eval-suites/{suiteId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_suite action of the caveman_evals tool (read access). Eval suites, their cases, and the evidence produced by running them.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "put": { "summary": "PUT /eval-suites/{suiteId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "putEvalSuitesSuiteId", "description": "PUT /api/v1/eval-suites/{suiteId} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the update_suite action of the caveman_evals_write tool (write access). Create eval suites, replace their case sets, ingest external eval evidence in batches, and run a baseline. Evidence ingest supports dry_run — always dry-run first.", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/eval-suites/{suiteId}/cases": { "parameters": [ { "name": "suiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /eval-suites/{suiteId}/cases", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getEvalSuitesSuiteIdCases", "description": "GET /api/v1/eval-suites/{suiteId}/cases on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_cases action of the caveman_evals tool (read access). Eval suites, their cases, and the evidence produced by running them.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /eval-suites/{suiteId}/cases", "description": "POST /api/v1/eval-suites/{suiteId}/cases on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the add_case action of the caveman_evals_write tool (write access). Create eval suites, replace their case sets, ingest external eval evidence in batches, and run a baseline. Evidence ingest supports dry_run — always dry-run first.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "fixture", "graders" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "fixture": { "$ref": "https://caveman.so/schemas/eval-case.schema.json#/properties/fixture" }, "graders": { "$ref": "https://caveman.so/schemas/eval-case.schema.json#/properties/graders" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Eval case created." }, "422": { "description": "Legacy storage-backed case shape is unsupported." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postEvalSuitesSuiteIdCases", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] }, "put": { "summary": "PUT /eval-suites/{suiteId}/cases", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "putEvalSuitesSuiteIdCases", "description": "PUT /api/v1/eval-suites/{suiteId}/cases on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the replace_cases action of the caveman_evals_write tool (write access). Create eval suites, replace their case sets, ingest external eval evidence in batches, and run a baseline. Evidence ingest supports dry_run — always dry-run first.", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/eval-suites/{suiteId}/run-baseline": { "parameters": [ { "name": "suiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /eval-suites/{suiteId}/run-baseline", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postEvalSuitesSuiteIdRunBaseline", "description": "POST /api/v1/eval-suites/{suiteId}/run-baseline on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the run_baseline action of the caveman_evals_write tool (write access). Create eval suites, replace their case sets, ingest external eval evidence in batches, and run a baseline. Evidence ingest supports dry_run — always dry-run first.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/experiments": { "get": { "summary": "List experiments", "responses": { "200": { "description": "Experiment page" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getExperiments", "description": "GET /api/v1/experiments on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list action of the caveman_experiments tool (read access). Experiment state, results and run timelines.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "Create experiment", "responses": { "201": { "description": "Experiment created" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postExperiments", "description": "POST /api/v1/experiments on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the create action of the caveman_experiments_write tool (write access). Create, start and cancel experiments. Approving an S3 experiment and rolling one back stay human-only.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/experiments/{experimentId}": { "parameters": [ { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /experiments/{experimentId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getExperimentsExperimentId", "description": "GET /api/v1/experiments/{experimentId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get action of the caveman_experiments tool (read access). Experiment state, results and run timelines.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/experiments/{experimentId}/approve": { "parameters": [ { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /experiments/{experimentId}/approve", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postExperimentsExperimentIdApprove", "description": "POST /api/v1/experiments/{experimentId}/approve on the Caveman Cloud control plane. Requires the experiment:approve_s3 scope. Not exposed to autonomous agents: Publishes or rolls back live traffic policy at S2/S3. Agents draft and experiment; a human promotes.", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } }, "/experiments/{experimentId}/cancel": { "parameters": [ { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /experiments/{experimentId}/cancel", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postExperimentsExperimentIdCancel", "description": "POST /api/v1/experiments/{experimentId}/cancel on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the cancel action of the caveman_experiments_write tool (write access). Create, start and cancel experiments. Approving an S3 experiment and rolling one back stay human-only.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/experiments/{experimentId}/results": { "parameters": [ { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /experiments/{experimentId}/results", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getExperimentsExperimentIdResults", "description": "GET /api/v1/experiments/{experimentId}/results on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the results action of the caveman_experiments tool (read access). Experiment state, results and run timelines.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/experiments/{experimentId}/rollback": { "parameters": [ { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /experiments/{experimentId}/rollback", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postExperimentsExperimentIdRollback", "description": "POST /api/v1/experiments/{experimentId}/rollback on the Caveman Cloud control plane. Requires the experiment:approve_s3 scope. Not exposed to autonomous agents: Publishes or rolls back live traffic policy at S2/S3. Agents draft and experiment; a human promotes.", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } }, "/experiments/{experimentId}/runs": { "parameters": [ { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /experiments/{experimentId}/runs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getExperimentsExperimentIdRuns", "description": "GET /api/v1/experiments/{experimentId}/runs on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the runs action of the caveman_experiments tool (read access). Experiment state, results and run timelines.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/experiments/{experimentId}/start": { "parameters": [ { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /experiments/{experimentId}/start", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postExperimentsExperimentIdStart", "description": "POST /api/v1/experiments/{experimentId}/start on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the start action of the caveman_experiments_write tool (write access). Create, start and cancel experiments. Approving an S3 experiment and rolling one back stay human-only.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/exports": { "get": { "summary": "GET /exports", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getExports", "description": "GET /api/v1/exports on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Deletes, exports or changes the retention of tenant data. Irreversible or data-egress; requires a human actor in the audit trail.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/github/callback": { "get": { "summary": "GET /github/callback", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [], "operationId": "getGithubCallback", "description": "GET /api/v1/github/callback on the Caveman Cloud control plane. Unauthenticated, or authenticated by a request signature rather than a session. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/github/webhook": { "post": { "summary": "POST /github/webhook", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [], "operationId": "postGithubWebhook", "description": "POST /api/v1/github/webhook on the Caveman Cloud control plane. Unauthenticated, or authenticated by a request signature rather than a session. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/imports": { "get": { "summary": "GET /imports", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getImports", "description": "GET /api/v1/imports on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Bulk-ingests traces into the evidence plane. A wrong import silently corrupts every downstream cost and savings number, so a human owns the decision.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /imports", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postImports", "description": "POST /api/v1/imports on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Bulk-ingests traces into the evidence plane. A wrong import silently corrupts every downstream cost and savings number, so a human owns the decision.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/jobs/{jobId}": { "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /jobs/{jobId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getJobsJobId", "description": "GET /api/v1/jobs/{jobId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Internal job plumbing. Agents observe outcomes through the resource they acted on, not the queue underneath it.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/me/delivery": { "get": { "summary": "GET /me/delivery", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getMeDelivery", "description": "GET /api/v1/me/delivery on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the my_delivery action of the caveman_people tool (read access). Org members, seats, and per-person spend and delivery attribution. Read-only — an agent never creates or changes an identity.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/me/personal-key": { "post": { "summary": "POST /me/personal-key", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postMePersonalKey", "description": "POST /api/v1/me/personal-key on the Caveman Cloud control plane. Requires the key:self scope. Not exposed to autonomous agents: Mints or approves a credential. An agent must never be able to widen its own access — this is the escalation boundary that makes scoped agent connections meaningful.", "security": [ { "oauth2": [ "key:self" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "key:self" ] } }, "/me/usage": { "get": { "summary": "GET /me/usage", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getMeUsage", "description": "GET /api/v1/me/usage on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the my_usage action of the caveman_people tool (read access). Org members, seats, and per-person spend and delivery attribution. Read-only — an agent never creates or changes an identity.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/me/wrap-entitlement": { "post": { "summary": "POST /me/wrap-entitlement", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postMeWrapEntitlement", "description": "POST /api/v1/me/wrap-entitlement on the Caveman Cloud control plane. Requires the key:self scope. Not exposed to autonomous agents: Mints or approves a credential. An agent must never be able to widen its own access — this is the escalation boundary that makes scoped agent connections meaningful.", "security": [ { "oauth2": [ "key:self" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "key:self" ] } }, "/metering/receipts": { "get": { "summary": "GET /metering/receipts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getMeteringReceipts", "description": "GET /api/v1/metering/receipts on the Caveman Cloud control plane. Requires the billing:read scope. Not exposed to autonomous agents: Changes billing, spend ceilings, or the money contract. Human-only regardless of agent competence.", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/opportunities": { "get": { "summary": "Optimization opportunities", "responses": { "200": { "description": "Ranked opportunities" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOpportunities", "description": "GET /api/v1/opportunities on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_opportunities action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/opportunities/{opportunityId}": { "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /opportunities/{opportunityId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOpportunitiesOpportunityId", "description": "GET /api/v1/opportunities/{opportunityId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_opportunity action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/opportunities/{opportunityId}/create-experiment": { "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /opportunities/{opportunityId}/create-experiment", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOpportunitiesOpportunityIdCreateExperiment", "description": "POST /api/v1/opportunities/{opportunityId}/create-experiment on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the create_experiment action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/opportunities/{opportunityId}/dismiss": { "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /opportunities/{opportunityId}/dismiss", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOpportunitiesOpportunityIdDismiss", "description": "POST /api/v1/opportunities/{opportunityId}/dismiss on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the dismiss_opportunity action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/opportunities/{opportunityId}/mark-implemented": { "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /opportunities/{opportunityId}/mark-implemented", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOpportunitiesOpportunityIdMarkImplemented", "description": "POST /api/v1/opportunities/{opportunityId}/mark-implemented on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the mark_implemented action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/optimization-proposals": { "get": { "summary": "GET /optimization-proposals", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOptimizationProposals", "description": "GET /api/v1/optimization-proposals on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_proposals action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /optimization-proposals", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOptimizationProposals", "description": "POST /api/v1/optimization-proposals on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the create_proposal action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/optimization-proposals/{proposalId}": { "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /optimization-proposals/{proposalId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOptimizationProposalsProposalId", "description": "GET /api/v1/optimization-proposals/{proposalId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_proposal action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/optimization-proposals/{proposalId}/evidence": { "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /optimization-proposals/{proposalId}/evidence", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOptimizationProposalsProposalIdEvidence", "description": "POST /api/v1/optimization-proposals/{proposalId}/evidence on the Caveman Cloud control plane. Requires the proposal:draft scope. Not exposed to autonomous agents: Writes the fix ladder from a bundle the caller authored about its own work. An agent that both implements the fix and posts the evidence is grading itself; the bundle is labeled self_reported for exactly that reason, and it stays a human-run `caveman agent submit`.", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/optimization-proposals/{proposalId}/packet": { "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /optimization-proposals/{proposalId}/packet", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOptimizationProposalsProposalIdPacket", "description": "GET /api/v1/optimization-proposals/{proposalId}/packet on the Caveman Cloud control plane. Requires the proposal:draft scope. Not exposed to autonomous agents: Issues the FixPacket a coding agent implements from, and mints a GitHub App token to resolve the base commit. The local fix lane is driven by `caveman agent pull` under a human's hands; handing an MCP agent its own work order is the same deferral as POST /run.", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/optimization-proposals/{proposalId}/reject": { "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /optimization-proposals/{proposalId}/reject", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOptimizationProposalsProposalIdReject", "description": "POST /api/v1/optimization-proposals/{proposalId}/reject on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the reject_proposal action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/optimization-proposals/{proposalId}/run": { "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /optimization-proposals/{proposalId}/run", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOptimizationProposalsProposalIdRun", "description": "POST /api/v1/optimization-proposals/{proposalId}/run on the Caveman Cloud control plane. Requires the proposal:draft scope. Not exposed to autonomous agents: Dispatches the server-side Cave Agent to open a pull request in the customer's repository. Deferred until the cloud-agent lane is reviewed on its own terms.", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/optimization-proposals/{proposalId}/runs": { "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /optimization-proposals/{proposalId}/runs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOptimizationProposalsProposalIdRuns", "description": "GET /api/v1/optimization-proposals/{proposalId}/runs on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the proposal_runs action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/optimization-proposals/from-move": { "post": { "summary": "POST /optimization-proposals/from-move", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOptimizationProposalsFromMove", "description": "POST /api/v1/optimization-proposals/from-move on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the create_proposal_from_move action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/org": { "get": { "summary": "GET /org", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrg", "description": "GET /api/v1/org on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the get_org action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "patch": { "summary": "PATCH /org", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchOrg", "description": "PATCH /api/v1/org on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Changes organization-wide settings that every project inherits. Outside a project-scoped agent connection's blast radius by design.", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/org/compute-budget": { "put": { "summary": "PUT /org/compute-budget", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "putOrgComputeBudget", "description": "PUT /api/v1/org/compute-budget on the Caveman Cloud control plane. Requires the billing:write scope. Not exposed to autonomous agents: Changes billing, spend ceilings, or the money contract. Human-only regardless of agent competence.", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/org/compute-budget/check": { "post": { "summary": "POST /org/compute-budget/check", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOrgComputeBudgetCheck", "description": "POST /api/v1/org/compute-budget/check on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Writes into the compute metering ledger that billing reads. Only the worker and the human-facing plane may write it.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/org/compute-usage": { "get": { "summary": "GET /org/compute-usage", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgComputeUsage", "description": "GET /api/v1/org/compute-usage on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Compute metering is a billing surface; it is read in the dashboard next to the invoice it explains.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/org/consents": { "get": { "summary": "GET /org/consents", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgConsents", "description": "GET /api/v1/org/consents on the Caveman Cloud control plane. Requires the auditlog:read scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "auditlog:read" ] }, "post": { "summary": "POST /org/consents", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOrgConsents", "description": "POST /api/v1/org/consents on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/org/consents/status": { "get": { "summary": "GET /org/consents/status", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgConsentsStatus", "description": "GET /api/v1/org/consents/status on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the consent_status action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/org/data": { "delete": { "summary": "DELETE /org/data", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteOrgData", "description": "DELETE /api/v1/org/data on the Caveman Cloud control plane. Requires the org:delete scope. Not exposed to autonomous agents: Deletes, exports or changes the retention of tenant data. Irreversible or data-egress; requires a human actor in the audit trail.", "security": [ { "oauth2": [ "org:delete" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:delete" ] } }, "/org/members": { "get": { "summary": "GET /org/members", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgMembers", "description": "GET /api/v1/org/members on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the list_members action of the caveman_people tool (read access). Org members, seats, and per-person spend and delivery attribution. Read-only — an agent never creates or changes an identity.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/org/members/{membershipId}": { "parameters": [ { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /org/members/{membershipId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteOrgMembersMembershipId", "description": "DELETE /api/v1/org/members/{membershipId} on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Creates or changes an organization identity. An agent proposes members; a human invites them, because a wrongly-added member is an access-control breach, not a config mistake.", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] }, "patch": { "summary": "PATCH /org/members/{membershipId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchOrgMembersMembershipId", "description": "PATCH /api/v1/org/members/{membershipId} on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Creates or changes an organization identity. An agent proposes members; a human invites them, because a wrongly-added member is an access-control breach, not a config mistake.", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/org/members/invite": { "post": { "summary": "POST /org/members/invite", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOrgMembersInvite", "description": "POST /api/v1/org/members/invite on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Creates or changes an organization identity. An agent proposes members; a human invites them, because a wrongly-added member is an access-control breach, not a config mistake.", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/org/oidc": { "get": { "summary": "GET /org/oidc", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgOidc", "description": "GET /api/v1/org/oidc on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Creates or changes an organization identity. An agent proposes members; a human invites them, because a wrongly-added member is an access-control breach, not a config mistake.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "post": { "summary": "POST /org/oidc", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOrgOidc", "description": "POST /api/v1/org/oidc on the Caveman Cloud control plane. Requires the sso:manage scope. Not exposed to autonomous agents: Creates or changes an organization identity. An agent proposes members; a human invites them, because a wrongly-added member is an access-control breach, not a config mistake.", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] } }, "/org/oidc/{providerId}": { "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /org/oidc/{providerId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteOrgOidcProviderId", "description": "DELETE /api/v1/org/oidc/{providerId} on the Caveman Cloud control plane. Requires the sso:manage scope. Not exposed to autonomous agents: Creates or changes an organization identity. An agent proposes members; a human invites them, because a wrongly-added member is an access-control breach, not a config mistake.", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] }, "patch": { "summary": "PATCH /org/oidc/{providerId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchOrgOidcProviderId", "description": "PATCH /api/v1/org/oidc/{providerId} on the Caveman Cloud control plane. Requires the sso:manage scope. Not exposed to autonomous agents: Creates or changes an organization identity. An agent proposes members; a human invites them, because a wrongly-added member is an access-control breach, not a config mistake.", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] } }, "/org/practice-rollup-consents": { "get": { "summary": "GET /org/practice-rollup-consents", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgPracticeRollupConsents", "description": "GET /api/v1/org/practice-rollup-consents on the Caveman Cloud control plane. Requires the settings:read scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/org/replay-consents": { "get": { "summary": "GET /org/replay-consents", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgReplayConsents", "description": "GET /api/v1/org/replay-consents on the Caveman Cloud control plane. Requires the settings:read scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/org/retention": { "get": { "summary": "GET /org/retention", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgRetention", "description": "GET /api/v1/org/retention on the Caveman Cloud control plane. Requires the settings:read scope. Exposed to autonomous agents as the org_retention action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] }, "patch": { "summary": "PATCH /org/retention", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchOrgRetention", "description": "PATCH /api/v1/org/retention on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Deletes, exports or changes the retention of tenant data. Irreversible or data-egress; requires a human actor in the audit trail.", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/org/seats": { "get": { "summary": "GET /org/seats", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgSeats", "description": "GET /api/v1/org/seats on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the seats action of the caveman_people tool (read access). Org members, seats, and per-person spend and delivery attribution. Read-only — an agent never creates or changes an identity.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/orgs/{orgId}/autopilot/pause": { "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /orgs/{orgId}/autopilot/pause", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteOrgsOrgIdAutopilotPause", "description": "DELETE /api/v1/orgs/{orgId}/autopilot/pause on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Publishes or rolls back live traffic policy at S2/S3. Agents draft and experiment; a human promotes.", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] }, "get": { "summary": "GET /orgs/{orgId}/autopilot/pause", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getOrgsOrgIdAutopilotPause", "description": "GET /api/v1/orgs/{orgId}/autopilot/pause on the Caveman Cloud control plane. Requires the settings:read scope. Not exposed to autonomous agents: Publishes or rolls back live traffic policy at S2/S3. Agents draft and experiment; a human promotes.", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] }, "post": { "summary": "POST /orgs/{orgId}/autopilot/pause", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postOrgsOrgIdAutopilotPause", "description": "POST /api/v1/orgs/{orgId}/autopilot/pause on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Publishes or rolls back live traffic policy at S2/S3. Agents draft and experiment; a human promotes.", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/practice-evidence": { "get": { "summary": "GET /practice-evidence", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getPracticeEvidence", "description": "GET /api/v1/practice-evidence on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the org_practice_evidence action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/practice-findings": { "post": { "summary": "Sync tenant-local, tokens-only practice findings", "responses": { "200": { "description": "Current authenticated user's findings replaced." }, "400": { "description": "Unknown fields, practices, basis values, or malformed counters are rejected." }, "403": { "description": "Enterprise ZDR refuses local practice telemetry." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postPracticeFindings", "description": "POST /api/v1/practice-findings on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the submit_practice_findings action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects": { "get": { "summary": "List projects", "responses": { "200": { "description": "Project page" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjects", "description": "GET /api/v1/projects on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the list_projects action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "post": { "summary": "Create project", "responses": { "201": { "description": "Project created" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjects", "description": "POST /api/v1/projects on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Creates a new tenant container. A project-scoped connection is bound to one project and cannot create siblings; keeping this human-only makes that bound explicit rather than incidental.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectId", "description": "GET /api/v1/projects/{projectId} on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the get_project action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "patch": { "summary": "PATCH /projects/{projectId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchProjectsProjectId", "description": "PATCH /api/v1/projects/{projectId} on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Renames the project other systems and reports key on. Cosmetic but confusing to do behind a human's back.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/agent-build-regressions": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List agent build regression findings", "responses": { "200": { "description": "Tenant-scoped regression findings", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdAgentBuildRegressions", "description": "GET /api/v1/projects/{projectId}/agent-build-regressions on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the regressions action of the caveman_builds tool (read access). Registered agent builds, their evidence, and detected regressions.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-builds": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List registered agent builds", "responses": { "200": { "description": "Newest 200 tenant-scoped builds", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBuild" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdAgentBuilds", "description": "GET /api/v1/projects/{projectId}/agent-builds on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list action of the caveman_builds tool (read access). Registered agent builds, their evidence, and detected regressions.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "Register immutable inferred agent build", "responses": { "201": { "description": "Build registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBuild" } } } }, "400": { "description": "Malformed, semantically invalid, or digest-mismatched build" }, "409": { "description": "Build digest already exists with different evidence" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "description": "Registers local build evidence only. Registration never activates plan or changes verified savings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBuildRegistration" } } } }, "operationId": "postProjectsProjectIdAgentBuilds", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/agent-builds/{buildSha256}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "buildSha256", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get registered agent build", "responses": { "200": { "description": "Tenant-scoped build", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBuild" } } } }, "404": { "description": "Build not found in project" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdAgentBuildsBuildSha256", "description": "GET /api/v1/projects/{projectId}/agent-builds/{buildSha256} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get action of the caveman_builds tool (read access). Registered agent builds, their evidence, and detected regressions.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-builds/{buildSha256}/evidence": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "buildSha256", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get observed traffic evidence for registered build", "responses": { "200": { "description": "Content-blind observed evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBuildEvidence" } } } }, "404": { "description": "Build not found in project" }, "422": { "description": "Requested window exceeds raw-trace retention" }, "503": { "description": "Retention policy could not be checked" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "description": "Identity is client-declared and observed. verified_savings_usd remains zero.", "parameters": [ { "name": "window", "in": "query", "required": false, "description": "Observed traffic window. Defaults to 30d.", "schema": { "type": "string", "enum": [ "7d", "14d", "30d", "60d", "90d" ], "default": "30d" } } ], "operationId": "getProjectsProjectIdAgentBuildsBuildSha256Evidence", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-connections": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-connections", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdAgentConnections", "description": "GET /api/v1/projects/{projectId}/agent-connections on the Caveman Cloud control plane. Requires the org:read scope.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/projects/{projectId}/agent-connections/{connectionId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/agent-connections/{connectionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteProjectsProjectIdAgentConnectionsConnectionId", "description": "DELETE /api/v1/projects/{projectId}/agent-connections/{connectionId} on the Caveman Cloud control plane. Requires the key:manage scope.", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] } }, "/projects/{projectId}/agents": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agents", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdAgents", "description": "GET /api/v1/projects/{projectId}/agents on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_agents action of the caveman_workflows tool (read access). Agents, workflows, and the observed workflow fingerprint registry that traffic is attributed to.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/agents", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdAgents", "description": "POST /api/v1/projects/{projectId}/agents on the Caveman Cloud control plane. Requires the policy:draft scope. Exposed to autonomous agents as the create_agent action of the caveman_workflows_write tool (write access). Create and update the agents and workflows that traffic is labelled against. This is what makes per-workflow cost attribution work.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/agents/{agentId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agents/{agentId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdAgentsAgentId", "description": "GET /api/v1/projects/{projectId}/agents/{agentId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_agent action of the caveman_workflows tool (read access). Agents, workflows, and the observed workflow fingerprint registry that traffic is attributed to.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /projects/{projectId}/agents/{agentId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchProjectsProjectIdAgentsAgentId", "description": "PATCH /api/v1/projects/{projectId}/agents/{agentId} on the Caveman Cloud control plane. Requires the policy:draft scope. Exposed to autonomous agents as the update_agent action of the caveman_workflows_write tool (write access). Create and update the agents and workflows that traffic is labelled against. This is what makes per-workflow cost attribution work.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/agents/{agentId}/workflows": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agents/{agentId}/workflows", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdAgentsAgentIdWorkflows", "description": "GET /api/v1/projects/{projectId}/agents/{agentId}/workflows on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list action of the caveman_workflows tool (read access). Agents, workflows, and the observed workflow fingerprint registry that traffic is attributed to.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/agents/{agentId}/workflows", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdAgentsAgentIdWorkflows", "description": "POST /api/v1/projects/{projectId}/agents/{agentId}/workflows on the Caveman Cloud control plane. Requires the policy:draft scope. Exposed to autonomous agents as the create action of the caveman_workflows_write tool (write access). Create and update the agents and workflows that traffic is labelled against. This is what makes per-workflow cost attribution work.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/autopilot/moves": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/autopilot/moves", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdAutopilotMoves", "description": "GET /api/v1/projects/{projectId}/autopilot/moves on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_moves action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/budgets": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/budgets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdBudgets", "description": "GET /api/v1/projects/{projectId}/budgets on the Caveman Cloud control plane. Requires any one of the scopes billing:read, policy:draft. Exposed to autonomous agents as the budgets action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "security": [ { "oauth2": [ "billing:read", "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read", "policy:draft" ] }, "patch": { "summary": "PATCH /projects/{projectId}/budgets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchProjectsProjectIdBudgets", "description": "PATCH /api/v1/projects/{projectId}/budgets on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Changes billing, spend ceilings, or the money contract. Human-only regardless of agent competence.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/capabilities": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/capabilities", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdCapabilities", "description": "GET /api/v1/projects/{projectId}/capabilities on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the get_capabilities action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "put": { "summary": "PUT /projects/{projectId}/capabilities", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "putProjectsProjectIdCapabilities", "description": "PUT /api/v1/projects/{projectId}/capabilities on the Caveman Cloud control plane. Requires the policy:publish_s0_s1 scope. Exposed to autonomous agents as the set_capabilities action of the caveman_project_setup tool (write access). Turn optimizations on for the bound project: runtime mode, capability set, pixel density. Escalating to an S2/S3 capability is refused server-side unless the caller holds that permission, which a scoped agent connection does not.", "security": [ { "oauth2": [ "policy:publish_s0_s1" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:publish_s0_s1" ] } }, "/projects/{projectId}/cave-plan": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/cave-plan", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdCavePlan", "description": "GET /api/v1/projects/{projectId}/cave-plan on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the project_plan action of the caveman_plan tool (read access). The ranked list of where this project is wasting money and what would fix it, plus the Cave Score. This is the agent's work queue.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/compute-usage": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/compute-usage", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdComputeUsage", "description": "POST /api/v1/projects/{projectId}/compute-usage on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Writes into the compute metering ledger that billing reads. Only the worker and the human-facing plane may write it.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/continuous-improvement": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/continuous-improvement", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdContinuousImprovement", "description": "GET /api/v1/projects/{projectId}/continuous-improvement on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the latest_improvement_report action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/continuous-improvement/{reportId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/continuous-improvement/{reportId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdContinuousImprovementReportId", "description": "GET /api/v1/projects/{projectId}/continuous-improvement/{reportId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_improvement_report action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/continuous-improvement/{reportId}/replay": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/continuous-improvement/{reportId}/replay", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdContinuousImprovementReportIdReplay", "description": "POST /api/v1/projects/{projectId}/continuous-improvement/{reportId}/replay on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Replays recorded traffic against a provider, which spends real money and is gated on replay consent.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/continuous-improvement/{reportId}/replay/{jobId}/reconcile": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/continuous-improvement/{reportId}/replay/{jobId}/reconcile", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectContinuousImprovementReportReplayJobReconcile", "description": "POST /api/v1/projects/{projectId}/continuous-improvement/{reportId}/replay/{jobId}/reconcile on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Replays recorded traffic against a provider, which spends real money and is gated on replay consent.", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/github": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/github", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteProjectsProjectIdGithub", "description": "DELETE /api/v1/projects/{projectId}/github on the Caveman Cloud control plane. Requires the repo:connect scope. Not exposed to autonomous agents: Repository binding is an OAuth trust relationship between two accounts. The human owns both sides of it.", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] }, "get": { "summary": "GET /projects/{projectId}/github", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdGithub", "description": "GET /api/v1/projects/{projectId}/github on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Repository binding is an OAuth trust relationship between two accounts. The human owns both sides of it.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/github/connect-init": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/github/connect-init", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdGithubConnectInit", "description": "POST /api/v1/projects/{projectId}/github/connect-init on the Caveman Cloud control plane. Requires the repo:connect scope. Not exposed to autonomous agents: Repository binding is an OAuth trust relationship between two accounts. The human owns both sides of it.", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] } }, "/projects/{projectId}/github/select-repo": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/github/select-repo", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdGithubSelectRepo", "description": "POST /api/v1/projects/{projectId}/github/select-repo on the Caveman Cloud control plane. Requires the repo:connect scope. Not exposed to autonomous agents: Repository binding is an OAuth trust relationship between two accounts. The human owns both sides of it.", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] } }, "/projects/{projectId}/github/test-command": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /projects/{projectId}/github/test-command", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "putProjectsProjectIdGithubTestCommand", "description": "PUT /api/v1/projects/{projectId}/github/test-command on the Caveman Cloud control plane. Requires the repo:connect scope. Not exposed to autonomous agents: Sets the shell command the fix sandbox runs as the repo_tests oracle. A human confirming that line is what makes the oracle evidence rather than a stranger's shell; an agent that could set it would be choosing the gate it is judged by.", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] } }, "/projects/{projectId}/keys": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List project keys", "responses": { "200": { "description": "Key page without full secrets" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdKeys", "description": "GET /api/v1/projects/{projectId}/keys on the Caveman Cloud control plane. Requires the key:manage scope. Not exposed to autonomous agents: Mints or approves a credential. An agent must never be able to widen its own access — this is the escalation boundary that makes scoped agent connections meaningful.", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] }, "post": { "summary": "Create project key", "responses": { "201": { "description": "Key with one-time full_key" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdKeys", "description": "POST /api/v1/projects/{projectId}/keys on the Caveman Cloud control plane. Requires the key:manage scope. Not exposed to autonomous agents: Mints or approves a credential. An agent must never be able to widen its own access — this is the escalation boundary that makes scoped agent connections meaningful.", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] } }, "/projects/{projectId}/keys/{keyId}/revoke": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/keys/{keyId}/revoke", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdKeysKeyIdRevoke", "description": "POST /api/v1/projects/{projectId}/keys/{keyId}/revoke on the Caveman Cloud control plane. Requires the key:manage scope. Not exposed to autonomous agents: Mints or approves a credential. An agent must never be able to widen its own access — this is the escalation boundary that makes scoped agent connections meaningful.", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] } }, "/projects/{projectId}/keys/{keyId}/rotate": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/keys/{keyId}/rotate", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdKeysKeyIdRotate", "description": "POST /api/v1/projects/{projectId}/keys/{keyId}/rotate on the Caveman Cloud control plane. Requires the key:manage scope. Not exposed to autonomous agents: Mints or approves a credential. An agent must never be able to widen its own access — this is the escalation boundary that makes scoped agent connections meaningful.", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] } }, "/projects/{projectId}/mode": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/mode", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdMode", "description": "GET /api/v1/projects/{projectId}/mode on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the get_mode action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "post": { "summary": "POST /projects/{projectId}/mode", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdMode", "description": "POST /api/v1/projects/{projectId}/mode on the Caveman Cloud control plane. Requires the policy:publish_s0_s1 scope. Exposed to autonomous agents as the set_mode action of the caveman_project_setup tool (write access). Turn optimizations on for the bound project: runtime mode, capability set, pixel density. Escalating to an S2/S3 capability is refused server-side unless the caller holds that permission, which a scoped agent connection does not.", "security": [ { "oauth2": [ "policy:publish_s0_s1" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:publish_s0_s1" ] } }, "/projects/{projectId}/novelty": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/novelty", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdNovelty", "description": "GET /api/v1/projects/{projectId}/novelty on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_novelty action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/novelty/{noveltyId}/dismiss": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "noveltyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/novelty/{noveltyId}/dismiss", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdNoveltyNoveltyIdDismiss", "description": "POST /api/v1/projects/{projectId}/novelty/{noveltyId}/dismiss on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the dismiss_novelty action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/projects/{projectId}/novelty/{noveltyId}/promote": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "noveltyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/novelty/{noveltyId}/promote", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdNoveltyNoveltyIdPromote", "description": "POST /api/v1/projects/{projectId}/novelty/{noveltyId}/promote on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the promote_novelty action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/projects/{projectId}/outcomes": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/outcomes", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdOutcomes", "description": "GET /api/v1/projects/{projectId}/outcomes on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_outcomes action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/outcomes", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdOutcomes", "description": "POST /api/v1/projects/{projectId}/outcomes on the Caveman Cloud control plane. Requires the outcome:write scope. Exposed to autonomous agents as the record_outcome action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "outcome:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "outcome:write" ] } }, "/projects/{projectId}/pixel-density": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/pixel-density", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdPixelDensity", "description": "POST /api/v1/projects/{projectId}/pixel-density on the Caveman Cloud control plane. Requires the policy:publish_s0_s1 scope. Exposed to autonomous agents as the set_pixel_density action of the caveman_project_setup tool (write access). Turn optimizations on for the bound project: runtime mode, capability set, pixel density. Escalating to an S2/S3 capability is refused server-side unless the caller holds that permission, which a scoped agent connection does not.", "security": [ { "oauth2": [ "policy:publish_s0_s1" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:publish_s0_s1" ] } }, "/projects/{projectId}/policies": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/policies", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPolicies", "description": "GET /api/v1/projects/{projectId}/policies on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Policy documents are drafted through experiments and the Cave Plan, not edited directly by agents; direct drafting bypasses the evidence path that makes a change defensible.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] }, "post": { "summary": "POST /projects/{projectId}/policies", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdPolicies", "description": "POST /api/v1/projects/{projectId}/policies on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Policy documents are drafted through experiments and the Cave Plan, not edited directly by agents; direct drafting bypasses the evidence path that makes a change defensible.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/policies/{policyId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/policies/{policyId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPoliciesPolicyId", "description": "GET /api/v1/projects/{projectId}/policies/{policyId} on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Policy documents are drafted through experiments and the Cave Plan, not edited directly by agents; direct drafting bypasses the evidence path that makes a change defensible.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] }, "patch": { "summary": "PATCH /projects/{projectId}/policies/{policyId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchProjectsProjectIdPoliciesPolicyId", "description": "PATCH /api/v1/projects/{projectId}/policies/{policyId} on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Policy documents are drafted through experiments and the Cave Plan, not edited directly by agents; direct drafting bypasses the evidence path that makes a change defensible.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/policies/{policyId}/publish": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/policies/{policyId}/publish", "requestBody": { "required": false, "description": "Optional. Only carries the operator's acknowledgement of what this publish would switch off; an empty body publishes when nothing would be deactivated.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "confirm_deactivations": { "type": "array", "description": "Entries from a prior 409 details.deactivations, copied verbatim. Confirmation is per entry: acknowledging one never waives another.", "items": { "type": "string" } } } } } } }, "responses": { "409": { "description": "cave_policy_deactivates — the draft would switch off an optimizer that is active right now (approved-canary evidence, or a byte-safe activation optimizer the current mode still runs) or walk the runtime mode down the ladder, and the caller did not confirm it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string", "const": "cave_policy_deactivates" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "deactivations": { "type": "array", "description": "Every unconfirmed entry: an optimizer id, or \"runtime_mode:->\". Re-send in confirm_deactivations to proceed.", "items": { "type": "string" } } } }, "request_id": { "type": "string" } } } } } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdPoliciesPolicyIdPublish", "description": "POST /api/v1/projects/{projectId}/policies/{policyId}/publish on the Caveman Cloud control plane. Requires the policy:publish_s2_s3 scope. Not exposed to autonomous agents: Publishes or rolls back live traffic policy at S2/S3. Agents draft and experiment; a human promotes.", "security": [ { "oauth2": [ "policy:publish_s2_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:publish_s2_s3" ] } }, "/projects/{projectId}/policies/{policyId}/rollback": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/policies/{policyId}/rollback", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdPoliciesPolicyIdRollback", "description": "POST /api/v1/projects/{projectId}/policies/{policyId}/rollback on the Caveman Cloud control plane. Requires the policy:publish_s2_s3 scope. Not exposed to autonomous agents: Publishes or rolls back live traffic policy at S2/S3. Agents draft and experiment; a human promotes.", "security": [ { "oauth2": [ "policy:publish_s2_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:publish_s2_s3" ] } }, "/projects/{projectId}/policies/{policyId}/validate": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/policies/{policyId}/validate", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdPoliciesPolicyIdValidate", "description": "POST /api/v1/projects/{projectId}/policies/{policyId}/validate on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Policy documents are drafted through experiments and the Cave Plan, not edited directly by agents; direct drafting bypasses the evidence path that makes a change defensible.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/policies/current": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/policies/current", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPoliciesCurrent", "description": "GET /api/v1/projects/{projectId}/policies/current on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the current action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/projects/{projectId}/policy-delivery": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/policy-delivery", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPolicyDelivery", "description": "GET /api/v1/projects/{projectId}/policy-delivery on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the delivery_status action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/projects/{projectId}/population-savings": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/population-savings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPopulationSavings", "description": "GET /api/v1/projects/{projectId}/population-savings on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the population_savings action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/projects/{projectId}/practice-evidence": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/practice-evidence", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPracticeEvidence", "description": "GET /api/v1/projects/{projectId}/practice-evidence on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the practice_evidence action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/practice-rollup-consent": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /projects/{projectId}/practice-rollup-consent", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchProjectsProjectIdPracticeRollupConsent", "description": "PATCH /api/v1/projects/{projectId}/practice-rollup-consent on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/projects/{projectId}/prompt-experiments": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/prompt-experiments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPromptExperiments", "description": "GET /api/v1/projects/{projectId}/prompt-experiments on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the list_experiments action of the caveman_prompts tool (read access). Registered prompts, their versions, and prompt experiments.", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] }, "post": { "summary": "POST /projects/{projectId}/prompt-experiments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdPromptExperiments", "description": "POST /api/v1/projects/{projectId}/prompt-experiments on the Caveman Cloud control plane. Requires the prompt:write scope. Exposed to autonomous agents as the create_experiment action of the caveman_prompts_write tool (write access). Register prompts extracted from a repository, add versions, pin a version, and manage prompt experiments.", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] } }, "/projects/{projectId}/prompt-experiments/{experimentId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/prompt-experiments/{experimentId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteProjectsProjectIdPromptExperimentsExperimentId", "description": "DELETE /api/v1/projects/{projectId}/prompt-experiments/{experimentId} on the Caveman Cloud control plane. Requires the prompt:write scope. Exposed to autonomous agents as the delete_experiment action of the caveman_prompts_write tool (write access). Register prompts extracted from a repository, add versions, pin a version, and manage prompt experiments.", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] }, "get": { "summary": "GET /projects/{projectId}/prompt-experiments/{experimentId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPromptExperimentsExperimentId", "description": "GET /api/v1/projects/{projectId}/prompt-experiments/{experimentId} on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the get_experiment action of the caveman_prompts tool (read access). Registered prompts, their versions, and prompt experiments.", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] }, "patch": { "summary": "PATCH /projects/{projectId}/prompt-experiments/{experimentId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchProjectsProjectIdPromptExperimentsExperimentId", "description": "PATCH /api/v1/projects/{projectId}/prompt-experiments/{experimentId} on the Caveman Cloud control plane. Requires the prompt:write scope. Exposed to autonomous agents as the update_experiment action of the caveman_prompts_write tool (write access). Register prompts extracted from a repository, add versions, pin a version, and manage prompt experiments.", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] } }, "/projects/{projectId}/prompts": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/prompts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPrompts", "description": "GET /api/v1/projects/{projectId}/prompts on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the list action of the caveman_prompts tool (read access). Registered prompts, their versions, and prompt experiments.", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] }, "post": { "summary": "POST /projects/{projectId}/prompts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdPrompts", "description": "POST /api/v1/projects/{projectId}/prompts on the Caveman Cloud control plane. Requires the prompt:write scope. Exposed to autonomous agents as the create action of the caveman_prompts_write tool (write access). Register prompts extracted from a repository, add versions, pin a version, and manage prompt experiments.", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] } }, "/projects/{projectId}/prompts/{promptId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/prompts/{promptId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteProjectsProjectIdPromptsPromptId", "description": "DELETE /api/v1/projects/{projectId}/prompts/{promptId} on the Caveman Cloud control plane. Requires the prompt:write scope. Exposed to autonomous agents as the delete action of the caveman_prompts_write tool (write access). Register prompts extracted from a repository, add versions, pin a version, and manage prompt experiments.", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] }, "get": { "summary": "GET /projects/{projectId}/prompts/{promptId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPromptsPromptId", "description": "GET /api/v1/projects/{projectId}/prompts/{promptId} on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the get action of the caveman_prompts tool (read access). Registered prompts, their versions, and prompt experiments.", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] } }, "/projects/{projectId}/prompts/{promptId}/pin": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/prompts/{promptId}/pin", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdPromptsPromptIdPin", "description": "POST /api/v1/projects/{projectId}/prompts/{promptId}/pin on the Caveman Cloud control plane. Requires the prompt:write scope. Exposed to autonomous agents as the pin_version action of the caveman_prompts_write tool (write access). Register prompts extracted from a repository, add versions, pin a version, and manage prompt experiments.", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] } }, "/projects/{projectId}/prompts/{promptId}/versions": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/prompts/{promptId}/versions", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdPromptsPromptIdVersions", "description": "POST /api/v1/projects/{projectId}/prompts/{promptId}/versions on the Caveman Cloud control plane. Requires the prompt:write scope. Exposed to autonomous agents as the add_version action of the caveman_prompts_write tool (write access). Register prompts extracted from a repository, add versions, pin a version, and manage prompt experiments.", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] } }, "/projects/{projectId}/prompts/{promptId}/versions/{version}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/prompts/{promptId}/versions/{version}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdPromptsPromptIdVersionsVersion", "description": "GET /api/v1/projects/{projectId}/prompts/{promptId}/versions/{version} on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the get_version action of the caveman_prompts tool (read access). Registered prompts, their versions, and prompt experiments.", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] } }, "/projects/{projectId}/providers": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List provider connections", "responses": { "200": { "description": "Provider page" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdProviders", "description": "GET /api/v1/projects/{projectId}/providers on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the list_providers action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "post": { "summary": "Create provider connection", "responses": { "201": { "description": "Provider created" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdProviders", "description": "POST /api/v1/projects/{projectId}/providers on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Handles provider credentials or their verification. Agents route traffic; they never hold or rotate the secrets that pay for it.", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/projects/{projectId}/providers/{connectionId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/providers/{connectionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteProjectsProjectIdProvidersConnectionId", "description": "DELETE /api/v1/projects/{projectId}/providers/{connectionId} on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Handles provider credentials or their verification. Agents route traffic; they never hold or rotate the secrets that pay for it.", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/projects/{projectId}/providers/{connectionId}/rotate-secret": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/providers/{connectionId}/rotate-secret", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdProvidersConnectionIdRotateSecret", "description": "POST /api/v1/projects/{projectId}/providers/{connectionId}/rotate-secret on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Handles provider credentials or their verification. Agents route traffic; they never hold or rotate the secrets that pay for it.", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/projects/{projectId}/providers/{connectionId}/verify": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/providers/{connectionId}/verify", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdProvidersConnectionIdVerify", "description": "POST /api/v1/projects/{projectId}/providers/{connectionId}/verify on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Handles provider credentials or their verification. Agents route traffic; they never hold or rotate the secrets that pay for it.", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/projects/{projectId}/replay-consent": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /projects/{projectId}/replay-consent", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchProjectsProjectIdReplayConsent", "description": "PATCH /api/v1/projects/{projectId}/replay-consent on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Records consent or a data-subject decision on behalf of the organization. Legal effect, so a human must be the actor.", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/projects/{projectId}/retention": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/retention", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdRetention", "description": "GET /api/v1/projects/{projectId}/retention on the Caveman Cloud control plane. Requires the settings:read scope. Exposed to autonomous agents as the retention action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/projects/{projectId}/sample-data": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/sample-data", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postProjectsProjectIdSampleData", "description": "POST /api/v1/projects/{projectId}/sample-data on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Writes sample rows a human could mistake for real evidence. Sample data is an explicit human choice, never something an agent turns on while setting a project up.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/themes": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/themes", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdThemes", "description": "GET /api/v1/projects/{projectId}/themes on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_themes action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/themes/{themeId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "themeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/themes/{themeId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdThemesThemeId", "description": "GET /api/v1/projects/{projectId}/themes/{themeId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_theme action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/workflows/{workflowId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/workflows/{workflowId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getProjectsProjectIdWorkflowsWorkflowId", "description": "GET /api/v1/projects/{projectId}/workflows/{workflowId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get action of the caveman_workflows tool (read access). Agents, workflows, and the observed workflow fingerprint registry that traffic is attributed to.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /projects/{projectId}/workflows/{workflowId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchProjectsProjectIdWorkflowsWorkflowId", "description": "PATCH /api/v1/projects/{projectId}/workflows/{workflowId} on the Caveman Cloud control plane. Requires the policy:draft scope. Exposed to autonomous agents as the update action of the caveman_workflows_write tool (write access). Create and update the agents and workflows that traffic is labelled against. This is what makes per-workflow cost attribution work.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/providers/catalog": { "get": { "summary": "GET /providers/catalog", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [], "operationId": "getProvidersCatalog", "description": "GET /api/v1/providers/catalog on the Caveman Cloud control plane. Unauthenticated, or authenticated by a request signature rather than a session. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/quality-monitors": { "get": { "summary": "GET /quality-monitors", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getQualityMonitors", "description": "GET /api/v1/quality-monitors on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list action of the caveman_monitors tool (read access). Quality monitors and their verdicts.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /quality-monitors", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postQualityMonitors", "description": "POST /api/v1/quality-monitors on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the create action of the caveman_monitors_write tool (write access). Create, replace, pause and archive the quality monitors that guard optimizations.", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/quality-monitors/{monitorId}": { "parameters": [ { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /quality-monitors/{monitorId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteQualityMonitorsMonitorId", "description": "DELETE /api/v1/quality-monitors/{monitorId} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the archive action of the caveman_monitors_write tool (write access). Create, replace, pause and archive the quality monitors that guard optimizations.", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] }, "get": { "summary": "GET /quality-monitors/{monitorId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getQualityMonitorsMonitorId", "description": "GET /api/v1/quality-monitors/{monitorId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get action of the caveman_monitors tool (read access). Quality monitors and their verdicts.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "put": { "summary": "PUT /quality-monitors/{monitorId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "putQualityMonitorsMonitorId", "description": "PUT /api/v1/quality-monitors/{monitorId} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the update action of the caveman_monitors_write tool (write access). Create, replace, pause and archive the quality monitors that guard optimizations.", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/quality-monitors/{monitorId}/results": { "parameters": [ { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /quality-monitors/{monitorId}/results", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getQualityMonitorsMonitorIdResults", "description": "GET /api/v1/quality-monitors/{monitorId}/results on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the results action of the caveman_monitors tool (read access). Quality monitors and their verdicts.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/quality-monitors/{monitorId}/status": { "parameters": [ { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /quality-monitors/{monitorId}/status", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postQualityMonitorsMonitorIdStatus", "description": "POST /api/v1/quality-monitors/{monitorId}/status on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the set_status action of the caveman_monitors_write tool (write access). Create, replace, pause and archive the quality monitors that guard optimizations.", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/reports/agents": { "get": { "summary": "GET /reports/agents", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsAgents", "description": "GET /api/v1/reports/agents on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the agents action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/cache": { "get": { "summary": "GET /reports/cache", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsCache", "description": "GET /api/v1/reports/cache on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the cache action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/cave-score": { "get": { "summary": "Cave Score", "responses": { "200": { "description": "Deterministic score and penalties" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsCaveScore", "description": "GET /api/v1/reports/cave-score on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the score action of the caveman_plan tool (read access). The ranked list of where this project is wasting money and what would fix it, plus the Cave Score. This is the agent's work queue.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/compression": { "get": { "summary": "GET /reports/compression", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsCompression", "description": "GET /api/v1/reports/compression on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the compression action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/costs": { "get": { "summary": "GET /reports/costs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsCosts", "description": "GET /api/v1/reports/costs on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the costs action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/delivery": { "get": { "summary": "GET /reports/delivery", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsDelivery", "description": "GET /api/v1/reports/delivery on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the delivery action of the caveman_people tool (read access). Org members, seats, and per-person spend and delivery attribution. Read-only — an agent never creates or changes an identity.", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/developers": { "get": { "summary": "GET /reports/developers", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsDevelopers", "description": "GET /api/v1/reports/developers on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the developers action of the caveman_people tool (read access). Org members, seats, and per-person spend and delivery attribution. Read-only — an agent never creates or changes an identity.", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/fleet": { "get": { "summary": "GET /reports/fleet", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsFleet", "description": "GET /api/v1/reports/fleet on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the fleet action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/reports/members": { "get": { "summary": "GET /reports/members", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsMembers", "description": "GET /api/v1/reports/members on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the member_spend action of the caveman_people tool (read access). Org members, seats, and per-person spend and delivery attribution. Read-only — an agent never creates or changes an identity.", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/models": { "get": { "summary": "GET /reports/models", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsModels", "description": "GET /api/v1/reports/models on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the models action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/overview": { "get": { "summary": "Overview metrics", "responses": { "200": { "description": "Measured, projected, and verified metrics" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsOverview", "description": "GET /api/v1/reports/overview on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the overview action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/routes": { "get": { "summary": "GET /reports/routes", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsRoutes", "description": "GET /api/v1/reports/routes on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the routes action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/spend-breakdown": { "get": { "summary": "GET /reports/spend-breakdown", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsSpendBreakdown", "description": "GET /api/v1/reports/spend-breakdown on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the spend_breakdown action of the caveman_people tool (read access). Org members, seats, and per-person spend and delivery attribution. Read-only — an agent never creates or changes an identity.", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/traffic-shape": { "get": { "summary": "GET /reports/traffic-shape", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsTrafficShape", "description": "GET /api/v1/reports/traffic-shape on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the traffic_shape action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/usage": { "get": { "summary": "GET /reports/usage", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsUsage", "description": "GET /api/v1/reports/usage on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the usage action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/verified-savings": { "get": { "summary": "GET /reports/verified-savings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsVerifiedSavings", "description": "GET /api/v1/reports/verified-savings on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the verified_savings action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/why": { "get": { "summary": "GET /reports/why", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsWhy", "description": "GET /api/v1/reports/why on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the why action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/workflows": { "get": { "summary": "GET /reports/workflows", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsWorkflows", "description": "GET /api/v1/reports/workflows on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the workflows action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/reports/workflows/{workflowSlug}": { "parameters": [ { "name": "workflowSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /reports/workflows/{workflowSlug}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsWorkflowsWorkflowSlug", "description": "GET /api/v1/reports/workflows/{workflowSlug} on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the workflow_detail action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/reports/wrap-savings": { "get": { "summary": "GET /reports/wrap-savings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getReportsWrapSavings", "description": "GET /api/v1/reports/wrap-savings on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the wrap_savings action of the caveman_reports tool (read access). Spend, usage, compression, routing, cache, models, traffic shape and verified-savings rollups for the bound project over a time window.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/routes/preview": { "post": { "summary": "POST /routes/preview", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postRoutesPreview", "description": "POST /api/v1/routes/preview on the Caveman Cloud control plane. Requires the policy:draft scope. Exposed to autonomous agents as the preview_routing action of the caveman_project_setup tool (write access). Turn optimizations on for the bound project: runtime mode, capability set, pixel density. Escalating to an S2/S3 capability is refused server-side unless the caller holds that permission, which a scoped agent connection does not.", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/surveyor-findings": { "get": { "summary": "GET /surveyor-findings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getSurveyorFindings", "description": "GET /api/v1/surveyor-findings on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_findings action of the caveman_fixes tool (read access). Opportunities, optimization proposals, continuous-improvement reports, novelty signals, themes and autopilot moves — everything describing a fix that has not landed yet.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /surveyor-findings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postSurveyorFindings", "description": "POST /api/v1/surveyor-findings on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the submit_finding action of the caveman_fixes_write tool (write access). Act on a fix: dismiss it, mark it implemented, promote it to an experiment, or draft an optimization proposal.", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/system/provider-capabilities": { "get": { "summary": "GET /system/provider-capabilities", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getSystemProviderCapabilities", "description": "GET /api/v1/system/provider-capabilities on the Caveman Cloud control plane. Requires the settings:read scope. Exposed to autonomous agents as the provider_capabilities action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/system/status": { "get": { "summary": "System health", "responses": { "200": { "description": "System status" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getSystemStatus", "description": "GET /api/v1/system/status on the Caveman Cloud control plane. Requires the settings:read scope. Exposed to autonomous agents as the system_status action of the caveman_context tool (read access). Who am I, which project am I bound to, what is turned on, and which providers and models are wired. Start here — every other tool assumes this context.", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/system/version": { "get": { "summary": "GET /system/version", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [], "operationId": "getSystemVersion", "description": "GET /api/v1/system/version on the Caveman Cloud control plane. Unauthenticated, or authenticated by a request signature rather than a session. Not exposed to autonomous agents: Not RBAC-guarded — part of the authentication or webhook plane. Agents authenticate through a scoped control-plane session and never touch these directly." } }, "/tool-catalogs": { "get": { "summary": "GET /tool-catalogs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getToolCatalogs", "description": "GET /api/v1/tool-catalogs on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Tool catalogs are a data-plane SDK concern, not an operator management surface.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces": { "get": { "summary": "List traces", "responses": { "200": { "description": "Trace page" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getTraces", "description": "GET /api/v1/traces on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list action of the caveman_traces tool (read access). Search and inspect individual LLM requests as metadata and span trees. Raw request and response bodies are deliberately not reachable from any agent tool.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/{traceId}": { "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /traces/{traceId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getTracesTraceId", "description": "GET /api/v1/traces/{traceId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get action of the caveman_traces tool (read access). Search and inspect individual LLM requests as metadata and span trees. Raw request and response bodies are deliberately not reachable from any agent tool.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/{traceId}/payloads/{payloadType}": { "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "payloadType", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read a captured trace payload", "responses": { "200": { "description": "Captured payload bytes", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid trace, payload type, or request_id" }, "404": { "description": "Trace or captured payload unavailable; response includes a machine-readable reason" }, "409": { "description": "Trace contains multiple requests and request_id was omitted" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "description": "Returns one tenant-scoped, retention-gated captured request, response, or compressed-request body. A trace with more than one request requires request_id so metadata and bytes stay bound to the same request.", "parameters": [ { "name": "request_id", "in": "query", "required": false, "description": "Request UUID owning the payload; required when the trace contains multiple requests.", "schema": { "type": "string", "format": "uuid" } } ], "operationId": "getTracesTraceIdPayloadsPayloadType", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/traces/{traceId}/spans": { "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /traces/{traceId}/spans", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getTracesTraceIdSpans", "description": "GET /api/v1/traces/{traceId}/spans on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the spans action of the caveman_traces tool (read access). Search and inspect individual LLM requests as metadata and span trees. Raw request and response bodies are deliberately not reachable from any agent tool.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/{traceId}/timeline": { "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /traces/{traceId}/timeline", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getTracesTraceIdTimeline", "description": "GET /api/v1/traces/{traceId}/timeline on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the timeline action of the caveman_traces tool (read access). Search and inspect individual LLM requests as metadata and span trees. Raw request and response bodies are deliberately not reachable from any agent tool.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/export": { "post": { "summary": "POST /traces/export", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postTracesExport", "description": "POST /api/v1/traces/export on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Deletes, exports or changes the retention of tenant data. Irreversible or data-egress; requires a human actor in the audit trail.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/search": { "post": { "summary": "POST /traces/search", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postTracesSearch", "description": "POST /api/v1/traces/search on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the search action of the caveman_traces tool (read access). Search and inspect individual LLM requests as metadata and span trees. Raw request and response bodies are deliberately not reachable from any agent tool.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/webhooks": { "get": { "summary": "GET /webhooks", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getWebhooks", "description": "GET /api/v1/webhooks on the Caveman Cloud control plane. Requires the settings:read scope. Not exposed to autonomous agents: Webhook targets are an egress channel; an agent that could add one could exfiltrate tenant events.", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] }, "post": { "summary": "POST /webhooks", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postWebhooks", "description": "POST /api/v1/webhooks on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Webhook targets are an egress channel; an agent that could add one could exfiltrate tenant events.", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/webhooks/{webhookId}": { "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /webhooks/{webhookId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "deleteWebhooksWebhookId", "description": "DELETE /api/v1/webhooks/{webhookId} on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Webhook targets are an egress channel; an agent that could add one could exfiltrate tenant events.", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/webhooks/{webhookId}/test": { "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /webhooks/{webhookId}/test", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "postWebhooksWebhookIdTest", "description": "POST /api/v1/webhooks/{webhookId}/test on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Webhook targets are an egress channel; an agent that could add one could exfiltrate tenant events.", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/workflow-fingerprints": { "get": { "summary": "GET /workflow-fingerprints", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "getWorkflowFingerprints", "description": "GET /api/v1/workflow-fingerprints on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_fingerprints action of the caveman_workflows tool (read access). Agents, workflows, and the observed workflow fingerprint registry that traffic is attributed to.", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/workflow-fingerprints/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /workflow-fingerprints/{id}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "patchWorkflowFingerprintsId", "description": "PATCH /api/v1/workflow-fingerprints/{id} on the Caveman Cloud control plane. Requires the experiment:approve_s3 scope. Not exposed to autonomous agents: Publishes or rolls back live traffic policy at S2/S3. Agents draft and experiment; a human promotes.", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } }, "/workflow-fingerprints/{id}/autopilot": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /workflow-fingerprints/{id}/autopilot", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "operationId": "putWorkflowFingerprintsIdAutopilot", "description": "PUT /api/v1/workflow-fingerprints/{id}/autopilot on the Caveman Cloud control plane. Requires the experiment:approve_s3 scope. Not exposed to autonomous agents: Publishes or rolls back live traffic policy at S2/S3. Agents draft and experiment; a human promotes.", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "The control-plane access token, scoped. Obtained through the RFC 8628 device-authorization grant that `caveman login` and the MCP server use; presented as `Authorization: Bearer `.", "flows": { "x-deviceAuthorization": { "deviceAuthorizationUrl": "https://api.caveman.so/api/v1/auth/device/code", "tokenUrl": "https://api.caveman.so/api/v1/auth/device/token", "scopes": { "org:read": "Read the organization, its projects, and the caller's own membership.", "org:update": "Change organization settings.", "member:manage": "Invite, change, and remove organization members.", "sso:manage": "Configure SAML and OIDC identity providers.", "provider:manage": "Add, verify, and remove upstream model-provider credentials.", "key:manage": "Create, bind, and revoke gateway keys for any member.", "key:self": "Create or rotate the caller's own personal gateway key.", "trace:read_metadata": "Read request metadata: models, tokens, latency, cost, tags. Never payload bytes.", "payload:read": "Read captured request and response payload bytes, subject to retention.", "policy:draft": "Draft optimization policies without publishing them to live traffic.", "policy:publish_s0_s1": "Publish byte-safe (S0/S1) policy changes to live traffic.", "policy:publish_s2_s3": "Publish byte-visible (S2/S3) policy changes to live traffic.", "experiment:run": "Start, stop, and read optimization experiments.", "experiment:approve_s3": "Approve an S3 (byte-visible, model-visible) experiment.", "autopilot:manage": "Pause or resume the organization-wide autopilot loop.", "proposal:draft": "Draft improvement proposals from observed waste.", "repo:connect": "Bind a source repository so proposals can be opened as pull requests.", "billing:read": "Read plan, invoices, quotas, and subscription state.", "billing:write": "Change plan, payment method, and subscription state.", "receipt:ingest": "Ingest signed savings receipts into the ledger.", "org:delete": "Delete the organization and its data.", "settings:read": "Read project and organization settings.", "opportunity:write": "Create, rank, and dismiss efficiency opportunities.", "outcome:write": "Ingest Outcome Contract evidence about what happened after a run.", "eval:write": "Create eval suites, replace their cases, and ingest eval evidence.", "prompt:read": "Read prompts and prompt experiments.", "prompt:write": "Create and change prompts and prompt experiments.", "auditlog:read": "Read the tenant audit trail.", "artifact:read_metadata": "List artifacts and read their metadata.", "artifact:delete": "Delete artifacts." } } }, "x-authorization-server-metadata": "https://caveman.so/.well-known/oauth-authorization-server" }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "The same access token without a declared scope list. Prefer the oauth2 scheme when you want least privilege." }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "cave_access", "description": "HttpOnly cave_access cookie. Cookie-authenticated mutations also require the x-cave-csrf: ui header." } }, "schemas": { "OrganizationMembership": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "name", "slug", "role" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "engineer", "viewer", "billing" ] } } }, "AuthResponse": { "type": "object", "additionalProperties": false, "required": [ "user" ], "properties": { "user": { "type": "object", "additionalProperties": false, "required": [ "id", "email", "organization_id", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "admin", "engineer", "viewer", "billing" ] } } }, "access_token": { "type": "string", "description": "Returned only to non-browser bearer clients; browser clients receive an HttpOnly cookie." }, "refresh_token": { "type": "string", "description": "Returned only to non-browser bearer clients; browser clients receive an HttpOnly cookie." } } }, "AgentBuildRegistration": { "type": "object", "additionalProperties": false, "required": [ "agent_slug", "build_sha256", "plan_sha256", "source_sha256", "eval_suite_sha256", "catalog_sha256", "transform_registry_sha256", "harness", "adapter_version", "upstream_version", "runtime_version", "evidence_status", "evidence_basis", "lock" ], "properties": { "agent_slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,95}$" }, "build_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "plan_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "source_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "eval_suite_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "catalog_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "transform_registry_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "harness": { "type": "string", "enum": [ "pi", "vercel-ai-sdk", "eve", "mastra" ], "description": "Cave Build v2 accepts only Pi. Cave Build v3 accepts exact native Pi behavioral builds plus baseline-equivalent generic Pi, Vercel AI SDK, Eve, and Mastra envelopes. Claude v3 fails closed until executable parity exists." }, "adapter_version": { "type": "string", "minLength": 1, "maxLength": 128 }, "upstream_version": { "type": "string", "minLength": 1, "maxLength": 128 }, "runtime_version": { "type": "string", "minLength": 1, "maxLength": 128 }, "evidence_status": { "const": "locked" }, "evidence_basis": { "const": "inferred" }, "lock": { "type": "object", "description": "Immutable Cave Build v2 or v3. V2 is Pi-only. V3 permits behavioral lowering only for the exact owned native Pi contract; generic targets remain baseline-equivalent. Runtime failure policy is abort-only. Server recomputes canonical digests, target identity, capabilities, plan-diff passes, validation economics, and policy_sha256." } } }, "AgentBuild": { "type": "object", "additionalProperties": false, "required": [ "agent_slug", "build_sha256", "plan_sha256", "source_sha256", "eval_suite_sha256", "catalog_sha256", "transform_registry_sha256", "harness", "adapter_version", "upstream_version", "runtime_version", "evidence_status", "evidence_basis", "lock", "id", "project_id", "registered_by", "created_at" ], "properties": { "agent_slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,95}$" }, "build_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "plan_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "source_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "eval_suite_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "catalog_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "transform_registry_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "harness": { "type": "string", "enum": [ "pi", "vercel-ai-sdk", "eve", "mastra" ], "description": "Cave Build v2 accepts only Pi. Cave Build v3 accepts exact native Pi behavioral builds plus baseline-equivalent generic Pi, Vercel AI SDK, Eve, and Mastra envelopes. Claude v3 fails closed until executable parity exists." }, "adapter_version": { "type": "string", "minLength": 1, "maxLength": 128 }, "upstream_version": { "type": "string", "minLength": 1, "maxLength": 128 }, "runtime_version": { "type": "string", "minLength": 1, "maxLength": 128 }, "evidence_status": { "const": "locked" }, "evidence_basis": { "const": "inferred" }, "lock": { "type": "object", "description": "Immutable Cave Build v2 or v3. V2 is Pi-only. V3 permits behavioral lowering only for the exact owned native Pi contract; generic targets remain baseline-equivalent. Runtime failure policy is abort-only. Server recomputes canonical digests, target identity, capabilities, plan-diff passes, validation economics, and policy_sha256." }, "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "registered_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "AgentBuildEvidence": { "type": "object", "additionalProperties": false, "required": [ "build_sha256", "plan_sha256", "registered", "requests", "catalog_priced_complete_requests", "context_tokens", "transform_ids", "transform_trace", "catalog_cost_usd", "evidence_basis", "attribution_basis", "verified_savings_usd" ], "properties": { "build_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "plan_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "registered": { "type": "boolean" }, "requests": { "type": "integer", "minimum": 0 }, "catalog_priced_complete_requests": { "type": "integer", "minimum": 0, "description": "Requests with provider-complete usage and a public-catalog price. catalog_cost_usd covers only this subset." }, "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "context_tokens": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "transform_ids": { "type": "array", "items": { "type": "string" } }, "transform_trace": { "type": "array", "items": { "type": "string" } }, "catalog_cost_usd": { "type": "number", "minimum": 0 }, "evidence_basis": { "const": "observed_traffic_client_declared_identity" }, "attribution_basis": { "const": "client_declared_build_plan_context" }, "verified_savings_usd": { "const": 0 } } }, "ErrorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "const": "cave_gateway_error" }, "code": { "type": "string", "pattern": "^cave_[a-z0-9_]+$", "description": "Stable machine-readable failure code. Match on this, never on message." }, "message": { "type": "string", "description": "Human-readable summary. Server-side failures are redacted to a fixed string." }, "details": { "type": "object", "additionalProperties": true, "description": "Failure-specific fields the caller can act on. Always absent on 5xx." }, "request_id": { "type": "string", "description": "Echoed in the x-cave-request-id response header. Quote it in support requests." }, "trace_id": { "type": "string" } } } } } }, "responses": { "Error": { "description": "Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "security": [ { "oauth2": [] }, { "bearerAuth": [] }, { "cookieAuth": [] } ], "x-caveman-excluded-runtime-routes": [ { "method": "POST", "path": "/jobs", "reason": "router explicitly marks operation unsupported" }, { "method": "POST", "path": "/jobs/{jobId}/cancel", "reason": "router explicitly marks operation unsupported" }, { "method": "DELETE", "path": "/projects/{projectId}", "reason": "router explicitly marks operation unsupported" }, { "method": "PATCH", "path": "/projects/{projectId}/retention", "reason": "router explicitly marks operation unsupported" }, { "method": "POST", "path": "/tool-catalogs", "reason": "router explicitly marks operation unsupported" } ], "externalDocs": { "description": "Agent-facing index", "url": "https://caveman.so/llms.txt" } }