{ "paths": { "/admin/broker/deals": { "post": { "summary": "POST /admin/broker/deals", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postAdminBrokerDeals", "description": "POST /api/v1/admin/broker/deals on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. Not exposed to autonomous agents: Private platform operator token changes what Caveman Code sells, its prices and the credits it grants across organisations; tenant agents cannot sell, price or grant platform credit.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/admin/broker/deals/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /admin/broker/deals/{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" } }, "operationId": "deleteAdminBrokerDealsId", "description": "DELETE /api/v1/admin/broker/deals/{id} on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. Not exposed to autonomous agents: Private platform operator token changes what Caveman Code sells, its prices and the credits it grants across organisations; tenant agents cannot sell, price or grant platform credit.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/admin/broker/grants": { "post": { "summary": "POST /admin/broker/grants", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postAdminBrokerGrants", "description": "POST /api/v1/admin/broker/grants on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. Not exposed to autonomous agents: Private platform operator token changes what Caveman Code sells, its prices and the credits it grants across organisations; tenant agents cannot sell, price or grant platform credit.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/admin/broker/margin": { "get": { "summary": "GET /admin/broker/margin", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getAdminBrokerMargin", "description": "GET /api/v1/admin/broker/margin on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. Not exposed to autonomous agents: Private platform operator token changes what Caveman Code sells, its prices and the credits it grants across organisations; tenant agents cannot sell, price or grant platform credit.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/admin/broker/offers": { "delete": { "summary": "DELETE /admin/broker/offers", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteAdminBrokerOffers", "description": "DELETE /api/v1/admin/broker/offers on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. Not exposed to autonomous agents: Private platform operator token changes what Caveman Code sells, its prices and the credits it grants across organisations; tenant agents cannot sell, price or grant platform credit.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] }, "get": { "summary": "GET /admin/broker/offers", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getAdminBrokerOffers", "description": "GET /api/v1/admin/broker/offers on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. Not exposed to autonomous agents: Private platform operator token changes what Caveman Code sells, its prices and the credits it grants across organisations; tenant agents cannot sell, price or grant platform credit.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] }, "put": { "summary": "PUT /admin/broker/offers", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putAdminBrokerOffers", "description": "PUT /api/v1/admin/broker/offers on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. Not exposed to autonomous agents: Private platform operator token changes what Caveman Code sells, its prices and the credits it grants across organisations; tenant agents cannot sell, price or grant platform credit.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/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" } }, "operationId": "getAdminClickhouseUsage", "description": "GET /api/v1/admin/clickhouse-usage on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/admin/hosted-ai/users/{userId}/limit": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "Set or restore a user's monthly included AI limit", "responses": { "204": { "description": "Allowance override recorded, or plan default restored." }, "400": { "description": "Invalid user or allowance." }, "401": { "description": "Platform operator authentication required." }, "403": { "description": "Request must originate from the private operator network." }, "429": { "description": "Operator request rate limit reached." }, "503": { "description": "Allowance accounting unavailable." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "PUT /api/v1/admin/hosted-ai/users/{userId}/limit on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. Not exposed to autonomous agents: Private platform operator token changes Caveman-funded allowances across organisations; tenant agents cannot grant platform credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "limit_micros" ], "properties": { "limit_micros": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10000000000000, "description": "Monthly USD list-price allowance in millionths of a dollar." } } } } } }, "operationId": "putAdminHostedAiUsersUserIdLimit", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/admin/model-catalog/decisions": { "post": { "summary": "POST /admin/model-catalog/decisions", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postAdminModelCatalogDecisions", "description": "POST /api/v1/admin/model-catalog/decisions on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/admin/model-catalog/reviews": { "get": { "summary": "GET /admin/model-catalog/reviews", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getAdminModelCatalogReviews", "description": "GET /api/v1/admin/model-catalog/reviews on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/admin/model-catalog/reviews/{reviewId}/approve": { "parameters": [ { "name": "reviewId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /admin/model-catalog/reviews/{reviewId}/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" } }, "operationId": "postAdminModelCatalogReviewsReviewIdApprove", "description": "POST /api/v1/admin/model-catalog/reviews/{reviewId}/approve on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/admin/model-catalog/reviews/{reviewId}/reject": { "parameters": [ { "name": "reviewId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /admin/model-catalog/reviews/{reviewId}/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" } }, "operationId": "postAdminModelCatalogReviewsReviewIdReject", "description": "POST /api/v1/admin/model-catalog/reviews/{reviewId}/reject on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/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" } }, "operationId": "postAdminOrgs", "description": "POST /api/v1/admin/orgs on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/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" } }, "operationId": "patchAdminOrgsOrgIdPlan", "description": "PATCH /api/v1/admin/orgs/{orgId}/plan on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "artifact:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "artifact:delete" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "artifact:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "audit.list", "x-caveman-operation-contract": "96ea9d2a4e7ed826c54366f912dabeb37465ec5f0655bbdd2b83eaaff171a3bd", "parameters": [ { "name": "action", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "auditlog:read" ] } }, "/audit-logs/export": { "get": { "summary": "GET /audit-logs/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" } }, "operationId": "getAuditLogsExport", "description": "GET /api/v1/audit-logs/export on the Caveman Cloud control plane. Requires the auditlog:read 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/auth/bootstrap-owner": { "post": { "summary": "Create first owner once", "responses": { "200": { "description": "Owner created" }, "400": { "description": "cave_bad_request when email, name, organization or slug is missing; cave_weak_password when the password is not 12 to 1024 bytes." }, "403": { "description": "cave_bootstrap_disabled when no bootstrap token is configured; cave_bootstrap_token_invalid when the token does not match." }, "409": { "description": "cave_bootstrap_owner_exists — the installation already has an owner; sign in instead." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/auth/config": { "get": { "summary": "Discover the browser authentication mode", "responses": { "200": { "description": "Deployment-selected authentication mode, and whether the first-owner setup can still run (absent when that lookup fails).", "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "legacy", "better-auth" ] }, "bootstrap": { "type": "string", "enum": [ "open", "owner_exists", "disabled" ] } } } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getAuthConfig", "description": "GET /api/v1/auth/config on the Caveman Cloud control plane. Unauthenticated, or authenticated by a request signature rather than a session. Not exposed to autonomous agents: Browser authentication mode discovery; no agent capability.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [] } }, "/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" } }, "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: Client credential-delivery acknowledgement, not an MCP tool. Scoped clients may ACK their approved grant with its device code and delivery secret; this cannot mint or widen access.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-operation": "context.whoami", "x-caveman-operation-contract": "02a93fce28e7dd0367159b6d27f86f63666c996f47b4f14e6949348fd7c23112", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "patch": { "summary": "PATCH /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" } }, "operationId": "patchAuthMe", "description": "PATCH /api/v1/auth/me on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Changes a person's own account profile. An agent connection acts for a project, not as the person, and must not rename them.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/auth/organizations": { "get": { "summary": "List active workspace memberships", "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" } }, "operationId": "getAuthOrganizations", "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/auth/password/reset/confirm": { "post": { "summary": "Confirm a password reset", "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" } }, "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 } } } } } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/auth/password/reset/request": { "post": { "summary": "Request a password reset 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" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [] } }, "/auth/sso/discover": { "post": { "summary": "Find the single sign-on provider for an email address", "responses": { "200": { "description": "The enabled provider of the organization that verified the address's domain by DNS. Start SSO with it.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "provider_id" ], "properties": { "provider_id": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "cave_sso_not_found: one answer for every address no enabled provider covers; cave_identity_required in legacy auth mode." }, "429": { "description": "Rate limited per IP" }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "operationId": "postAuthSsoDiscover", "description": "POST /api/v1/auth/sso/discover 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: Public sign-in discovery before authentication: it names the identity provider for an email address. Part of the authentication plane; agents authenticate through a scoped control-plane session and never touch it.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/auth/switch-organization": { "post": { "summary": "Rotate the session into another workspace", "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. cave_sso_required when the target organization requires single sign-on of this non-owner member." }, "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" } }, "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" } } } } } }, "operationId": "postAuthSwitchOrganization", "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/billing/cancel": { "post": { "summary": "POST /billing/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" } }, "operationId": "postBillingCancel", "description": "POST /api/v1/billing/cancel 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/billing/checkout": { "post": { "summary": "POST /billing/checkout", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postBillingCheckout", "description": "POST /api/v1/billing/checkout 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/billing/limits/{product}": { "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /billing/limits/{product}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putBillingLimitsProduct", "description": "PUT /api/v1/billing/limits/{product} 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/billing/packages/{package}": { "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /billing/packages/{package}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteBillingPackagesPackage", "description": "DELETE /api/v1/billing/packages/{package} 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] }, "post": { "summary": "POST /billing/packages/{package}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postBillingPackagesPackage", "description": "POST /api/v1/billing/packages/{package} 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/billing/resume": { "post": { "summary": "POST /billing/resume", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postBillingResume", "description": "POST /api/v1/billing/resume 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/billing/usage": { "get": { "summary": "GET /billing/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" } }, "operationId": "getBillingUsage", "description": "GET /api/v1/billing/usage on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the billing_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.", "x-caveman-operation": "reports.billing_usage", "x-caveman-operation-contract": "f667c0b86a7319b44d4ec04a5d6a60e061d64906a713e8fa458f440bcd89df0b", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/billing/usage/daily": { "get": { "summary": "GET /billing/usage/daily", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getBillingUsageDaily", "description": "GET /api/v1/billing/usage/daily on the Caveman Cloud control plane. Requires the billing:read scope. Not exposed to autonomous agents: The billing page's per-day chart of the month's billable usage. Agents read the month through the billing_usage action; keeping the day split human-only until an agent surface needs it.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/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" } }, "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.", "x-caveman-operation": "plan.org_plan", "x-caveman-operation-contract": "122397773d40bb58a4a16ecd3fd8e4907a741f03931712128b3c9be947a08789", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/ci/runs": { "post": { "summary": "POST /ci/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" } }, "operationId": "postCiRuns", "description": "POST /api/v1/ci/runs on the Caveman Cloud control plane. Requires a GitHub Actions OIDC token issued for this API (Authorization: Bearer), from a workflow in a repository connected to the project. Not exposed to autonomous agents: Not RBAC-guarded: authenticated by the CI provider's OIDC token for one job. Agents never hold that token.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "github-actions-oidc", "security": [ { "githubActionsOIDC": [] } ] } }, "/ci/runs/{runId}/finish": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /ci/runs/{runId}/finish", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCiRunsRunIdFinish", "description": "POST /api/v1/ci/runs/{runId}/finish on the Caveman Cloud control plane. Requires a GitHub Actions OIDC token issued for this API (Authorization: Bearer), from a workflow in a repository connected to the project. Not exposed to autonomous agents: Not RBAC-guarded: authenticated by the CI provider's OIDC token for one job. Agents never hold that token.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "github-actions-oidc", "security": [ { "githubActionsOIDC": [] } ] } }, "/cloud/operations": { "get": { "summary": "GET /cloud/operations", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "view", "in": "query", "required": false, "description": "full (the default) returns every descriptor the caller may use; ids returns only their ids, for a client that re-checks its grants on every call.", "schema": { "type": "string", "enum": [ "full", "ids" ], "default": "full" } } ], "operationId": "getCloudOperations", "description": "GET /api/v1/cloud/operations on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the operations 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/cloud/operations/{operationId}": { "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /cloud/operations/{operationId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCloudOperationsOperationId", "description": "POST /api/v1/cloud/operations/{operationId} on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the execute_org_operation action of the caveman_project_setup tool (write access). Project settings for the bound project: semantic-cache shadowing and its options, pixel density, routing previews. Optimizations themselves are chosen per request (x-cave-optimize, x-cave-cache), not switched on here. Changing the semantic-cache threshold or TTL is refused server-side unless the caller holds policy:publish_s2_s3, which a scoped agent connection does not.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/code/access-log": { "get": { "summary": "GET /code/access-log", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeAccessLog", "description": "GET /api/v1/code/access-log on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: A person's own record of which runtime read their secrets, server keys, profile or connections (names only). It is for that person in the Code app or the web, not for agent connections.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/agents": { "get": { "summary": "List agents", "responses": { "200": { "description": "Agents", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/CodeAgent" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include archived agents." } ], "operationId": "getCodeAgents", "description": "GET /api/v1/code/agents on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "Create an agent", "responses": { "201": { "description": "The agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAgent" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "409": { "description": "An agent of that name exists." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/agents on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "file" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" }, "file": { "type": "string", "maxLength": 262144 } } } } } }, "operationId": "postCodeAgents", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/agents/{agentId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read an agent with its latest file", "responses": { "200": { "description": "The agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAgent" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeAgentsAgentId", "description": "GET /api/v1/code/agents/{agentId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "Update an agent's file", "responses": { "200": { "description": "The agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAgent" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "409": { "description": "Archived, or a newer version exists." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/agents/{agentId} on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "file" ], "properties": { "file": { "type": "string", "maxLength": 262144 }, "version": { "type": "integer", "minimum": 1 } } } } } }, "operationId": "postCodeAgentsAgentId", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/agents/{agentId}/archive": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Archive an agent", "responses": { "200": { "description": "The agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAgent" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/agents/{agentId}/archive on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "operationId": "postCodeAgentsAgentIdArchive", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/agents/{agentId}/versions": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List an agent's versions", "responses": { "200": { "description": "Versions, newest first, without files", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "versions" ], "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/CodeAgentVersion" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeAgentsAgentIdVersions", "description": "GET /api/v1/code/agents/{agentId}/versions on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/agents/{agentId}/versions/{version}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read one version of an agent with its file", "responses": { "200": { "description": "The version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAgentVersion" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeAgentsAgentIdVersionsVersion", "description": "GET /api/v1/code/agents/{agentId}/versions/{version} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/automations": { "get": { "summary": "List Cloud automations", "responses": { "200": { "description": "Automations, newest first", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "automations" ], "properties": { "automations": { "type": "array", "items": { "$ref": "#/components/schemas/CodeAutomation" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/automations on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "parameters": [ { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this repository's (owner/name)." } ], "operationId": "getCodeAutomations", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/automations/{automationId}": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read a Cloud automation with its revisions", "responses": { "200": { "description": "The automation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAutomation" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeAutomationsAutomationId", "description": "GET /api/v1/code/automations/{automationId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/automations/{automationId}/board": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read one automation's board", "responses": { "200": { "description": "The automation's board", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CodeAutomationsBoard" }, { "type": "object", "required": [ "steps" ], "properties": { "steps": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CodeStepModel" } }, { "type": "null" } ] } } } ] } } } }, "404": { "description": "Not an automation of this organization." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/automations/{automationId}/board on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: The automations board is read in the console's Automations page by the people who own the automations (ADR 0134). An agent works inside a run's session and does not read the org's automation outcomes from a control-plane connection.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 400 } } ], "operationId": "getCodeAutomationsAutomationIdBoard", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/automations/{automationId}/disable": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/automations/{automationId}/disable", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeAutomationsAutomationIdDisable", "description": "POST /api/v1/code/automations/{automationId}/disable on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/automations/{automationId}/enable": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/automations/{automationId}/enable", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeAutomationsAutomationIdEnable", "description": "POST /api/v1/code/automations/{automationId}/enable on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/automations/{automationId}/hook/rotate": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/automations/{automationId}/hook/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" } }, "operationId": "postCodeAutomationsAutomationIdHookRotate", "description": "POST /api/v1/code/automations/{automationId}/hook/rotate on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/automations/{automationId}/revisions/{revisionId}": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "revisionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read a revision with its files", "responses": { "200": { "description": "The revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAutomationRevision" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeAutomationsAutomationIdRevisionsRevisionId", "description": "GET /api/v1/code/automations/{automationId}/revisions/{revisionId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/automations/{automationId}/revisions/{revisionId}/approve": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "revisionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Approve a waiting revision", "responses": { "200": { "description": "The automation, the now-active revision and, once, its hook", "content": { "application/json": { "schema": { "type": "object", "required": [ "automation", "revision" ], "properties": { "automation": { "$ref": "#/components/schemas/CodeAutomation" }, "revision": { "$ref": "#/components/schemas/CodeAutomationRevision" }, "hook": { "type": "object" } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "409": { "description": "Not waiting, or no service account named and none to default to (cave_code_automation_service_account_required; the message names the choices)." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/automations/{automationId}/revisions/{revisionId}/approve on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "service_account_id": { "type": "string", "format": "uuid" } } } } } }, "operationId": "postCodeAutomationsAutomationIdRevisionsRevisionIdApprove", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/automations/{automationId}/run": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Run an automation now", "responses": { "201": { "description": "The run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAutomationRun" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "409": { "description": "The automation is off or has no approved revision." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/automations/{automationId}/run on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "inputs": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 4096 }, "maxProperties": 32 } } } } } }, "operationId": "postCodeAutomationsAutomationIdRun", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/automations/{automationId}/runs": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List an automation's runs", "responses": { "200": { "description": "Runs, newest first", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "runs" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/CodeAutomationRun" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeAutomationsAutomationIdRuns", "description": "GET /api/v1/code/automations/{automationId}/runs on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/automations/{automationId}/runs/{runId}": { "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read an automation run", "responses": { "200": { "description": "The run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAutomationRun" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeAutomationsAutomationIdRunsRunId", "description": "GET /api/v1/code/automations/{automationId}/runs/{runId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/automations/apply": { "post": { "summary": "Apply a repository's automation files", "responses": { "200": { "description": "What the apply did to each automation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "automations" ], "properties": { "automations": { "type": "array", "items": { "$ref": "#/components/schemas/CodeAutomationApplied" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/automations/apply on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "repo", "files" ], "properties": { "repo": { "type": "string", "description": "owner/name" }, "commit_sha": { "type": "string", "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})?$" }, "files": { "type": "object", "additionalProperties": { "type": "string" }, "description": ".caveman/automations/.yaml and .caveman/agents/.md files by path." }, "service_account_id": { "type": "string", "format": "uuid", "description": "A person's apply: the service account the automations run as. A code:run key binds its own." } } } } } }, "operationId": "postCodeAutomationsApply", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/automations/board": { "get": { "summary": "Read the automations board", "responses": { "200": { "description": "The board", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeAutomationsBoard" } } } }, "400": { "description": "days is out of range." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/automations/board on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: The automations board is read in the console's Automations page by the people who own the automations (ADR 0134). An agent works inside a run's session and does not read the org's automation outcomes from a control-plane connection.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 400 } } ], "operationId": "getCodeAutomationsBoard", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/automations/runs": { "get": { "summary": "List automation runs", "responses": { "200": { "description": "Runs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "runs" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/CodeAutomationRun" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/automations/runs on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Cloud automations are applied from a repository's .caveman/ files by the Code app, a code:run key or a push to the default branch, and a person approves wider authority (ADR 0133). An agent works inside a run's session and never applies, approves, enables or fires automations from a control-plane connection.", "parameters": [ { "name": "automation_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only this automation's runs." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "At most this many (100)." } ], "operationId": "getCodeAutomationsRuns", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/automations/service-accounts": { "get": { "summary": "List the service accounts you may bind an automation to", "responses": { "200": { "description": "Accounts", "content": { "application/json": { "schema": { "type": "object", "required": [ "service_accounts" ], "properties": { "service_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/CodeServiceAccount" } } } } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/automations/service-accounts on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: The console's Approve and Enable pick the service account an automation runs as from this list (ADR 0133). Binding an account is a person's decision about authority; an agent never makes it from a control-plane connection.", "operationId": "getCodeAutomationsServiceAccounts", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/chats": { "get": { "summary": "GET /code/chats", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeChats", "description": "GET /api/v1/code/chats on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: A person's chats sync to their own devices through the Code app (ADR 0135): the list, its stream, the Cloud copy, marks, queued calls and moves. An agent works inside a Code session and never lists, reads, calls or moves a person's chats from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/chats/{sessionId}/calls": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/chats/{sessionId}/calls", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeChatsSessionIdCalls", "description": "POST /api/v1/code/chats/{sessionId}/calls on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person's chats sync to their own devices through the Code app (ADR 0135): the list, its stream, the Cloud copy, marks, queued calls and moves. An agent works inside a Code session and never lists, reads, calls or moves a person's chats from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/chats/{sessionId}/calls/{requestId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/chats/{sessionId}/calls/{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" } }, "operationId": "getCodeChatsSessionIdCallsRequestId", "description": "GET /api/v1/code/chats/{sessionId}/calls/{requestId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: A person's chats sync to their own devices through the Code app (ADR 0135): the list, its stream, the Cloud copy, marks, queued calls and moves. An agent works inside a Code session and never lists, reads, calls or moves a person's chats from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/chats/{sessionId}/events": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/chats/{sessionId}/events", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeChatsSessionIdEvents", "description": "GET /api/v1/code/chats/{sessionId}/events on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: A person's chats sync to their own devices through the Code app (ADR 0135): the list, its stream, the Cloud copy, marks, queued calls and moves. An agent works inside a Code session and never lists, reads, calls or moves a person's chats from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/chats/{sessionId}/move": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/chats/{sessionId}/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" } }, "operationId": "postCodeChatsSessionIdMove", "description": "POST /api/v1/code/chats/{sessionId}/move on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person's chats sync to their own devices through the Code app (ADR 0135): the list, its stream, the Cloud copy, marks, queued calls and moves. An agent works inside a Code session and never lists, reads, calls or moves a person's chats from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/chats/{sessionId}/state": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /code/chats/{sessionId}/state", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeChatsSessionIdState", "description": "PUT /api/v1/code/chats/{sessionId}/state on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person's chats sync to their own devices through the Code app (ADR 0135): the list, its stream, the Cloud copy, marks, queued calls and moves. An agent works inside a Code session and never lists, reads, calls or moves a person's chats from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/chats/stream": { "get": { "summary": "GET /code/chats/stream", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeChatsStream", "description": "GET /api/v1/code/chats/stream on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: A person's chats sync to their own devices through the Code app (ADR 0135): the list, its stream, the Cloud copy, marks, queued calls and moves. An agent works inside a Code session and never lists, reads, calls or moves a person's chats from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/computers": { "get": { "summary": "GET /code/computers", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeComputers", "description": "GET /api/v1/code/computers on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/computers/{computerId}": { "parameters": [ { "name": "computerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/computers/{computerId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeComputersComputerId", "description": "DELETE /api/v1/code/computers/{computerId} on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] }, "get": { "summary": "GET /code/computers/{computerId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeComputersComputerId", "description": "GET /api/v1/code/computers/{computerId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/computers/{computerId}/resume": { "parameters": [ { "name": "computerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/computers/{computerId}/resume", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeComputersComputerIdResume", "description": "POST /api/v1/code/computers/{computerId}/resume on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/computers/{computerId}/sleep": { "parameters": [ { "name": "computerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/computers/{computerId}/sleep", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeComputersComputerIdSleep", "description": "POST /api/v1/code/computers/{computerId}/sleep on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/computers/{computerId}/update": { "parameters": [ { "name": "computerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/computers/{computerId}/update", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeComputersComputerIdUpdate", "description": "POST /api/v1/code/computers/{computerId}/update on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/computers/{computerId}/wake-hint": { "parameters": [ { "name": "computerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/computers/{computerId}/wake-hint", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeComputersComputerIdWakeHint", "description": "POST /api/v1/code/computers/{computerId}/wake-hint on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person's device wakes their own sleeping Cloud computer while they type (ADR 0135). An agent works inside a Code session and never wakes computers from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/connections": { "get": { "summary": "GET /code/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" } }, "operationId": "getCodeConnections", "description": "GET /api/v1/code/connections on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person's connections to their MCP servers are made and removed by that person in the Code app. No agent connection lists or deletes them, and no route but a runtime lease returns a token.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/connections/{connectionId}": { "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/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" } }, "operationId": "deleteCodeConnectionsConnectionId", "description": "DELETE /api/v1/code/connections/{connectionId} on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person's connections to their MCP servers are made and removed by that person in the Code app. No agent connection lists or deletes them, and no route but a runtime lease returns a token.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/connections/begin": { "get": { "summary": "GET /code/connections/begin", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeConnectionsBegin", "description": "GET /api/v1/code/connections/begin 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 — it is the consent page a person's browser opens before signing in to their MCP server: it names the account and computer that asked, and only that browser's Continue proceeds.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] }, "post": { "summary": "POST /code/connections/begin", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeConnectionsBegin", "description": "POST /api/v1/code/connections/begin 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 — it is the consent page a person's browser opens before signing in to their MCP server: it names the account and computer that asked, and only that browser's Continue proceeds.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/code/connections/callback": { "get": { "summary": "GET /code/connections/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" } }, "operationId": "getCodeConnectionsCallback", "description": "GET /api/v1/code/connections/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 — it is the browser redirect that carries a person's sign-in at their MCP server back to this installation, verified by its single-use state. Only that person's browser completes it.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/code/credits": { "get": { "summary": "GET /code/credits", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeCredits", "description": "GET /api/v1/code/credits on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code credits are read and spent by the Code app on a person's behalf. An agent works inside a Code session and never reads or changes its organisation's plan or credits from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/credits/checkout": { "post": { "summary": "POST /code/credits/checkout", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeCreditsCheckout", "description": "POST /api/v1/code/credits/checkout 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/code/credits/keys": { "post": { "summary": "POST /code/credits/keys", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeCreditsKeys", "description": "POST /api/v1/code/credits/keys on the Caveman Cloud control plane. Requires the code:write 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/credits/keys/{keyId}": { "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/credits/keys/{keyId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeCreditsKeysKeyId", "description": "DELETE /api/v1/code/credits/keys/{keyId} on the Caveman Cloud control plane. Requires the code:write 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/credits/models": { "get": { "summary": "GET /code/credits/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" } }, "operationId": "getCodeCreditsModels", "description": "GET /api/v1/code/credits/models on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code credits are read and spent by the Code app on a person's behalf. An agent works inside a Code session and never reads or changes its organisation's plan or credits from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/credits/settings": { "put": { "summary": "PUT /code/credits/settings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeCreditsSettings", "description": "PUT /api/v1/code/credits/settings 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/code/desktop-token": { "post": { "summary": "POST /code/desktop-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" } }, "operationId": "postCodeDesktopToken", "description": "POST /api/v1/code/desktop-token on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: The Code app's runtime mints its desktop renderer a one-hour token for that person's chats, wake hints, latency reports and runtime attach (ADR 0135). It narrows a person's own session; an agent never needs one.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/engine-logins": { "get": { "summary": "GET /code/engine-logins", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeEngineLogins", "description": "GET /api/v1/code/engine-logins on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: A person's claude.ai or ChatGPT sign-in that follows them to their Cloud computers is listed and signed out everywhere by that person in the Code app or the web. No agent connection lists or removes it, and no route but a Cloud computer's runtime read returns a token.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/engine-logins/{engine}": { "parameters": [ { "name": "engine", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/engine-logins/{engine}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeEngineLoginsEngine", "description": "DELETE /api/v1/code/engine-logins/{engine} on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person's claude.ai or ChatGPT sign-in that follows them to their Cloud computers is listed and signed out everywhere by that person in the Code app or the web. No agent connection lists or removes it, and no route but a Cloud computer's runtime read returns a token.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/environments": { "get": { "summary": "GET /code/environments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeEnvironments", "description": "GET /api/v1/code/environments on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "put": { "summary": "PUT /code/environments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeEnvironments", "description": "PUT /api/v1/code/environments on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/environments/builds": { "post": { "summary": "POST /code/environments/builds", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeEnvironmentsBuilds", "description": "POST /api/v1/code/environments/builds on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/environments/builds/{buildId}": { "parameters": [ { "name": "buildId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/environments/builds/{buildId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeEnvironmentsBuildsBuildId", "description": "GET /api/v1/code/environments/builds/{buildId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/environments/builds/{buildId}/log": { "parameters": [ { "name": "buildId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/environments/builds/{buildId}/log", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeEnvironmentsBuildsBuildIdLog", "description": "GET /api/v1/code/environments/builds/{buildId}/log on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/files": { "get": { "summary": "List files", "responses": { "200": { "description": "A page of files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeFilePage" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/files on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code files are the org's inputs for sessions and the outputs sessions wrote, uploaded and read through the Agents API by a person or a service account's key. An agent in a session reads its attached files at /mnt/session/uploads and writes /mnt/session/outputs through its runtime, never through a control-plane connection.", "parameters": [ { "name": "purpose", "in": "query", "required": false, "schema": { "enum": [ "input", "output" ] }, "description": "Only inputs or only outputs." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "The next_cursor of the previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "At most this many (default 100)." } ], "operationId": "getCodeFiles", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "Upload a file", "responses": { "201": { "description": "The file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeFile" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "413": { "description": "Over 100 MB (cave_code_file_too_large)." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/files on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code files are the org's inputs for sessions and the outputs sessions wrote, uploaded and read through the Agents API by a person or a service account's key. An agent in a session reads its attached files at /mnt/session/uploads and writes /mnt/session/outputs through its runtime, never through a control-plane connection.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": false, "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "operationId": "postCodeFiles", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/files/{fileId}": { "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete a file", "responses": { "204": { "description": "Deleted" }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "No such file the caller sees." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "DELETE /api/v1/code/files/{fileId} on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code files are the org's inputs for sessions and the outputs sessions wrote, uploaded and read through the Agents API by a person or a service account's key. An agent in a session reads its attached files at /mnt/session/uploads and writes /mnt/session/outputs through its runtime, never through a control-plane connection.", "operationId": "deleteCodeFilesFileId", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] }, "get": { "summary": "Read a file's metadata", "responses": { "200": { "description": "The file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeFile" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "No such file the caller sees." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeFilesFileId", "description": "GET /api/v1/code/files/{fileId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code files are the org's inputs for sessions and the outputs sessions wrote, uploaded and read through the Agents API by a person or a service account's key. An agent in a session reads its attached files at /mnt/session/uploads and writes /mnt/session/outputs through its runtime, never through a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/files/{fileId}/content": { "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Download a file", "responses": { "200": { "description": "The file's bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "No such file the caller sees." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/files/{fileId}/content on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code files are the org's inputs for sessions and the outputs sessions wrote, uploaded and read through the Agents API by a person or a service account's key. An agent in a session reads its attached files at /mnt/session/uploads and writes /mnt/session/outputs through its runtime, never through a control-plane connection.", "operationId": "getCodeFilesFileIdContent", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/hooks/{hookId}": { "parameters": [ { "name": "hookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/hooks/{hookId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeHooksHookId", "description": "POST /api/v1/code/hooks/{hookId} 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 — authenticated by the request's own signature: the automation's hook secret, or the Slack, Linear or Jira signing secret the installation holds (ADR 0133). Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/code/integrations/{provider}/links": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/integrations/{provider}/links", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeIntegrationsProviderLinks", "description": "POST /api/v1/code/integrations/{provider}/links on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: A person with org:update links a Slack workspace, Linear organization or Jira site to the organization with a one-time code the external workspace posts back (ADR 0133). No agent connection links or unlinks one.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/integrations/links": { "get": { "summary": "GET /code/integrations/links", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeIntegrationsLinks", "description": "GET /api/v1/code/integrations/links on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: A person with org:update links a Slack workspace, Linear organization or Jira site to the organization with a one-time code the external workspace posts back (ADR 0133). No agent connection links or unlinks one.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/integrations/links/{linkId}": { "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/integrations/links/{linkId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeIntegrationsLinksLinkId", "description": "DELETE /api/v1/code/integrations/links/{linkId} on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: A person with org:update links a Slack workspace, Linear organization or Jira site to the organization with a one-time code the external workspace posts back (ADR 0133). No agent connection links or unlinks one.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/mail/ask": { "post": { "summary": "POST /code/mail/ask", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailAsk", "description": "POST /api/v1/code/mail/ask on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/claim": { "post": { "summary": "POST /code/mail/claim", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailClaim", "description": "POST /api/v1/code/mail/claim on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/deliveries": { "post": { "summary": "POST /code/mail/deliveries", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailDeliveries", "description": "POST /api/v1/code/mail/deliveries on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/deliveries/ack": { "post": { "summary": "POST /code/mail/deliveries/ack", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailDeliveriesAck", "description": "POST /api/v1/code/mail/deliveries/ack on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/deliveries/renew": { "post": { "summary": "POST /code/mail/deliveries/renew", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailDeliveriesRenew", "description": "POST /api/v1/code/mail/deliveries/renew on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/handoff": { "post": { "summary": "POST /code/mail/handoff", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailHandoff", "description": "POST /api/v1/code/mail/handoff on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/note": { "post": { "summary": "POST /code/mail/note", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailNote", "description": "POST /api/v1/code/mail/note on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/release": { "post": { "summary": "POST /code/mail/release", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailRelease", "description": "POST /api/v1/code/mail/release on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/spawn": { "post": { "summary": "POST /code/mail/spawn", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailSpawn", "description": "POST /api/v1/code/mail/spawn on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/task": { "post": { "summary": "POST /code/mail/task", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMailTask", "description": "POST /api/v1/code/mail/task on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/mail/wait": { "get": { "summary": "GET /code/mail/wait", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeMailWait", "description": "GET /api/v1/code/mail/wait on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/marketplaces": { "get": { "summary": "GET /code/marketplaces", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeMarketplaces", "description": "GET /api/v1/code/marketplaces on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "POST /code/marketplaces", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeMarketplaces", "description": "POST /api/v1/code/marketplaces on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/marketplaces/{marketplaceId}": { "parameters": [ { "name": "marketplaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /code/marketplaces/{marketplaceId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchCodeMarketplacesMarketplaceId", "description": "PATCH /api/v1/code/marketplaces/{marketplaceId} on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/memory-stores": { "get": { "summary": "List memory stores", "responses": { "200": { "description": "Memory stores", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "memory_stores" ], "properties": { "memory_stores": { "type": "array", "items": { "$ref": "#/components/schemas/CodeMemoryStore" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/memory-stores on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Team memory stores are created and curated through the Agents API by a person or a service account's key. An agent in a session reads and writes only the stores its session attached, through its runtime and as attached, never through a control-plane connection.", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only one Code project's stores." } ], "operationId": "getCodeMemoryStores", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "Create a memory store", "responses": { "201": { "description": "The store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeMemoryStore" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "409": { "description": "A store by that name exists, or the organization is at its cap." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/memory-stores on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Team memory stores are created and curated through the Agents API by a person or a service account's key. An agent in a session reads and writes only the stores its session attached, through its runtime and as attached, never through a control-plane connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 1000 }, "project_id": { "type": "string", "format": "uuid" } } } } } }, "operationId": "postCodeMemoryStores", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/memory-stores/{storeId}": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete a memory store", "responses": { "204": { "description": "Deleted" }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "No such store the caller sees." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "DELETE /api/v1/code/memory-stores/{storeId} on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Team memory stores are created and curated through the Agents API by a person or a service account's key. An agent in a session reads and writes only the stores its session attached, through its runtime and as attached, never through a control-plane connection.", "operationId": "deleteCodeMemoryStoresStoreId", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] }, "get": { "summary": "Read a memory store", "responses": { "200": { "description": "The store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeMemoryStore" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "No such store the caller sees." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeMemoryStoresStoreId", "description": "GET /api/v1/code/memory-stores/{storeId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Team memory stores are created and curated through the Agents API by a person or a service account's key. An agent in a session reads and writes only the stores its session attached, through its runtime and as attached, never through a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/memory-stores/{storeId}/memories": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete a memory", "responses": { "204": { "description": "Deleted (kept as a version)" }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "No such memory." }, "409": { "description": "if_sha256 does not match." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 }, "description": "The memory to delete." }, { "name": "if_sha256", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The sha256 its current content must have." } ], "operationId": "deleteCodeMemoryStoresStoreIdMemories", "description": "DELETE /api/v1/code/memory-stores/{storeId}/memories on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Team memory stores are created and curated through the Agents API by a person or a service account's key. An agent in a session reads and writes only the stores its session attached, through its runtime and as attached, never through a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] }, "get": { "summary": "List or read memories", "responses": { "200": { "description": "A memory, or a page of memories", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CodeMemory" }, { "$ref": "#/components/schemas/CodeMemoryPage" } ] } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "No such store or memory the caller sees." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/memory-stores/{storeId}/memories on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Team memory stores are created and curated through the Agents API by a person or a service account's key. An agent in a session reads and writes only the stores its session attached, through its runtime and as attached, never through a control-plane connection.", "parameters": [ { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 }, "description": "Read this one memory, with its content." }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 }, "description": "Only paths starting with this." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 }, "description": "The next_cursor of the previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "At most this many (100 with content)." }, { "name": "include_content", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Carry each memory's content." } ], "operationId": "getCodeMemoryStoresStoreIdMemories", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "put": { "summary": "Write a memory", "responses": { "200": { "description": "The memory, without content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeMemory" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "409": { "description": "if_sha256 does not match (cave_code_memory_conflict), or the store is full." }, "413": { "description": "Over 100 KB." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "PUT /api/v1/code/memory-stores/{storeId}/memories on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Team memory stores are created and curated through the Agents API by a person or a service account's key. An agent in a session reads and writes only the stores its session attached, through its runtime and as attached, never through a control-plane connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "path", "content" ], "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "content": { "type": "string", "maxLength": 102400 }, "if_sha256": { "type": "string", "description": "A lowercase hex sha256, or \"\"." } } } } } }, "operationId": "putCodeMemoryStoresStoreIdMemories", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/memory-stores/{storeId}/memories/versions": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List a memory's versions", "responses": { "200": { "description": "Versions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "versions" ], "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/CodeMemoryVersion" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/memory-stores/{storeId}/memories/versions on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Team memory stores are created and curated through the Agents API by a person or a service account's key. An agent in a session reads and writes only the stores its session attached, through its runtime and as attached, never through a control-plane connection.", "parameters": [ { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 }, "description": "The memory's path." } ], "operationId": "getCodeMemoryStoresStoreIdMemoriesVersions", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/memory-stores/{storeId}/memories/versions/{versionId}": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read a memory version", "responses": { "200": { "description": "The version, with content for a put", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeMemoryVersion" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "No such version in the last 30 days." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeMemoryStoresStoreIdMemoriesVersionsVersionId", "description": "GET /api/v1/code/memory-stores/{storeId}/memories/versions/{versionId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Team memory stores are created and curated through the Agents API by a person or a service account's key. An agent in a session reads and writes only the stores its session attached, through its runtime and as attached, never through a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/plan/cancel": { "post": { "summary": "POST /code/plan/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" } }, "operationId": "postCodePlanCancel", "description": "POST /api/v1/code/plan/cancel 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/code/plan/change": { "post": { "summary": "POST /code/plan/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" } }, "operationId": "postCodePlanChange", "description": "POST /api/v1/code/plan/change 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/code/plan/checkout": { "post": { "summary": "POST /code/plan/checkout", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodePlanCheckout", "description": "POST /api/v1/code/plan/checkout 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/code/plan/resume": { "post": { "summary": "POST /code/plan/resume", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodePlanResume", "description": "POST /api/v1/code/plan/resume 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:write" ] } }, "/code/plugins/installs": { "delete": { "summary": "DELETE /code/plugins/installs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodePluginsInstalls", "description": "DELETE /api/v1/code/plugins/installs on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] }, "get": { "summary": "GET /code/plugins/installs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodePluginsInstalls", "description": "GET /api/v1/code/plugins/installs on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "POST /code/plugins/installs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodePluginsInstalls", "description": "POST /api/v1/code/plugins/installs on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/policy": { "get": { "summary": "Read the organization's Code policy", "responses": { "200": { "description": "The policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodePolicy" } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodePolicy", "description": "GET /api/v1/code/policy on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Service accounts, their code:run keys and the organization's Code policy are a person's decisions (org:update). No agent connection mints credentials, disables an account or changes the policy.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] }, "put": { "summary": "Replace the organization's Code policy", "responses": { "200": { "description": "The policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodePolicy" } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodePolicy" } } } }, "operationId": "putCodePolicy", "description": "PUT /api/v1/code/policy on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Service accounts, their code:run keys and the organization's Code policy are a person's decisions (org:update). No agent connection mints credentials, disables an account or changes the policy.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/profile": { "delete": { "summary": "DELETE /code/profile", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeProfile", "description": "DELETE /api/v1/code/profile on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person removes their own synced Caveman Code settings from Cloud in the Code app or the web. No agent connection deletes them.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/projects": { "get": { "summary": "GET /code/projects", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeProjects", "description": "GET /api/v1/code/projects on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "POST /code/projects", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeProjects", "description": "POST /api/v1/code/projects on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/projects/{projectId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /code/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" } }, "operationId": "patchCodeProjectsProjectId", "description": "PATCH /api/v1/code/projects/{projectId} on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/projects/{projectId}/repos": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/projects/{projectId}/repos", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeProjectsProjectIdRepos", "description": "DELETE /api/v1/code/projects/{projectId}/repos on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] }, "post": { "summary": "POST /code/projects/{projectId}/repos", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeProjectsProjectIdRepos", "description": "POST /api/v1/code/projects/{projectId}/repos on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/projects/for-repository": { "post": { "summary": "POST /code/projects/for-repository", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeProjectsForRepository", "description": "POST /api/v1/code/projects/for-repository on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/router/keys": { "post": { "summary": "Rotate this Code sign-in's routing-only key", "responses": { "201": { "description": "Routing key activated. Cache-Control: no-store. Store full_key securely; it cannot be read again.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "id", "name", "key_prefix", "scopes", "full_key", "created_at", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "const": "caveman-code-router" }, "key_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "const": "router:write" }, "minItems": 1, "maxItems": 1 }, "full_key": { "type": "string", "description": "Returned once; store securely." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Error", "description": "cave_unauthorized or cave_invalid_session: sign in again." }, "402": { "$ref": "#/components/responses/Error", "description": "cave_code_router_paid_required: no paid Caveman plan or enabled positive credits balance." }, "403": { "$ref": "#/components/responses/Error", "description": "cave_code_device_required, cave_scope_forbidden, cave_agent_operation_forbidden, cave_project_forbidden, cave_forbidden, or license admission denied." }, "409": { "$ref": "#/components/responses/Error", "description": "cave_code_router_no_project or cave_policy_delivery_pending (Retry-After: 1)." }, "429": { "$ref": "#/components/responses/Error", "description": "cave_auth_rate_limited; Retry-After says when to retry." }, "500": { "$ref": "#/components/responses/Error", "description": "cave_code_router_key_failed: persistence failed." }, "503": { "$ref": "#/components/responses/Error", "description": "cave_code_router_unavailable, cave_key_invalidation_failed or cave_key_cache_failed. Retry; a replacement is never returned before prior-key invalidation succeeds." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRouterKeys", "description": "POST /api/v1/code/router/keys on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Mints a routing-only credential for a paid Caveman Code device sign-in. Agent and MCP sessions cannot widen their own access. Requires a live Code device session with code:write and a paid effective Cloud or Code plan, or enabled credits with a positive unreserved balance. No request body: tenant, user, session, project and scopes are server-derived. Returns the secret once. Repeating rotates the previous key; sign-out and device revocation revoke it. expires_at is the device session's expiry. Same control-plane IP, principal and organization rate limits as credits key minting. Read GET /auth/me plan and, when available, GET /code/credits plan, use_balance and balance_micros to offer Auto; this mint is authoritative.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/runtime": { "get": { "summary": "GET /code/runtime", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntime", "description": "GET /api/v1/code/runtime on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/access-log": { "get": { "summary": "GET /code/runtime/access-log", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeAccessLog", "description": "GET /api/v1/code/runtime/access-log on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/agents": { "get": { "summary": "GET /code/runtime/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" } }, "operationId": "getCodeRuntimeAgents", "description": "GET /api/v1/code/runtime/agents on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "post": { "summary": "POST /code/runtime/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" } }, "operationId": "postCodeRuntimeAgents", "description": "POST /api/v1/code/runtime/agents on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/agents/{agentId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/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" } }, "operationId": "postCodeRuntimeAgentsAgentId", "description": "POST /api/v1/code/runtime/agents/{agentId} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/agents/{agentId}/versions/{version}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/agents/{agentId}/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" } }, "operationId": "getCodeRuntimeAgentsAgentIdVersionsVersion", "description": "GET /api/v1/code/runtime/agents/{agentId}/versions/{version} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/automations": { "get": { "summary": "GET /code/runtime/automations", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeAutomations", "description": "GET /api/v1/code/runtime/automations on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/automations/apply": { "post": { "summary": "POST /code/runtime/automations/apply", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeAutomationsApply", "description": "POST /api/v1/code/runtime/automations/apply on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/automations/revisions/{revisionId}": { "parameters": [ { "name": "revisionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/automations/revisions/{revisionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeAutomationsRevisionsRevisionId", "description": "GET /api/v1/code/runtime/automations/revisions/{revisionId} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token, and only for an automation run whose session is on that runtime's computer (ADR 0133). Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/automations/runs": { "get": { "summary": "GET /code/runtime/automations/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" } }, "operationId": "getCodeRuntimeAutomationsRuns", "description": "GET /api/v1/code/runtime/automations/runs on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/bootstrap": { "post": { "summary": "POST /code/runtime/bootstrap", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeBootstrap", "description": "POST /api/v1/code/runtime/bootstrap 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 — asked by a warm Cloud computer pod with the bootstrap token only its own Secret holds; it answers the computer's runtime identity sealed to that pod's key, which nothing else opens (ADR 0136, kind review K6). Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/code/runtime/chats": { "put": { "summary": "PUT /code/runtime/chats", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeChats", "description": "PUT /api/v1/code/runtime/chats on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/chats/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/runtime/chats/{sessionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeRuntimeChatsSessionId", "description": "DELETE /api/v1/code/runtime/chats/{sessionId} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "put": { "summary": "PUT /code/runtime/chats/{sessionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeChatsSessionId", "description": "PUT /api/v1/code/runtime/chats/{sessionId} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/chats/{sessionId}/calls": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/chats/{sessionId}/calls", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeChatsSessionIdCalls", "description": "POST /api/v1/code/runtime/chats/{sessionId}/calls on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/chats/{sessionId}/calls/{callId}/result": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "callId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/chats/{sessionId}/calls/{callId}/result", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeChatsSessionIdCallsCallIdResult", "description": "POST /api/v1/code/runtime/chats/{sessionId}/calls/{callId}/result on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/comments": { "post": { "summary": "POST /code/runtime/comments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeComments", "description": "POST /api/v1/code/runtime/comments on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token, and only for a live automation run whose session is on that runtime's computer and whose approved revision declares a github.comment output, on the issue, pull request or commit that fired it (ADR 0133). Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/computers": { "get": { "summary": "GET /code/runtime/computers", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeComputers", "description": "GET /api/v1/code/runtime/computers on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/computers/{computerId}": { "parameters": [ { "name": "computerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/runtime/computers/{computerId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeRuntimeComputersComputerId", "description": "DELETE /api/v1/code/runtime/computers/{computerId} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime, only on a Cloud computer they made (never with their admin role), and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/computers/{computerId}/resume": { "parameters": [ { "name": "computerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/computers/{computerId}/resume", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeComputersComputerIdResume", "description": "POST /api/v1/code/runtime/computers/{computerId}/resume on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/computers/{computerId}/sleep": { "parameters": [ { "name": "computerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/computers/{computerId}/sleep", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeComputersComputerIdSleep", "description": "POST /api/v1/code/runtime/computers/{computerId}/sleep on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/computers/{computerId}/update": { "parameters": [ { "name": "computerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/computers/{computerId}/update", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeComputersComputerIdUpdate", "description": "POST /api/v1/code/runtime/computers/{computerId}/update on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime, only on a Cloud computer they made (never with their admin role), and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/connections": { "get": { "summary": "GET /code/runtime/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" } }, "operationId": "getCodeRuntimeConnections", "description": "GET /api/v1/code/runtime/connections on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/connections/{connectionId}": { "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/runtime/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" } }, "operationId": "deleteCodeRuntimeConnectionsConnectionId", "description": "DELETE /api/v1/code/runtime/connections/{connectionId} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/connections/lease": { "post": { "summary": "POST /code/runtime/connections/lease", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeConnectionsLease", "description": "POST /api/v1/code/runtime/connections/lease on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/connections/start": { "post": { "summary": "POST /code/runtime/connections/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" } }, "operationId": "postCodeRuntimeConnectionsStart", "description": "POST /api/v1/code/runtime/connections/start on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/engine-logins": { "get": { "summary": "GET /code/runtime/engine-logins", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeEngineLogins", "description": "GET /api/v1/code/runtime/engine-logins on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/engine-logins/{engine}": { "parameters": [ { "name": "engine", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/runtime/engine-logins/{engine}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeRuntimeEngineLoginsEngine", "description": "DELETE /api/v1/code/runtime/engine-logins/{engine} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "get": { "summary": "GET /code/runtime/engine-logins/{engine}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeEngineLoginsEngine", "description": "GET /api/v1/code/runtime/engine-logins/{engine} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "put": { "summary": "PUT /code/runtime/engine-logins/{engine}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeEngineLoginsEngine", "description": "PUT /api/v1/code/runtime/engine-logins/{engine} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/engine-logins/{engine}/refresh": { "parameters": [ { "name": "engine", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/engine-logins/{engine}/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" } }, "operationId": "postCodeRuntimeEngineLoginsEngineRefresh", "description": "POST /api/v1/code/runtime/engine-logins/{engine}/refresh on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/environments": { "get": { "summary": "GET /code/runtime/environments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeEnvironments", "description": "GET /api/v1/code/runtime/environments on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "put": { "summary": "PUT /code/runtime/environments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeEnvironments", "description": "PUT /api/v1/code/runtime/environments on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/environments/builds": { "post": { "summary": "POST /code/runtime/environments/builds", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeEnvironmentsBuilds", "description": "POST /api/v1/code/runtime/environments/builds on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/environments/builds/{buildId}": { "parameters": [ { "name": "buildId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/environments/builds/{buildId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeEnvironmentsBuildsBuildId", "description": "GET /api/v1/code/runtime/environments/builds/{buildId} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/environments/builds/{buildId}/log": { "parameters": [ { "name": "buildId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/environments/builds/{buildId}/log", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeEnvironmentsBuildsBuildIdLog", "description": "GET /api/v1/code/runtime/environments/builds/{buildId}/log on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/files/{fileId}/content": { "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/files/{fileId}/content", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeFilesFileIdContent", "description": "GET /api/v1/code/runtime/files/{fileId}/content on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/heartbeat": { "post": { "summary": "POST /code/runtime/heartbeat", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeHeartbeat", "description": "POST /api/v1/code/runtime/heartbeat on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/local-usage": { "post": { "summary": "POST /code/runtime/local-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" } }, "operationId": "postCodeRuntimeLocalUsage", "description": "POST /api/v1/code/runtime/local-usage on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/memory-stores/{storeId}/memories": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/runtime/memory-stores/{storeId}/memories", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeRuntimeMemoryStoresStoreIdMemories", "description": "DELETE /api/v1/code/runtime/memory-stores/{storeId}/memories on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "get": { "summary": "GET /code/runtime/memory-stores/{storeId}/memories", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeMemoryStoresStoreIdMemories", "description": "GET /api/v1/code/runtime/memory-stores/{storeId}/memories on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "put": { "summary": "PUT /code/runtime/memory-stores/{storeId}/memories", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeMemoryStoresStoreIdMemories", "description": "PUT /api/v1/code/runtime/memory-stores/{storeId}/memories on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/memory-stores/{storeId}/memories/versions": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/memory-stores/{storeId}/memories/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" } }, "operationId": "getCodeRuntimeMemoryStoresStoreIdMemoriesVersions", "description": "GET /api/v1/code/runtime/memory-stores/{storeId}/memories/versions on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/moves/{moveId}": { "parameters": [ { "name": "moveId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/moves/{moveId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeMovesMoveId", "description": "POST /api/v1/code/runtime/moves/{moveId} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/outputs": { "post": { "summary": "POST /code/runtime/outputs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeOutputs", "description": "POST /api/v1/code/runtime/outputs on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token, and only for an automation run whose session is on that runtime's computer (ADR 0133). Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/plugins": { "get": { "summary": "GET /code/runtime/plugins", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimePlugins", "description": "GET /api/v1/code/runtime/plugins on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/profile": { "delete": { "summary": "DELETE /code/runtime/profile", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeRuntimeProfile", "description": "DELETE /api/v1/code/runtime/profile on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "get": { "summary": "GET /code/runtime/profile", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeProfile", "description": "GET /api/v1/code/runtime/profile on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "put": { "summary": "PUT /code/runtime/profile", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeProfile", "description": "PUT /api/v1/code/runtime/profile on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/pull-request-info": { "post": { "summary": "POST /code/runtime/pull-request-info", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimePullRequestInfo", "description": "POST /api/v1/code/runtime/pull-request-info on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token, only for a pull request of the repository Cloud made that Cloud computer for, for a chat whose person GitHub confirms may read it, on a computer no other person's work shares; Cloud reads it with the GitHub App and binds the first open one to the chat (ADR 0136). Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/pull-requests": { "get": { "summary": "GET /code/runtime/pull-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" } }, "operationId": "getCodeRuntimePullRequests", "description": "GET /api/v1/code/runtime/pull-requests on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "post": { "summary": "POST /code/runtime/pull-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" } }, "operationId": "postCodeRuntimePullRequests", "description": "POST /api/v1/code/runtime/pull-requests on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token, for a live automation run whose session is on that runtime's computer and whose approved revision declares a github.pull_request output (ADR 0133), or for a person's own chat on that Cloud computer, from the chat's own caveman/* branch, on the repository Cloud made the computer for, whose person GitHub confirms may push to it, on a computer no other person's work shares (ADR 0136); Cloud opens it with the GitHub App. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/pull-requests/{number}/update-head": { "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/pull-requests/{number}/update-head", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimePullRequestsNumberUpdateHead", "description": "POST /api/v1/code/runtime/pull-requests/{number}/update-head on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token, only for a person's own chat on that Cloud computer that started on that pull request (bound by pull-request-info), whose person GitHub confirms may push to the repository Cloud made the computer for, on a computer no other person's work shares; Cloud fast-forwards the pull request's own branch with the GitHub App, never forced and never a .github/workflows change (ADR 0136). Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/returns": { "get": { "summary": "GET /code/runtime/returns", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeReturns", "description": "GET /api/v1/code/runtime/returns on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/revoke": { "post": { "summary": "POST /code/runtime/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" } }, "operationId": "postCodeRuntimeRevoke", "description": "POST /api/v1/code/runtime/revoke on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/runs": { "post": { "summary": "Post a finished automation run's record", "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "run_id", "ended", "replayed", "attempts", "cost_usd" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "ended": { "type": "boolean" }, "replayed": { "type": "boolean" }, "attempts": { "type": "integer", "minimum": 0 }, "cost_usd": { "type": "number", "minimum": 0 } } } } } }, "401": { "description": "A runtime token is required." }, "403": { "description": "Not an automation's session (cave_code_session_personal)." }, "404": { "description": "Not a run of this session's automation." }, "409": { "description": "The session is on another computer, or the run already has a different record." }, "503": { "description": "The run ended but its step detail was not stored; send the same record again." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/runtime/runs on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token, and only for an org workload's session on that runtime's computer: an automation run's record when it ends, an Agents API or automation session's spans (ADR 0134). Agents authenticate through a scoped control-plane session and never touch these directly.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "automation_id", "record" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "automation_id": { "type": "string", "format": "uuid" }, "record": { "type": "object", "description": "The run record as journalled (SEMANTICS 12)." } } } } } }, "operationId": "postCodeRuntimeRuns", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/secrets": { "get": { "summary": "GET /code/runtime/secrets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeSecrets", "description": "GET /api/v1/code/runtime/secrets on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "put": { "summary": "PUT /code/runtime/secrets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeSecrets", "description": "PUT /api/v1/code/runtime/secrets on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/secrets/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/runtime/secrets/{name}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeRuntimeSecretsName", "description": "DELETE /api/v1/code/runtime/secrets/{name} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/secrets/resolve": { "post": { "summary": "POST /code/runtime/secrets/resolve", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeSecretsResolve", "description": "POST /api/v1/code/runtime/secrets/resolve on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /code/runtime/sessions/{sessionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeSessionsSessionId", "description": "PUT /api/v1/code/runtime/sessions/{sessionId} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/events": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/sessions/{sessionId}/events", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeSessionsSessionIdEvents", "description": "POST /api/v1/code/runtime/sessions/{sessionId}/events on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/files": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/sessions/{sessionId}/files", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeSessionsSessionIdFiles", "description": "GET /api/v1/code/runtime/sessions/{sessionId}/files on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/handoff": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/sessions/{sessionId}/handoff", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeSessionsSessionIdHandoff", "description": "POST /api/v1/code/runtime/sessions/{sessionId}/handoff on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/journal": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/sessions/{sessionId}/journal", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeSessionsSessionIdJournal", "description": "GET /api/v1/code/runtime/sessions/{sessionId}/journal on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "put": { "summary": "PUT /code/runtime/sessions/{sessionId}/journal", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeSessionsSessionIdJournal", "description": "PUT /api/v1/code/runtime/sessions/{sessionId}/journal on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/journal/epoch": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/sessions/{sessionId}/journal/epoch", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeSessionsSessionIdJournalEpoch", "description": "POST /api/v1/code/runtime/sessions/{sessionId}/journal/epoch on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/journal/segments/{n}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "n", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/sessions/{sessionId}/journal/segments/{n}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeSessionsSessionIdJournalSegmentsN", "description": "GET /api/v1/code/runtime/sessions/{sessionId}/journal/segments/{n} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] }, "put": { "summary": "PUT /code/runtime/sessions/{sessionId}/journal/segments/{n}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeSessionsSessionIdJournalSegmentsN", "description": "PUT /api/v1/code/runtime/sessions/{sessionId}/journal/segments/{n} on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/memory-stores": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtime/sessions/{sessionId}/memory-stores", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimeSessionsSessionIdMemoryStores", "description": "GET /api/v1/code/runtime/sessions/{sessionId}/memory-stores on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/move": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/sessions/{sessionId}/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" } }, "operationId": "postCodeRuntimeSessionsSessionIdMove", "description": "POST /api/v1/code/runtime/sessions/{sessionId}/move on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/move-check": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/sessions/{sessionId}/move-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" } }, "operationId": "postCodeRuntimeSessionsSessionIdMoveCheck", "description": "POST /api/v1/code/runtime/sessions/{sessionId}/move-check on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/outputs": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/sessions/{sessionId}/outputs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeSessionsSessionIdOutputs", "description": "POST /api/v1/code/runtime/sessions/{sessionId}/outputs on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/sessions/{sessionId}/user-events": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtime/sessions/{sessionId}/user-events", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeSessionsSessionIdUserEvents", "description": "POST /api/v1/code/runtime/sessions/{sessionId}/user-events on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/traces": { "post": { "summary": "Post an org workload's spans", "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "accepted", "spans", "project_id" ], "properties": { "accepted": { "type": "integer", "minimum": 0 }, "spans": { "type": "integer", "minimum": 0 }, "project_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Not OTLP/JSON, or spans of more than one session." }, "401": { "description": "A runtime token is required." }, "403": { "description": "A person's chat sends no traces (cave_code_session_personal)." }, "409": { "description": "The session is on another computer, or its service account has no project." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/runtime/traces on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token, and only for an org workload's session on that runtime's computer: an automation run's record when it ends, an Agents API or automation session's spans (ADR 0134). Agents authenticate through a scoped control-plane session and never touch these directly.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resourceSpans" ], "properties": { "resourceSpans": { "type": "array" } } } } } }, "operationId": "postCodeRuntimeTraces", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/usage": { "post": { "summary": "POST /code/runtime/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" } }, "operationId": "postCodeRuntimeUsage", "description": "POST /api/v1/code/runtime/usage on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/workspaces": { "post": { "summary": "POST /code/runtime/workspaces", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimeWorkspaces", "description": "POST /api/v1/code/runtime/workspaces on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Acts as the member who enrolled the laptop runtime and requires their code:write; authenticated by that runtime's Caveman Code token and rate-limited per runtime. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/workspaces/{workspaceId}/run-state": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /code/runtime/workspaces/{workspaceId}/run-state", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeWorkspacesWorkspaceIdRunState", "description": "PUT /api/v1/code/runtime/workspaces/{workspaceId}/run-state on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtime/workspaces/{workspaceId}/wake-at": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /code/runtime/workspaces/{workspaceId}/wake-at", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeRuntimeWorkspacesWorkspaceIdWakeAt", "description": "PUT /api/v1/code/runtime/workspaces/{workspaceId}/wake-at on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "runtime-token", "security": [ { "runtimeTokenAuth": [] } ] } }, "/code/runtimes": { "get": { "summary": "GET /code/runtimes", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimes", "description": "GET /api/v1/code/runtimes on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's web client lists the runtimes a person may attach to through the relay. An agent works inside a Code session and never attaches to runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] }, "post": { "summary": "POST /code/runtimes", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeRuntimes", "description": "POST /api/v1/code/runtimes on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/runtimes/{runtimeId}/attach": { "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/runtimes/{runtimeId}/attach", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeRuntimesRuntimeIdAttach", "description": "GET /api/v1/code/runtimes/{runtimeId}/attach on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's relay asks this before a person's client reaches a runtime. An agent works inside a Code session and never attaches to runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/runtimes/{runtimeId}/revoke": { "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtimes/{runtimeId}/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" } }, "operationId": "postCodeRuntimesRuntimeIdRevoke", "description": "POST /api/v1/code/runtimes/{runtimeId}/revoke on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/runtimes/{runtimeId}/token": { "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/runtimes/{runtimeId}/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" } }, "operationId": "postCodeRuntimesRuntimeIdToken", "description": "POST /api/v1/code/runtimes/{runtimeId}/token on the Caveman Cloud control plane. Authenticated by the body: an Ed25519 signature, with the runtime's enrolled key, over \"caveman-code-runtime-token/v1\\n\\n\\n\" (issued_at in Unix seconds, within 60 s of now and later than the last one used). Rate-limited per address. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token or by the enrolled key's signed assertion that mints one. Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/code/secrets": { "get": { "summary": "GET /code/secrets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeSecrets", "description": "GET /api/v1/code/secrets on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: A person's repository secrets are written by that person in the Code app. No agent connection stores, lists or deletes them; an agent in a Code session sees the names its runtime gives it and never a value (16-SECRETS.md).", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "put": { "summary": "PUT /code/secrets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeSecrets", "description": "PUT /api/v1/code/secrets on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person's repository secrets are written by that person in the Code app. No agent connection stores, lists or deletes them; an agent in a Code session sees the names its runtime gives it and never a value (16-SECRETS.md).", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/secrets/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/secrets/{name}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeSecretsName", "description": "DELETE /api/v1/code/secrets/{name} on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: A person's repository secrets are written by that person in the Code app. No agent connection stores, lists or deletes them; an agent in a Code session sees the names its runtime gives it and never a value (16-SECRETS.md).", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/service-accounts": { "get": { "summary": "List service accounts", "responses": { "200": { "description": "Service accounts", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "service_accounts" ], "properties": { "service_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/CodeServiceAccount" } } } } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeServiceAccounts", "description": "GET /api/v1/code/service-accounts on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Service accounts, their code:run keys and the organization's Code policy are a person's decisions (org:update). No agent connection mints credentials, disables an account or changes the policy.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] }, "post": { "summary": "Create a service account", "responses": { "201": { "description": "The service account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeServiceAccount" } } } }, "409": { "description": "A service account of that name exists." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/service-accounts on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Service accounts, their code:run keys and the organization's Code policy are a person's decisions (org:update). No agent connection mints credentials, disables an account or changes the policy.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "project_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": "string", "format": "uuid" } } } } } }, "operationId": "postCodeServiceAccounts", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/service-accounts/{serviceAccountId}": { "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/service-accounts/{serviceAccountId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeServiceAccountsServiceAccountId", "description": "GET /api/v1/code/service-accounts/{serviceAccountId} on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Service accounts, their code:run keys and the organization's Code policy are a person's decisions (org:update). No agent connection mints credentials, disables an account or changes the policy.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/service-accounts/{serviceAccountId}/access-log": { "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/service-accounts/{serviceAccountId}/access-log", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeServiceAccountsServiceAccountIdAccessLog", "description": "GET /api/v1/code/service-accounts/{serviceAccountId}/access-log on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: The vault holds a service account's credentials and the repository secrets people grant it. A person with org:update stores, grants, lists and removes them; values are write-only and reach only the computers running that account's sessions. No agent connection reads or changes them.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/service-accounts/{serviceAccountId}/credentials": { "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/service-accounts/{serviceAccountId}/credentials", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeServiceAccountsServiceAccountIdCredentials", "description": "GET /api/v1/code/service-accounts/{serviceAccountId}/credentials on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: The vault holds a service account's credentials and the repository secrets people grant it. A person with org:update stores, grants, lists and removes them; values are write-only and reach only the computers running that account's sessions. No agent connection reads or changes them.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] }, "post": { "summary": "POST /code/service-accounts/{serviceAccountId}/credentials", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeServiceAccountsServiceAccountIdCredentials", "description": "POST /api/v1/code/service-accounts/{serviceAccountId}/credentials on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: The vault holds a service account's credentials and the repository secrets people grant it. A person with org:update stores, grants, lists and removes them; values are write-only and reach only the computers running that account's sessions. No agent connection reads or changes them.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/service-accounts/{serviceAccountId}/credentials/{credentialId}": { "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/service-accounts/{serviceAccountId}/credentials/{credentialId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeServiceAccountsServiceAccountIdCredentialsCredentialId", "description": "DELETE /api/v1/code/service-accounts/{serviceAccountId}/credentials/{credentialId} on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: The vault holds a service account's credentials and the repository secrets people grant it. A person with org:update stores, grants, lists and removes them; values are write-only and reach only the computers running that account's sessions. No agent connection reads or changes them.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/service-accounts/{serviceAccountId}/disable": { "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/service-accounts/{serviceAccountId}/disable", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeServiceAccountsServiceAccountIdDisable", "description": "POST /api/v1/code/service-accounts/{serviceAccountId}/disable on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Service accounts, their code:run keys and the organization's Code policy are a person's decisions (org:update). No agent connection mints credentials, disables an account or changes the policy.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/service-accounts/{serviceAccountId}/keys": { "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/service-accounts/{serviceAccountId}/keys", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeServiceAccountsServiceAccountIdKeys", "description": "GET /api/v1/code/service-accounts/{serviceAccountId}/keys on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Service accounts, their code:run keys and the organization's Code policy are a person's decisions (org:update). No agent connection mints credentials, disables an account or changes the policy.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] }, "post": { "summary": "Mint a code:run key for a service account", "responses": { "201": { "description": "The key, with full_key shown once" }, "409": { "description": "The account is disabled." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/service-accounts/{serviceAccountId}/keys on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Service accounts, their code:run keys and the organization's Code policy are a person's decisions (org:update). No agent connection mints credentials, disables an account or changes the policy.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": { "name": { "type": "string", "maxLength": 100 }, "expires_in_days": { "type": "integer", "minimum": 0, "maximum": 3650 } } } } } }, "operationId": "postCodeServiceAccountsServiceAccountIdKeys", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/service-accounts/{serviceAccountId}/keys/{keyId}": { "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /code/service-accounts/{serviceAccountId}/keys/{keyId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteCodeServiceAccountsServiceAccountIdKeysKeyId", "description": "DELETE /api/v1/code/service-accounts/{serviceAccountId}/keys/{keyId} on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Service accounts, their code:run keys and the organization's Code policy are a person's decisions (org:update). No agent connection mints credentials, disables an account or changes the policy.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/service-accounts/{serviceAccountId}/repo-secrets": { "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/service-accounts/{serviceAccountId}/repo-secrets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeServiceAccountsServiceAccountIdRepoSecrets", "description": "GET /api/v1/code/service-accounts/{serviceAccountId}/repo-secrets on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: The vault holds a service account's credentials and the repository secrets people grant it. A person with org:update stores, grants, lists and removes them; values are write-only and reach only the computers running that account's sessions. No agent connection reads or changes them.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] }, "put": { "summary": "PUT /code/service-accounts/{serviceAccountId}/repo-secrets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putCodeServiceAccountsServiceAccountIdRepoSecrets", "description": "PUT /api/v1/code/service-accounts/{serviceAccountId}/repo-secrets on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: The vault holds a service account's credentials and the repository secrets people grant it. A person with org:update stores, grants, lists and removes them; values are write-only and reach only the computers running that account's sessions. No agent connection reads or changes them.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/code/sessions": { "get": { "summary": "List Caveman Code sessions", "responses": { "200": { "description": "Sessions, newest first", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/CodeSession" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only this workspace's sessions." }, { "name": "origin", "in": "query", "required": false, "schema": { "enum": [ "person", "api", "automation" ] }, "description": "Only sessions of this origin." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only sessions running this agent." } ], "description": "GET /api/v1/code/sessions on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "operationId": "getCodeSessions", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "Start a Caveman Code session", "responses": { "201": { "description": "The session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeSession" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "409": { "description": "Paused (cave_code_paused), archived agent, no Cloud computers here, or the computer limit." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/sessions on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "repo", "task" ], "properties": { "request_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Idempotent per caller: a retry returns the session the first call started." }, "agent": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } } } ] }, "repo": { "type": "string", "description": "owner/name: the repository the session's computer checks out." }, "base_branch": { "type": "string" }, "task": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "The first user message." }, "title": { "type": "string", "maxLength": 200 }, "engine": { "enum": [ "caveman", "claude-agent", "codex" ] }, "model": { "type": "string", "maxLength": 200, "description": "A model id or a class: fast, base, frontier or auto." }, "budget_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "computer": { "type": "object", "additionalProperties": false, "required": [], "properties": { "size": { "type": "string", "pattern": "^[1-9][0-9]?cpu-[1-9][0-9]{0,3}gb$" } } }, "files": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "memory_stores": { "type": "array", "maxItems": 8, "items": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string" }, "access": { "enum": [ "read_write", "read_only" ] } } } }, "metadata": { "type": "object", "maxProperties": 16, "additionalProperties": { "type": "string", "maxLength": 512 } } } } } } }, "operationId": "postCodeSessions", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read a Caveman Code session", "responses": { "200": { "description": "The session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeSession" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "Not a session this caller may see." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeSessionsSessionId", "description": "GET /api/v1/code/sessions/{sessionId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/sessions/{sessionId}/events": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read a session's events", "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/CodeSessionEvent" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "Not a session this caller may see." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Return events after this seq (or send Last-Event-ID)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "At most this many events (500)." } ], "description": "GET /api/v1/code/sessions/{sessionId}/events on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "operationId": "getCodeSessionsSessionIdEvents", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "Send an event to a running session", "responses": { "200": { "description": "The mail the event became", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeMail" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "Not a session this caller may drive." }, "409": { "description": "The session ended, or its budget is spent." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/code/sessions/{sessionId}/events on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "type" ], "properties": { "request_id": { "type": "string", "minLength": 1, "maxLength": 150 }, "type": { "enum": [ "user.message", "user.interrupt", "user.approval", "user.answer", "user.tool_result" ] }, "text": { "type": "string" }, "ask_id": { "type": "string" }, "decision": { "enum": [ "allow", "deny" ] }, "message": { "type": "string" }, "content": { "type": "string" }, "is_error": { "type": "boolean" } } } } } }, "operationId": "postCodeSessionsSessionIdEvents", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/sessions/{sessionId}/events/stream": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Stream a session's events", "responses": { "200": { "description": "An event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "Not a session this caller may see." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Return events after this seq (or send Last-Event-ID)." } ], "description": "GET /api/v1/code/sessions/{sessionId}/events/stream on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: The Agents API is driven by a service account's code:run key, or by a person in the Code app and console. An agent connection works inside a Code session and never starts, lists or drives Code sessions or agents from a control-plane connection.", "operationId": "getCodeSessionsSessionIdEventsStream", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/sessions/{sessionId}/files": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List a session's files", "responses": { "200": { "description": "The session's files", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/CodeFile" } } } } } } }, "401": { "description": "A person's sign-in or a code:run key is required." }, "403": { "description": "The role, the key's scope, or an inactive service account (cave_code_service_account_inactive) refuses." }, "404": { "description": "No such session the caller sees." }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "GET /api/v1/code/sessions/{sessionId}/files on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code files are the org's inputs for sessions and the outputs sessions wrote, uploaded and read through the Agents API by a person or a service account's key. An agent in a session reads its attached files at /mnt/session/uploads and writes /mnt/session/outputs through its runtime, never through a control-plane connection.", "operationId": "getCodeSessionsSessionIdFiles", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/spend": { "get": { "summary": "GET /code/spend", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeSpend", "description": "GET /api/v1/code/spend on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/telemetry/latency": { "post": { "summary": "POST /code/telemetry/latency", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeTelemetryLatency", "description": "POST /api/v1/code/telemetry/latency on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Client telemetry transport, not an MCP tool: a person's Code device posts how fast it saw their own chats, as it measured it (ADR 0135). It reads nothing and grants nothing.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/workspaces": { "get": { "summary": "GET /code/workspaces", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeWorkspaces", "description": "GET /api/v1/code/workspaces on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] }, "post": { "summary": "POST /code/workspaces", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeWorkspaces", "description": "POST /api/v1/code/workspaces on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/workspaces/{workspaceId}": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /code/workspaces/{workspaceId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getCodeWorkspacesWorkspaceId", "description": "GET /api/v1/code/workspaces/{workspaceId} on the Caveman Cloud control plane. Requires the code:read scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:read" ] } }, "/code/workspaces/{workspaceId}/archive": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /code/workspaces/{workspaceId}/archive", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postCodeWorkspacesWorkspaceIdArchive", "description": "POST /api/v1/code/workspaces/{workspaceId}/archive on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/code/workspaces/{workspaceId}/budget": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /code/workspaces/{workspaceId}/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" } }, "operationId": "putCodeWorkspacesWorkspaceIdBudget", "description": "PUT /api/v1/code/workspaces/{workspaceId}/budget on the Caveman Cloud control plane. Requires the code:write scope. Not exposed to autonomous agents: Caveman Code's registry is driven by the Code app and the runtimes it enrolls. An agent works inside a Code session and reaches its tree through the session mailbox, never by listing, starting or archiving workspaces or enrolling runtimes from a control-plane connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "code:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "code:write" ] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "context.data_source_catalog", "x-caveman-operation-contract": "203b024984d3ca53049a976bdafe546519a0026dc4bf78806d126ca9d02b2fb7", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/dev/agents": { "get": { "summary": "GET /dev/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" } }, "operationId": "getDevAgents", "description": "GET /api/v1/dev/agents on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the dev_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.", "x-caveman-operation": "reports.dev_agents", "x-caveman-operation-contract": "2be328ef3f9d8965204fecfa1836318f2988f4981730e33a9dd054e6bbb12113", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/eval-cells/{cellId}": { "parameters": [ { "name": "cellId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /eval-cells/{cellId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getEvalCellsCellId", "description": "GET /api/v1/eval-cells/{cellId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the open_cell action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.open_cell", "x-caveman-operation-contract": "9cf8e648db4da96d4cbe50d433574acc73ad3677a0c2166f70557c3762307a09", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.list_evidence", "x-caveman-operation-contract": "6dcbc41de14fc14c1b1e4973533f7472c9e1978dcdc84caed5fdedc44424396f", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "trace_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.ingest_evidence", "x-caveman-operation-contract": "999dd7ee98ff540525b0d2e94f11cc75293ff48ccfcc7158a48a40278b483307", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "dry_run": { "type": "boolean" }, "items": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "additionalProperties": false, "properties": { "observed_at": { "type": "string" }, "result_at": { "type": "string" }, "trace_id": { "type": "string" }, "span_id": { "type": "string" }, "response_id": { "type": "string" }, "source_system": { "type": "string" }, "source_run_id": { "type": "string" }, "source_suite_id": { "type": "string" }, "source_case_id": { "type": "string" }, "source_result_id": { "type": "string" }, "ingestion_id": { "type": "string" }, "evaluator_name": { "type": "string" }, "evaluator_type": { "type": "string" }, "evaluator_version": { "type": "string" }, "evaluator_config_digest": { "type": "string" }, "status": { "enum": [ "processed", "skipped", "error" ] }, "fault": { "type": "string" }, "score_label": { "type": "string" }, "explanation": { "type": "string" }, "explanation_artifact_ref": { "type": "string" }, "payload_digest": { "type": "string" }, "fixture_digest": { "type": "string" }, "completeness": { "enum": [ "complete", "partial", "unknown" ] }, "idempotency_key": { "type": "string" }, "passed": { "type": [ "boolean", "null" ] }, "score": { "type": [ "number", "null" ] }, "score_min": { "type": [ "number", "null" ] }, "score_max": { "type": [ "number", "null" ] } }, "required": [ "observed_at", "result_at", "source_system", "evaluator_name", "evaluator_type", "evaluator_version", "evaluator_config_digest", "status", "completeness", "idempotency_key" ] } }, "project_id": { "type": "string", "format": "uuid" } }, "required": [ "items", "project_id" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/eval-runs/{runId}": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /eval-runs/{runId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getEvalRunsRunId", "description": "GET /api/v1/eval-runs/{runId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the open_run action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.open_run", "x-caveman-operation-contract": "e391800447c8b908772facc2771f9615478e91c13434cdbac0855b60e033bf20", "parameters": [ { "name": "row_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_key", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/eval-runs/{runId}/export.jsonl": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /eval-runs/{runId}/export.jsonl", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getEvalRunsRunIdExportJsonl", "description": "GET /api/v1/eval-runs/{runId}/export.jsonl on the Caveman Cloud control plane. Requires the payload:read scope. Not exposed to autonomous agents: Exports authored inputs and model outputs as a tenant-data download. Bulk data egress requires a human actor.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/eval-runs/{runId}/results": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /eval-runs/{runId}/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" } }, "operationId": "getEvalRunsRunIdResults", "description": "GET /api/v1/eval-runs/{runId}/results on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the query_results action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.query_results", "x-caveman-operation-contract": "e7266324965c15e4f273460ae448f805d7657e9ab1e21c6c6ef078eb2bd74cd1", "parameters": [ { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "criterion", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "verdict", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "change", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "baseline_run_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "baseline_target_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "score_min", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "score_max", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/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" } }, "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). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.list_suites", "x-caveman-operation-contract": "2eb5fd849e60497faad95b7ea13c59803bfcf8dec9deb3a526155287e54c178f", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.create_suite", "x-caveman-operation-contract": "e27785e1a62f72eda9571389eb23d36f46f56efde4705bebd350b6163dc0e899", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.get_suite", "x-caveman-operation-contract": "4859b6edf58523536afd42fa7751d48add007cf57743fce9d8e6986c21f642e0", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.update_suite", "x-caveman-operation-contract": "812c12b8a1387445abc31c1ada470bb733d246177bf5b419ab89d49cedc5e303", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "enum": [ "draft", "active", "archived" ] } }, "required": [ "name", "status" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.list_cases", "x-caveman-operation-contract": "598d2621fee126736ee8641603eae046977ab005355ba6087a969fd4b99afc18", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /eval-suites/{suiteId}/cases", "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" } }, "operationId": "postEvalSuitesSuiteIdCases", "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). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.add_case", "x-caveman-operation-contract": "969a9b4a41ac23db10cfac8e685559a5d0182280453b563ef8f7aa57e4c98677", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "fixture": {}, "fixture_sha256": { "type": "string" }, "fixture_storage_key": { "type": "string" }, "graders": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "options": {}, "type": { "type": "string" } } } }, "graders_json": {}, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.replace_cases", "x-caveman-operation-contract": "39722b8bb1d055e0f8a92d69079f16962498d63b2b69b0ddc48dd11f45041822", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "cases": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "fixture": {}, "graders": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "options": {}, "type": { "type": "string" } } } }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "minItems": 1, "maxItems": 200 } }, "required": [ "cases" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.run_baseline", "x-caveman-operation-contract": "fbeae0cd4c21244ea41e91854d6ec4836449567e02eaaaeb80e89cb87b4e9bc3", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "experiments.list", "x-caveman-operation-contract": "ccc6d4394db9f587383391371e91fe39db126893d0ec16b7685b9d3094ea0d31", "parameters": [ { "name": "workflow", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "eval_suite_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "experiments.create", "x-caveman-operation-contract": "43b61851a6ba3f424e3f1b1514e02a36d2cf12d47f6d6b37bd7251f60e3e07a0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "baseline_config": {}, "candidate_config": {}, "eval_suite_id": { "type": "string" }, "guardrails": {}, "name": { "type": "string" }, "opportunity_id": { "type": "string" }, "practice_id": { "type": "string" }, "type": { "enum": [ "replay", "shadow", "canary", "density-canary", "before_after" ] } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "experiments.get", "x-caveman-operation-contract": "967fcaa4861fe70c8d6714d72b51c642b8ad154f1d3309d0758e50b8cbda1e4b", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "experiments.cancel", "x-caveman-operation-contract": "5f3ac939e9aeb2d779a2b217ab6135ddc27f1ac3711b78351ef8c84f3a8632ec", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "experiments.results", "x-caveman-operation-contract": "fbb24b583218cfd4d2c4599bdde4608d3df7e5254cf83aa06c554af04b0e740d", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "experiments.runs", "x-caveman-operation-contract": "e41853b257a5ff006ab993d44daeb4e38213d447946afa60a0a55074a3ca0d2a", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "experiments.start", "x-caveman-operation-contract": "4acda219c7f6aa9e9981dce38b7249fcc9f24564761dce438f59996937909bbd", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/filters/fields": { "get": { "summary": "GET /filters/fields", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getFiltersFields", "description": "GET /api/v1/filters/fields on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the filter_fields action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.filter_fields", "x-caveman-operation-contract": "76e5b6f9c5ca63b187cb25866c64837b2e3735b5a09dc8947887916fd892670a", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/github/admin-proof/callback": { "get": { "summary": "GET /github/admin-proof/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" } }, "operationId": "getGithubAdminProofCallback", "description": "GET /api/v1/github/admin-proof/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 — it is the browser redirect that carries a GitHub user authorization back to this installation. The proof it records is about a human's repository administration, so only that human's browser can complete it.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/imports/gateway-config": { "post": { "summary": "POST /imports/gateway-config", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postImportsGatewayConfig", "description": "POST /api/v1/imports/gateway-config on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Reads another gateway's configuration and, on apply, mints credentials, invites members and rewrites the admission policy. Every one of those is a human decision, and the source file can carry provider secrets.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/inbox/items": { "get": { "summary": "GET /inbox/items", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getInboxItems", "description": "GET /api/v1/inbox/items on the Caveman Cloud control plane. Requires the inbox:read scope. Exposed to autonomous agents as the list action of the caveman_inbox tool (read access). What Caveman noticed, did, and needs decided — the organization's decision queue.", "x-caveman-operation": "inbox.list", "x-caveman-operation-contract": "41eb23675ac5b841afd13a0eea6ea43a91b3ad647e52584f4a0789eebf18c1d9", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workflow", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "inbox:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "inbox:read" ] }, "post": { "summary": "POST /inbox/items", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postInboxItems", "description": "POST /api/v1/inbox/items on the Caveman Cloud control plane. Requires the inbox:write scope. Exposed to autonomous agents as the emit action of the caveman_inbox_write tool (write access). Emit an inbox item from an agent run, and archive/resolve/act on items.", "x-caveman-operation": "inbox.emit", "x-caveman-operation-contract": "e054377c1a88dd438a76a0c182a25984dcdfd72677be31d74e11be13db89b347", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "actions": { "type": "array", "items": {} }, "artifacts": { "type": "array", "items": {} }, "data": { "type": "object", "additionalProperties": false, "properties": { "workflow": { "type": "string", "pattern": "^[a-z0-9_-]{1,200}$" } } }, "dedupe_key": { "type": "string" }, "href": { "type": "string" }, "kind": { "type": "string" }, "occurred_at": { "type": "string" }, "priority": { "type": "integer" }, "ref_id": { "type": "string" }, "ref_type": { "type": "string" }, "scope": { "type": "string" }, "source": { "type": "string" }, "summary": { "type": "string" }, "title": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" } }, "required": [ "project_id" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "inbox:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "inbox:write" ] } }, "/inbox/items/{itemId}": { "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /inbox/items/{itemId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getInboxItemsItemId", "description": "GET /api/v1/inbox/items/{itemId} on the Caveman Cloud control plane. Requires the inbox:read scope. Exposed to autonomous agents as the get action of the caveman_inbox tool (read access). What Caveman noticed, did, and needs decided — the organization's decision queue.", "x-caveman-operation": "inbox.get", "x-caveman-operation-contract": "3a6bbdca65f51205867950222466910446e44ce3d2e6f47289898e7bba6800ba", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "inbox:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "inbox:read" ] } }, "/inbox/items/{itemId}/actions/{actionKey}": { "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /inbox/items/{itemId}/actions/{actionKey}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postInboxItemsItemIdActionsActionKey", "description": "POST /api/v1/inbox/items/{itemId}/actions/{actionKey} on the Caveman Cloud control plane. Requires the inbox:write scope. Exposed to autonomous agents as the act action of the caveman_inbox_write tool (write access). Emit an inbox item from an agent run, and archive/resolve/act on items.", "x-caveman-operation": "inbox.act", "x-caveman-operation-contract": "c7e2ef3dc68701ed674ebdf8a9f8453be6fa314bf49da1741fdba0b8599fb0cf", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "inbox:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "inbox:write" ] } }, "/inbox/summary": { "get": { "summary": "GET /inbox/summary", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getInboxSummary", "description": "GET /api/v1/inbox/summary on the Caveman Cloud control plane. Requires the inbox:read scope. Exposed to autonomous agents as the summary action of the caveman_inbox tool (read access). What Caveman noticed, did, and needs decided — the organization's decision queue.", "x-caveman-operation": "inbox.summary", "x-caveman-operation-contract": "6102dc525bc5cfc29b342948c9a59ba9afad2288f5eb0fb5d1dc708db9bceaef", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "inbox:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "inbox:read" ] } }, "/integrations/{provider}/events": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /integrations/{provider}/events", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postIntegrationsProviderEvents", "description": "POST /api/v1/integrations/{provider}/events 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 — authenticated by the request's own signature: the automation's hook secret, or the Slack, Linear or Jira signing secret the installation holds (ADR 0133). Agents authenticate through a scoped control-plane session and never touch these directly.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/join/link/accept": { "post": { "summary": "POST /join/link/accept", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postJoinLinkAccept", "description": "POST /api/v1/join/link/accept 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/join/link/inspect": { "post": { "summary": "POST /join/link/inspect", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postJoinLinkInspect", "description": "POST /api/v1/join/link/inspect 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: Public invite-link inspection before sign-in; not RBAC-guarded and part of the authentication plane. Agents authenticate through a scoped control-plane session and never touch it.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/join/start": { "post": { "summary": "POST /join/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" } }, "operationId": "postJoinStart", "description": "POST /api/v1/join/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: Public request for a join confirmation email before sign-in; not RBAC-guarded and part of the authentication plane. Agents authenticate through a scoped control-plane session and never touch it.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/me/chatgpt": { "delete": { "summary": "DELETE /me/chatgpt", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteMeChatgpt", "description": "DELETE /api/v1/me/chatgpt on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Links or unlinks a person's own ChatGPT plan, which pays for their agent runs. A person grants that in a browser; an agent must never be able to widen what pays for its own work.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "get": { "summary": "GET /me/chatgpt", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getMeChatgpt", "description": "GET /api/v1/me/chatgpt on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Links or unlinks a person's own ChatGPT plan, which pays for their agent runs. A person grants that in a browser; an agent must never be able to widen what pays for its own work.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/me/chatgpt/authorize": { "post": { "summary": "POST /me/chatgpt/authorize", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postMeChatgptAuthorize", "description": "POST /api/v1/me/chatgpt/authorize on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Links or unlinks a person's own ChatGPT plan, which pays for their agent runs. A person grants that in a browser; an agent must never be able to widen what pays for its own work.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/me/chatgpt/callback": { "get": { "summary": "GET /me/chatgpt/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" } }, "operationId": "getMeChatgptCallback", "description": "GET /api/v1/me/chatgpt/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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [] } }, "/me/delivery": { "get": { "summary": "GET /me/delivery", "responses": { "200": { "description": "Window-scoped delivery evidence. Costs exclude ambiguous joins and incomplete pricing; contribution details disclose truncation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryReport" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "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.", "x-caveman-operation": "people.my_delivery", "x-caveman-operation-contract": "12f865f7f72f97af6eb91b5d80692e90b3afdf7bf0a6248bcc3c7f58822c135b", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/me/joinable-organizations": { "get": { "summary": "GET /me/joinable-organizations", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getMeJoinableOrganizations", "description": "GET /api/v1/me/joinable-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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/me/joinable-organizations/{organizationId}/join": { "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /me/joinable-organizations/{organizationId}/join", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postMeJoinableOrganizationsOrganizationIdJoin", "description": "POST /api/v1/me/joinable-organizations/{organizationId}/join 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:self" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "key:self" ] } }, "/me/sessions": { "get": { "summary": "GET /me/sessions", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getMeSessions", "description": "GET /api/v1/me/sessions on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the my_sessions 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.", "x-caveman-operation": "people.my_sessions", "x-caveman-operation-contract": "22504537057acb2901bf20dfe71a965bda158abc6444b9593440fc589e2752a9", "parameters": [ { "name": "agent", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "member_user_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "snapshot", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "work_type", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/me/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /me/sessions/{sessionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getMeSessionsSessionId", "description": "GET /api/v1/me/sessions/{sessionId} on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the my_session 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.", "x-caveman-operation": "people.my_session", "x-caveman-operation-contract": "b4815914417d1b0dfb92e741e5a3047e696029d98fd11f0490bddc2276343836", "parameters": [ { "name": "agent", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "member_user_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "snapshot", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "work_type", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/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" } }, "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.", "x-caveman-operation": "people.my_usage", "x-caveman-operation-contract": "4da1410a65a20063fc3d0555570332f0f188f07a8cd2671139c2851358e6d585", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:self" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/oauth/authorize": { "get": { "summary": "GET /oauth/authorize", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOauthAuthorize", "description": "GET /api/v1/oauth/authorize 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: OAuth credential and consent ceremony. Only verified human approval and registered client proof may create or revoke this resource connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] }, "post": { "summary": "POST /oauth/authorize", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postOauthAuthorize", "description": "POST /api/v1/oauth/authorize on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: OAuth credential and consent ceremony. Only verified human approval and registered client proof may create or revoke this resource connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/oauth/revoke": { "post": { "summary": "POST /oauth/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" } }, "operationId": "postOauthRevoke", "description": "POST /api/v1/oauth/revoke 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: OAuth credential and consent ceremony. Only verified human approval and registered client proof may create or revoke this resource connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/oauth/token": { "post": { "summary": "POST /oauth/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" } }, "operationId": "postOauthToken", "description": "POST /api/v1/oauth/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: OAuth credential and consent ceremony. Only verified human approval and registered client proof may create or revoke this resource connection.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "endpoint-specific", "security": [] } }, "/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" } }, "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.", "x-caveman-operation": "fixes.list_opportunities", "x-caveman-operation-contract": "0ce96d7f3805e3e04ed330f85988c83d0b8fde75616fa795f594ab2eee9c6752", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "fixes.get_opportunity", "x-caveman-operation-contract": "fa44aff71c652b883e1643cd648356cc8673947ce1e831a2cea1595ddd051c7f", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Dismiss or mark opportunities implemented, create an experiment from an opportunity, record outcomes, and submit practice findings. Legacy optimization proposal creation is retired.", "x-caveman-operation": "fixes.create_experiment", "x-caveman-operation-contract": "6a4a8df5711c38308820ba30723993b142367fb8fbe19234edd56b98accbe803", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "baseline_config": {}, "candidate_config": {}, "eval_suite_id": { "type": "string" }, "guardrails": {}, "name": { "type": "string" }, "opportunity_id": { "type": "string", "format": "uuid" }, "practice_id": { "type": "string" }, "type": { "enum": [ "replay", "shadow", "canary", "density-canary", "before_after" ] } }, "required": [ "opportunity_id" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Dismiss or mark opportunities implemented, create an experiment from an opportunity, record outcomes, and submit practice findings. Legacy optimization proposal creation is retired.", "x-caveman-operation": "fixes.dismiss_opportunity", "x-caveman-operation-contract": "929efc11df1e060e398973eba93d1105cbf7723dc6f398ba2417b5439340b19e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Dismiss or mark opportunities implemented, create an experiment from an opportunity, record outcomes, and submit practice findings. Legacy optimization proposal creation is retired.", "x-caveman-operation": "fixes.mark_implemented", "x-caveman-operation-contract": "85d4d8de26126766f58b06cbf1437362ecb7d32a2a6d4f53cb783b635bd915a7", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "proposals.list", "x-caveman-operation-contract": "68bad9ded3dc8574508bc5e5ad9e5350310f8baa2969f0b3b93720692fffea08", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/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" } }, "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.", "x-caveman-operation": "proposals.get", "x-caveman-operation-contract": "65f699cb84a717bb6e74eed3f4170231ba4766823ce82b95983f778269f00651", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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: The proposal-keyed spelling of the local fix lane's evidence, driven by `caveman agent submit` and gated on proposal:draft, which an MCP agent connection is never granted (only the onboarding wizard's connection holds it). An agent reports the same bundle by brief (briefs.fix_report): an agent grading its own work is exactly why the server labels it self_reported and caps it at candidate.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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: The proposal-keyed spelling of the local fix lane, driven by `caveman agent pull` and gated on proposal:draft, which an MCP agent connection is never granted (only the onboarding wizard's connection holds it). An agent pulls the same packet by brief (briefs.fix_packet); the GitHub App token this route mints to resolve the base commit never leaves the server.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/optimization-proposals/{proposalId}/reject": { "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Reject a proposal with an immutable review receipt", "responses": { "200": { "description": "Proposal rejected, or an exact retry returned the original immutable decision receipt.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "learning_recorded", "decision_receipt" ], "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "status": { "const": "rejected" }, "learning_recorded": { "type": "boolean", "description": "Explicit learning outcome; false means no typed learning feedback was recorded." }, "decision_receipt": { "type": "object", "additionalProperties": false, "required": [ "id", "project_id", "proposal_id", "decision_generation", "decision", "idempotency_key", "actor_user_id", "reason_domain", "reason_code", "predecessor_status", "learning_recorded", "receipt_origin", "decided_at", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "project_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "proposal_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "decision_generation": { "type": "integer", "minimum": 1 }, "decision": { "const": "rejected" }, "idempotency_key": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "actor_user_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "reason_domain": { "type": "string", "enum": [ "quality", "security", "scope", "cost", "stale_knowledge", "human_preference", "duplicate", "unsupported", "policy" ] }, "reason_code": { "type": "string", "enum": [ "quality_risk", "security_risk", "scope_too_broad", "cost_not_justified", "stale_knowledge", "human_preference", "duplicate_change", "unsupported_change", "policy_conflict" ] }, "predecessor_status": { "type": "string", "enum": [ "drafting", "proposed", "pr_open" ] }, "learning_recorded": { "type": "boolean", "description": "True only when the same transaction recorded typed human_rejected feedback against an immutable optimization-technique binding." }, "receipt_origin": { "const": "api" }, "decided_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Missing, malformed, non-canonical, unknown, or trailing request input" }, "404": { "description": "Proposal not found in the caller's tenant scope" }, "409": { "description": "Illegal predecessor or a mismatched immutable review decision" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postOptimizationProposalsProposalIdReject", "description": "POST /api/v1/optimization-proposals/{proposalId}/reject on the Caveman Cloud control plane. Requires the proposal:draft scope. Not exposed to autonomous agents: Records a human rejection reason and feeds it into optimization learning. Agent access would let the optimizer impersonate its reviewer and poison its own feedback signal. The client supplies one stable canonical UUID per human decision and a closed reason code; exact retries return the same receipt without another transition or audit row.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "idempotency_key", "reason_code" ], "properties": { "idempotency_key": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Stable client decision identity. Reuse after an uncertain network result; rotate after success, conflict, cancellation, or a new decision." }, "reason_code": { "type": "string", "enum": [ "quality_risk", "security_risk", "scope_too_broad", "cost_not_justified", "stale_knowledge", "human_preference", "duplicate_change", "unsupported_change", "policy_conflict" ] } } } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "fixes.proposal_runs", "x-caveman-operation-contract": "beccabd93c0c437d26ae48b5b537ec2d3900a0379fb26d85465c0a528c54125b", "parameters": [ { "name": "after_seq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/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" } }, "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.", "x-caveman-operation": "context.get_org", "x-caveman-operation-contract": "6f1518c098e5b10aecb89c9ac692e43bf86c46214cc97ac4e39ad71bbfb3fabc", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "policy.consent_status", "x-caveman-operation-contract": "2b61e8cd850456b1b55d3ff9e7f504bc8f562b411216186f161d91031cf0d5c3", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:delete" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:delete" ] } }, "/org/domains": { "get": { "summary": "GET /org/domains", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOrgDomains", "description": "GET /api/v1/org/domains on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Changes who may join the organization and how (invite link, approved domains, join role, who can invite, required SSO). An agent proposes; a human decides, because a wrong setting opens the organization to people it did not choose.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] }, "post": { "summary": "POST /org/domains", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postOrgDomains", "description": "POST /api/v1/org/domains on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Changes who may join the organization and how (invite link, approved domains, join role, who can invite, required SSO). An agent proposes; a human decides, because a wrong setting opens the organization to people it did not choose.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/org/domains/{domainId}": { "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /org/domains/{domainId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteOrgDomainsDomainId", "description": "DELETE /api/v1/org/domains/{domainId} on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Changes who may join the organization and how (invite link, approved domains, join role, who can invite, required SSO). An agent proposes; a human decides, because a wrong setting opens the organization to people it did not choose.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] }, "patch": { "summary": "PATCH /org/domains/{domainId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchOrgDomainsDomainId", "description": "PATCH /api/v1/org/domains/{domainId} on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Changes who may join the organization and how (invite link, approved domains, join role, who can invite, required SSO). An agent proposes; a human decides, because a wrong setting opens the organization to people it did not choose.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/org/domains/{domainId}/verify": { "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /org/domains/{domainId}/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" } }, "operationId": "postOrgDomainsDomainIdVerify", "description": "POST /api/v1/org/domains/{domainId}/verify on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Changes who may join the organization and how (invite link, approved domains, join role, who can invite, required SSO). An agent proposes; a human decides, because a wrong setting opens the organization to people it did not choose.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/org/github/app": { "get": { "summary": "GET /org/github/app", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOrgGithubApp", "description": "GET /api/v1/org/github/app on the Caveman Cloud control plane. Requires the settings:read scope. Not exposed to autonomous agents: The organization's own GitHub App identity: app id, slug, owner and key revision. An agent has no reason to inspect the customer's registration, and the endpoint carries no credential it could use.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/org/github/app-manifest": { "post": { "summary": "POST /org/github/app-manifest", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postOrgGithubAppManifest", "description": "POST /api/v1/org/github/app-manifest on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Creates the manifest an organization owner posts to their own GitHub account. Registering the customer's App is an account permission ceremony a person performs in a browser; an agent can neither approve it nor hold its key.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/org/github/app-manifest/complete": { "post": { "summary": "POST /org/github/app-manifest/complete", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postOrgGithubAppManifestComplete", "description": "POST /api/v1/org/github/app-manifest/complete on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Exchanges the one-use registration code for the customer's App and stores its private key and secrets under this installation's secret provider. Nothing about this step is delegable: an agent must never be able to introduce a source identity.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/org/invite-link/reset": { "post": { "summary": "POST /org/invite-link/reset", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postOrgInviteLinkReset", "description": "POST /api/v1/org/invite-link/reset on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Changes who may join the organization and how (invite link, approved domains, join role, who can invite, required SSO). An agent proposes; a human decides, because a wrong setting opens the organization to people it did not choose.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/org/join-settings": { "get": { "summary": "GET /org/join-settings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOrgJoinSettings", "description": "GET /api/v1/org/join-settings on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Changes who may join the organization and how (invite link, approved domains, join role, who can invite, required SSO). An agent proposes; a human decides, because a wrong setting opens the organization to people it did not choose.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "patch": { "summary": "PATCH /org/join-settings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchOrgJoinSettings", "description": "PATCH /api/v1/org/join-settings on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Changes who may join the organization and how (invite link, approved domains, join role, who can invite, required SSO). An agent proposes; a human decides, because a wrong setting opens the organization to people it did not choose.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/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" } }, "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.", "x-caveman-operation": "people.list_members", "x-caveman-operation-contract": "bfaf11c041f9f811f20ec7a095b589bf68ccd1d706e66bde3d8b8397fd65b33f", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/org/members/{membershipId}/resend-invite": { "parameters": [ { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /org/members/{membershipId}/resend-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" } }, "operationId": "postOrgMembersMembershipIdResendInvite", "description": "POST /api/v1/org/members/{membershipId}/resend-invite 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/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" } }, "operationId": "postOrgMembersInvite", "description": "POST /api/v1/org/members/invite 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/org/redaction-rules": { "get": { "summary": "GET /org/redaction-rules", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOrgRedactionRules", "description": "GET /api/v1/org/redaction-rules on the Caveman Cloud control plane. Requires the settings:read scope. Exposed to autonomous agents as the org_redaction_rules action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "x-caveman-operation": "policy.org_redaction_rules", "x-caveman-operation-contract": "4ec475fec6955254799af084c3d6ae9bb6365eff27b4ade3b5e0cd38c4286b4c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] }, "post": { "summary": "POST /org/redaction-rules", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postOrgRedactionRules", "description": "POST /api/v1/org/redaction-rules on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Changes what is masked out of captured payloads before storage. A wrong rule silently stops redacting; a human owns that decision.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/org/redaction-rules/{ruleId}": { "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /org/redaction-rules/{ruleId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteOrgRedactionRulesRuleId", "description": "DELETE /api/v1/org/redaction-rules/{ruleId} on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Removes a rule that masks data out of captured payloads. A wrong deletion silently stops redacting; a human owns that decision.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] }, "patch": { "summary": "PATCH /org/redaction-rules/{ruleId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchOrgRedactionRulesRuleId", "description": "PATCH /api/v1/org/redaction-rules/{ruleId} on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Changes what is masked out of captured payloads before storage. A wrong rule silently stops redacting; a human owns that decision.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "policy.org_retention", "x-caveman-operation-contract": "ea64f90adde387114ce45c545837f962db5622dc96a0b543a0047912579dd449", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/org/roles": { "get": { "summary": "GET /org/roles", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOrgRoles", "description": "GET /api/v1/org/roles on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Organization role metadata is administrative reference information for human operators, not an agent action.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/org/router-learning-consents": { "get": { "summary": "GET /org/router-learning-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" } }, "operationId": "getOrgRouterLearningConsents", "description": "GET /api/v1/org/router-learning-consents on the Caveman Cloud control plane. Requires the settings:read scope. Not exposed to autonomous agents: Exposes organization decisions governing whether tenant traffic may train shared routing models. Legal and data-use consent state stays human-only.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/org/scim/groups": { "get": { "summary": "GET /org/scim/groups", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOrgScimGroups", "description": "GET /api/v1/org/scim/groups on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: SCIM-provisioned group membership is an administrative identity view; agents must not inspect or change organization provisioning state.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/org/scim/tokens": { "get": { "summary": "GET /org/scim/tokens", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOrgScimTokens", "description": "GET /api/v1/org/scim/tokens 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] }, "post": { "summary": "POST /org/scim/tokens", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postOrgScimTokens", "description": "POST /api/v1/org/scim/tokens on the Caveman Cloud control plane. Requires the sso:manage scope. Not exposed to autonomous agents: Mints a bearer that can provision and deprovision organization members. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] } }, "/org/scim/tokens/{tokenId}": { "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /org/scim/tokens/{tokenId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteOrgScimTokensTokenId", "description": "DELETE /api/v1/org/scim/tokens/{tokenId} 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] } }, "/org/sso/group-mappings": { "get": { "summary": "GET /org/sso/group-mappings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOrgSsoGroupMappings", "description": "GET /api/v1/org/sso/group-mappings on the Caveman Cloud control plane. Requires the sso:manage scope. Not exposed to autonomous agents: IdP group mappings change organization access policy; agents must not create or modify identity controls.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] }, "post": { "summary": "POST /org/sso/group-mappings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postOrgSsoGroupMappings", "description": "POST /api/v1/org/sso/group-mappings on the Caveman Cloud control plane. Requires the sso:manage scope. Not exposed to autonomous agents: IdP group mappings change organization access policy; agents must not create or modify identity controls.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] } }, "/org/sso/group-mappings/{mappingId}": { "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /org/sso/group-mappings/{mappingId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteOrgSsoGroupMappingsMappingId", "description": "DELETE /api/v1/org/sso/group-mappings/{mappingId} on the Caveman Cloud control plane. Requires the sso:manage scope. Not exposed to autonomous agents: IdP group mappings change organization access policy; agents must not create or modify identity controls.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] }, "patch": { "summary": "PATCH /org/sso/group-mappings/{mappingId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchOrgSsoGroupMappingsMappingId", "description": "PATCH /api/v1/org/sso/group-mappings/{mappingId} on the Caveman Cloud control plane. Requires the sso:manage scope. Not exposed to autonomous agents: IdP group mappings change organization access policy; agents must not create or modify identity controls.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "sso:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "sso:manage" ] } }, "/orgs/{orgId}/autopilot/funding": { "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /orgs/{orgId}/autopilot/funding", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getOrgsOrgIdAutopilotFunding", "description": "GET /api/v1/orgs/{orgId}/autopilot/funding on the Caveman Cloud control plane. Requires the settings:read scope. Exposed to autonomous agents as the autopilot_funding action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "x-caveman-operation": "autopilot.funding_get", "x-caveman-operation-contract": "6e9c685a9433870eb1dd7b84e6009424e7184f2ffa30420fe49b52fbea567674", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] }, "put": { "summary": "PUT /orgs/{orgId}/autopilot/funding", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putOrgsOrgIdAutopilotFunding", "description": "PUT /api/v1/orgs/{orgId}/autopilot/funding on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Chooses who pays for Caveman's own work and, for the allowance or a ChatGPT plan, makes the chooser the payer. A person spends their own money; an agent session never chooses it.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/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" } }, "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: Pauses or resumes every automatic change in the organization. A person pulls and releases that brake; an agent session never flips it for itself.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "operationId": "getOrgsOrgIdAutopilotPause", "description": "GET /api/v1/orgs/{orgId}/autopilot/pause on the Caveman Cloud control plane. Requires the settings:read scope. Exposed to autonomous agents as the autopilot_pause action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "x-caveman-operation": "autopilot.pause_status", "x-caveman-operation-contract": "ec1867dcbbb38189c97ca2974a6fd2f9c63b67c9cf8f3d81ecfdec06af60d700", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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: Pauses or resumes every automatic change in the organization. A person pulls and releases that brake; an agent session never flips it for itself.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "fixes.org_practice_evidence", "x-caveman-operation-contract": "7d782c618383c6d359e11e9e75fbd51663a6707438324c4c2aa27539c5204034", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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 organizations refuse 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" } }, "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). Dismiss or mark opportunities implemented, create an experiment from an opportunity, record outcomes, and submit practice findings. Legacy optimization proposal creation is retired.", "x-caveman-operation": "fixes.submit_practice_findings", "x-caveman-operation-contract": "b17fc138b21d328220ccf1b2efdb6d0090bd08d0e909dd57cd1094aa7616c281", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "findings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "basis": { "type": "string" }, "observed_at": { "type": "string" }, "practice_id": { "type": "string" }, "sessions_scanned": { "type": "integer" }, "sink_id": { "type": "string" }, "tokens_per_day_rate": { "type": "integer" }, "tokens_per_turn": { "type": "integer" } } } } }, "required": [ "findings" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "projects.list", "x-caveman-operation-contract": "6717a3b8d1930bcb863e485734623317c0db6dfbd79405aa2173444012ea2861", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "projects.create", "x-caveman-operation-contract": "730dad7db6984a4de00289e24fbafef64faab394bef54d3939f2840043c07355", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "slug": { "type": "string" } }, "required": [ "name" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /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" } }, "operationId": "deleteProjectsProjectId", "description": "DELETE /api/v1/projects/{projectId} on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Deleting a project is irreversible and cascades keys, policies, and telemetry. It stays a human owner's decision, like every other destructive lifecycle action.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] }, "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" } }, "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.", "x-caveman-operation": "projects.get", "x-caveman-operation-contract": "d1e8b3d7eb6ad5b4738bc122bff46ade367f11bdd0a1c3977498a5f2bf73f9ad", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "projects.update", "x-caveman-operation-contract": "5fac8d8039edf17d1c527b67c2981cc32b96e7c57cc1b716618ad13a01e67acb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "name" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/access": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/access", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAccess", "description": "GET /api/v1/projects/{projectId}/access on the Caveman Cloud control plane. Requires any one of the scopes billing:read, policy:draft. Exposed to autonomous agents as the access action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "x-caveman-operation": "policy.access", "x-caveman-operation-contract": "b23420399c81d03f42b380f0d348bf9c506b4b7e9f1dbbb73ba7c749a3494eaa", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read", "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read", "policy:draft" ] }, "patch": { "summary": "PATCH /projects/{projectId}/access", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdAccess", "description": "PATCH /api/v1/projects/{projectId}/access on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Changes which providers and models any key in the project may reach, and the ceilings every key shares. An admission control is a security boundary, not a tuning knob.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/agent-automations/{automationId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /projects/{projectId}/agent-automations/{automationId}", "responses": { "200": { "description": "Native operation persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAutomationReceipt" } } } }, "400": { "description": "Invalid or missing explicit configuration/input." }, "401": { "description": "Authentication required." }, "403": { "description": "Native user lacks authority." }, "404": { "description": "Requested resource or current authority unavailable." }, "409": { "description": "Revision/input conflict or budget unavailable." }, "503": { "description": "Shared agent execution unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdAgentAutomationsAutomationId", "description": "PUT /api/v1/projects/{projectId}/agent-automations/{automationId} on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user control of standing automation: which sources may open repair cases, under which repository scope and publication rule, owned by the caller. Workload credentials and scoped agent connections cannot configure, resume or pause automations. Native user endpoint. Scoped agent sessions and workload credentials cannot call this operation. Organization budget edits additionally require billing:write. Interactive grants bind current membership and role; input, audit, run and outbox admission commit atomically. Reuse the same request identity, input and deadline on retries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAutomationConfiguration" } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/agent-automations/{automationId}/pause": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-automations/{automationId}/pause", "responses": { "200": { "description": "Native operation persisted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "revoked": { "const": true } }, "required": [ "id", "revision", "revoked" ] } } } }, "400": { "description": "Invalid or missing explicit configuration/input." }, "401": { "description": "Authentication required." }, "403": { "description": "Native user lacks authority." }, "404": { "description": "Requested resource or current authority unavailable." }, "409": { "description": "Revision/input conflict or budget unavailable." }, "503": { "description": "Shared agent execution unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentAutomationsAutomationIdPause", "description": "POST /api/v1/projects/{projectId}/agent-automations/{automationId}/pause on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user control of standing automation: which sources may open repair cases, under which repository scope and publication rule, owned by the caller. Workload credentials and scoped agent connections cannot configure, resume or pause automations. Native user endpoint. Scoped agent sessions and workload credentials cannot call this operation. Organization budget edits additionally require billing:write. Interactive grants bind current membership and role; input, audit, run and outbox admission commit atomically. Reuse the same request identity, input and deadline on retries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAutomationPause" } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/agent-budget": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /projects/{projectId}/agent-budget", "responses": { "200": { "description": "Native operation persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBudgetConfiguration" } } } }, "400": { "description": "Invalid or missing explicit configuration/input." }, "401": { "description": "Authentication required." }, "403": { "description": "Native user lacks authority." }, "404": { "description": "Requested resource or current authority unavailable." }, "409": { "description": "Revision/input conflict or budget unavailable." }, "503": { "description": "Shared agent execution unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdAgentBudget", "description": "PUT /api/v1/projects/{projectId}/agent-budget on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user control of shared agent authority and execution. Workload credentials and scoped agent connections cannot expand grants, budgets or recursively admit runs. Native user endpoint. Scoped agent sessions and workload credentials cannot call this operation. Organization budget edits additionally require billing:write. Interactive grants bind current membership and role; input, audit, run and outbox admission commit atomically. Reuse the same request identity, input and deadline on retries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBudgetConfiguration" } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/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" } }, "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.", "x-caveman-operation": "builds.regressions", "x-caveman-operation-contract": "1e907e8cdfdd61535ac15c2c4b81960a57bed6aa2c407207f65eecdb4f743e3d", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "builds.list", "x-caveman-operation-contract": "15d04faacafc1adc4d5c3c392866be624eea8ec0027bfe9e0369195caa97c430", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "operationId": "postProjectsProjectIdAgentBuilds", "description": "Registers local build evidence only. Registration never activates plan or changes verified savings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "adapter_version": { "type": "string" }, "agent_slug": { "type": "string" }, "build_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "catalog_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "eval_suite_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "evidence_basis": { "const": "inferred" }, "evidence_status": { "const": "locked" }, "harness": { "enum": [ "pi", "vercel-ai-sdk", "eve", "mastra" ] }, "lock": {}, "plan_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "runtime_version": { "type": "string" }, "source_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "transform_registry_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "upstream_version": { "type": "string" } }, "required": [ "adapter_version", "agent_slug", "build_sha256", "catalog_sha256", "eval_suite_sha256", "evidence_basis", "evidence_status", "harness", "lock", "plan_sha256", "runtime_version", "source_sha256", "transform_registry_sha256", "upstream_version" ] } } } }, "x-caveman-operation": "builds.register", "x-caveman-operation-contract": "21a98fc3f56f140f86f0ae0a050918333b40449a07ec3b7ebc10dac5973f104b", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "builds.get", "x-caveman-operation-contract": "7d1faed0b9ccbf4256ed95b253fc8a4258e0162f820ae567fa8761afd5ca162f", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "operationId": "getProjectsProjectIdAgentBuildsBuildSha256Evidence", "description": "Identity is client-declared and observed. verified_savings_usd remains zero.", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-operation": "builds.evidence", "x-caveman-operation-contract": "f71ce1acefd179009e6bbc38789954bacda453748f5cfcf28efb655c2ac248ba", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-candidates/routes": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-candidates/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" } }, "operationId": "postProjectsProjectIdAgentCandidatesRoutes", "description": "POST /api/v1/projects/{projectId}/agent-candidates/routes on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the route action of the caveman_candidates_write tool (write access). Try an improvement case's ideas before they ship. Only an improvement session's case token may call it; a try authorizes nothing and a winner still reaches a person through the Inbox.", "x-caveman-operation": "candidates.route", "x-caveman-operation-contract": "ff4a30d36efdecd7df474aa0e61fd28bb3d3e71fb468264eadb784bbf004982a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "workflow": { "type": "string", "minLength": 1, "maxLength": 64 }, "targets": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "object", "additionalProperties": false, "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "effort": { "type": "string" } }, "required": [ "provider", "model" ] } }, "days": { "type": "integer", "minimum": 1, "maximum": 30 }, "note": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "workflow", "targets", "note" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/agent-candidates/runs": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-candidates/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" } }, "operationId": "postProjectsProjectIdAgentCandidatesRuns", "description": "POST /api/v1/projects/{projectId}/agent-candidates/runs on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the runs action of the caveman_candidates tool (read access). Read an improvement session's own practice runs and route tries: each scored commit with the fixed scorer's mark (kept or discarded), its cost ratio and per-task outcomes, and each route try's verdicts. With wait_seconds it waits for a pending one to settle. Only an improvement session's case token may read; a person reads the same on the case.", "x-caveman-operation": "candidates.runs", "x-caveman-operation-contract": "ec3b138477cf255bfc76fa0f2091fd52dd3bb7dc4470196ada83dc1fa48e0339", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "wait_seconds": { "type": "integer", "minimum": 0, "maximum": 25 } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-candidates/scores": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-candidates/scores", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentCandidatesScores", "description": "POST /api/v1/projects/{projectId}/agent-candidates/scores on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the score action of the caveman_candidates_write tool (write access). Try an improvement case's ideas before they ship. Only an improvement session's case token may call it; a try authorizes nothing and a winner still reaches a person through the Inbox.", "x-caveman-operation": "candidates.score", "x-caveman-operation-contract": "e963e6e7aacad3300a400539f96c2854552d7efa04be88383ebee6b2fe9d41da", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commit": { "type": "string", "description": "The full lowercase 40-hex SHA of the commit to score (git rev-parse HEAD)." }, "note": { "type": "string", "description": "What the commit tries, in 1 to 300 characters." } }, "required": [ "commit", "note" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/projects/{projectId}/agent-cases/{caseId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-cases/{caseId}", "responses": { "200": { "description": "Case projection with its pinned shared allowance and separate case spend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryCaseAllowanceProjection" } } } }, "403": { "description": "Native user authority required." }, "404": { "description": "Case unavailable in this scope." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentCasesCaseId", "description": "GET /api/v1/projects/{projectId}/agent-cases/{caseId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-cases/{caseId}/cancel": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-cases/{caseId}/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" } }, "operationId": "postProjectsProjectIdAgentCasesCaseIdCancel", "description": "POST /api/v1/projects/{projectId}/agent-cases/{caseId}/cancel on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/agent-cases/{caseId}/refresh-source": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-cases/{caseId}/refresh-source", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentCasesCaseIdRefreshSource", "description": "POST /api/v1/projects/{projectId}/agent-cases/{caseId}/refresh-source on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user authority over factory evidence eligibility. Re-reading the bound repository head can invalidate an accepted comparison and block publication, so an agent session must never decide that its own evidence is still current.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/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" } }, "operationId": "getProjectsProjectIdAgentConnections", "description": "GET /api/v1/projects/{projectId}/agent-connections on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Agent connections name an agent's own brokered session and key (migration 0107). Listing them is the human owner's audit view; an agent enumerating sessions would be reading about its peers' credentials.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "operationId": "deleteProjectsProjectIdAgentConnectionsConnectionId", "description": "DELETE /api/v1/projects/{projectId}/agent-connections/{connectionId} on the Caveman Cloud control plane. Requires the key:manage scope. Not exposed to autonomous agents: Revocation is the human owner's kill switch over an agent's session. An agent must not be able to revoke its own or a peer's access.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] } }, "/projects/{projectId}/agent-deployments": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-deployments", "responses": { "200": { "description": "Native operation persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDeployment" } } } }, "400": { "description": "Invalid or missing explicit configuration/input." }, "401": { "description": "Authentication required." }, "403": { "description": "Native user lacks authority." }, "404": { "description": "Requested resource or current authority unavailable." }, "409": { "description": "Revision/input conflict or budget unavailable." }, "503": { "description": "Shared agent execution unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentDeployments", "description": "POST /api/v1/projects/{projectId}/agent-deployments on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user registration of immutable deployment source identity; requires autopilot:manage and repo:connect. Model and workload callers cannot mint deployment attribution. Native user endpoint. Scoped agent sessions and workload credentials cannot call this operation. Organization budget edits additionally require billing:write. Interactive grants bind current membership and role; input, audit, run and outbox admission commit atomically. Reuse the same request identity, input and deadline on retries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDeploymentRegistration" } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/agent-evaluators/activations": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-evaluators/activations", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentEvaluatorsActivations", "description": "POST /api/v1/projects/{projectId}/agent-evaluators/activations on the Caveman Cloud control plane. Requires the autopilot:manage scope. Exposed to autonomous agents as the activate_evaluator action of the caveman_authoring_write tool (write access). Draft an evaluator or a scenario, list the qualification sets that can qualify a draft, qualify it and request its activation, each bound to the Ask or author session whose case token calls it. A draft is unqualified and not live; a person's connection has no session run and is refused.", "x-caveman-operation": "evaluators.activate", "x-caveman-operation-contract": "1b73af4dabef7570207fc1ee224917cfc88e92534c28b62b6840246e13dc6ac6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "qualification_id": { "type": "string", "format": "uuid" } }, "required": [ "qualification_id" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/agent-evaluators/drafts": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-evaluators/drafts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentEvaluatorsDrafts", "description": "POST /api/v1/projects/{projectId}/agent-evaluators/drafts on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the draft_evaluator action of the caveman_authoring_write tool (write access). Draft an evaluator or a scenario, list the qualification sets that can qualify a draft, qualify it and request its activation, each bound to the Ask or author session whose case token calls it. A draft is unqualified and not live; a person's connection has no session run and is refused.", "x-caveman-operation": "evaluators.draft", "x-caveman-operation-contract": "3e7a1d9117285545a8cb396f391f2cdd8b21bee0baeb232b5572733adb596be8", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "type": "string", "maxLength": 2000 }, "config": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "grader_type", "options", "input_mapping" ], "properties": { "schema_version": { "const": 1 }, "grader_type": { "type": "string", "enum": [ "exact_match", "contains", "not_contains", "regex", "not_regex", "blocklist", "json_schema", "json_path_assertion", "tool_called", "tool_not_called", "tool_sequence", "tool_argument_assertion", "http_status", "latency_threshold", "cost_threshold", "token_threshold", "bleu_score", "rouge_score", "context_f1", "no_pii", "localization_f1", "llm_judge", "llm_score", "llm_category", "llm_pairwise", "llm_answer_match" ], "description": "One of the platform's grader families; any other name is refused before any effect. Free-text contracts: contains (required facts) and not_contains (forbidden literals). Tool use: tool_called, tool_not_called, tool_sequence, tool_argument_assertion. Spend: cost_threshold, token_threshold, latency_threshold." }, "options": { "type": "object", "description": "The grader family's own options. The draft records them; they are checked when the evaluator is qualified, not here." }, "input_mapping": { "type": "object", "additionalProperties": false, "required": [ "candidate" ], "description": "Only candidate, reference and baseline are accepted; any other key is refused.", "properties": { "candidate": { "type": "object", "additionalProperties": false, "required": [ "source", "key" ], "description": "what is graded: {\"source\":\"target\",\"key\":\"$target\"} for the target's own output", "properties": { "source": { "type": "string", "enum": [ "dataset", "target" ] }, "key": { "type": "string", "anyOf": [ { "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" }, { "const": "$target" } ], "description": "a dataset column key, or $target (source target only) for the graded output itself" } } }, "reference": { "type": "object", "additionalProperties": false, "required": [ "source", "key" ], "description": "optional expected value, usually a dataset column", "properties": { "source": { "type": "string", "enum": [ "dataset", "target" ] }, "key": { "type": "string", "anyOf": [ { "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" }, { "const": "$target" } ], "description": "a dataset column key, or $target (source target only) for the graded output itself" } } }, "baseline": { "type": "object", "additionalProperties": false, "required": [ "source", "key" ], "description": "optional comparison value for pairwise graders", "properties": { "source": { "type": "string", "enum": [ "dataset", "target" ] }, "key": { "type": "string", "anyOf": [ { "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" }, { "const": "$target" } ], "description": "a dataset column key, or $target (source target only) for the graded output itself" } } } } } } }, "evidence_queries": { "type": "array", "minItems": 1, "maxItems": 24, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "required": [ "name", "description", "config", "evidence_queries" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/agent-evaluators/qualification-sets": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-evaluators/qualification-sets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentEvaluatorsQualificationSets", "description": "POST /api/v1/projects/{projectId}/agent-evaluators/qualification-sets on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the qualification_sets action of the caveman_authoring_write tool (read access). Draft an evaluator or a scenario, list the qualification sets that can qualify a draft, qualify it and request its activation, each bound to the Ask or author session whose case token calls it. A draft is unqualified and not live; a person's connection has no session run and is refused.", "x-caveman-operation": "evaluators.qualification_sets", "x-caveman-operation-contract": "ed7ee1d4399d9cd2a4084f4307f911fe5e8fe4e58f5b39e52e37c0c4997c0ff5", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-evaluators/qualifications": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-evaluators/qualifications", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentEvaluatorsQualifications", "description": "POST /api/v1/projects/{projectId}/agent-evaluators/qualifications on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the qualify_evaluator action of the caveman_authoring_write tool (write access). Draft an evaluator or a scenario, list the qualification sets that can qualify a draft, qualify it and request its activation, each bound to the Ask or author session whose case token calls it. A draft is unqualified and not live; a person's connection has no session run and is refused.", "x-caveman-operation": "evaluators.qualify", "x-caveman-operation-contract": "8b8c41e4a76c548b071830e0f9493dc2f86eef0f81724eb919059949688758a2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "evaluator_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "set_id": { "type": "string", "format": "uuid" } }, "required": [ "evaluator_id", "version", "set_id" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/agent-notebook/entries": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-notebook/entries", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentNotebookEntries", "description": "POST /api/v1/projects/{projectId}/agent-notebook/entries on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the append action of the caveman_notebook_write tool (write access). Append one row to an improvement case's notebook: a plan, hypothesis, edit, result, dead end, running notes or a declined inbox item. Only an improvement session's case token may write, and a row authorizes nothing.", "x-caveman-operation": "notebook.append", "x-caveman-operation-contract": "7c50a82da0a00a0771f4c6af0e2871a695107a14e9d02c46f1a96b77c8350f40", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "plan", "hypothesis", "check_authored", "edit", "dev_result", "dead_end", "capability_request", "notes", "inbox_closed" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 500 }, "ref": { "type": "string", "maxLength": 120 }, "metric": { "type": "object", "maxProperties": 16 }, "detail": { "type": "string", "maxLength": 16384 } }, "required": [ "kind", "summary" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/projects/{projectId}/agent-runs": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-runs", "responses": { "200": { "description": "Bounded native user page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunPage" } } } }, "400": { "description": "Invalid cursor." }, "401": { "description": "Authentication required." }, "403": { "description": "Native user required." }, "404": { "description": "Project, cursor or current authority unavailable." }, "503": { "description": "Shared agent configuration unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentRuns", "description": "GET /api/v1/projects/{projectId}/agent-runs on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Native user history of immutable owned chat runs. Shared agents use the protected journal. Native unscoped user endpoint. Returns only this user's owned chat run metadata. Results require separate current permission and source checks.", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Previous next_cursor. Omit for first page." }, { "name": "sessions", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Return the newest owned chat run per case, ordered by latest activity." } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/agent-runs", "responses": { "202": { "description": "Native operation persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" } } } }, "400": { "description": "Invalid or missing explicit configuration/input." }, "401": { "description": "Authentication required." }, "403": { "description": "Native user lacks authority." }, "404": { "description": "Requested resource or current authority unavailable." }, "409": { "description": "Revision/input conflict or budget unavailable." }, "503": { "description": "Shared agent execution unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentRuns", "description": "POST /api/v1/projects/{projectId}/agent-runs on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the run_agent action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic. Native user endpoint. Scoped agent sessions and workload credentials cannot call this operation. Organization budget edits additionally require billing:write. Interactive grants bind current membership and role; input, audit, run and outbox admission commit atomically. Reuse the same request identity, input and deadline on retries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "parent_run_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "deadline": { "type": "string", "format": "date-time" }, "fix": { "type": "boolean", "description": "Ask for a repair case instead of an answer." }, "model": { "type": "string", "maxLength": 200, "description": "provider/model from GET ask/models. Omitted: the parent turn's model on a follow-up, else the default." }, "input": { "type": "object", "additionalProperties": false, "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 16000 }, "window": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ] }, "context": { "type": "object", "description": "The console page the question was asked from." } }, "required": [ "question", "window" ] } }, "required": [ "request_id", "input" ] } } } }, "x-caveman-operation": "agent.run", "x-caveman-operation-contract": "ca3e8084eda5d2e963a2879f8f826f34b291c3b958ccc832802e401b5d60e943", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/projects/{projectId}/agent-runs/{runId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-runs/{runId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentRunsRunId", "description": "GET /api/v1/projects/{projectId}/agent-runs/{runId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the agent_run 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.", "x-caveman-operation": "runs.get", "x-caveman-operation-contract": "6e092945803d5345ee8ba8be656d20ead818c6b2b871cde19517663a38a5611e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-runs/{runId}/cancel": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-runs/{runId}/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" } }, "operationId": "postProjectsProjectIdAgentRunsRunIdCancel", "description": "POST /api/v1/projects/{projectId}/agent-runs/{runId}/cancel on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the cancel_agent_run action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "runs.cancel", "x-caveman-operation-contract": "16ffe3185a990493468573c6578c68db9ad8ba9404d507a9047d3a1e90ba7ce3", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/projects/{projectId}/agent-runs/{runId}/case": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-runs/{runId}/case", "responses": { "200": { "description": "Bounded native user page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCase" } } } }, "400": { "description": "Invalid cursor." }, "401": { "description": "Authentication required." }, "403": { "description": "Native user required." }, "404": { "description": "Project, cursor or current authority unavailable." }, "503": { "description": "Shared agent configuration unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentRunsRunIdCase", "description": "GET /api/v1/projects/{projectId}/agent-runs/{runId}/case on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Discloses protected native case context under current ownership and transactional payload audit. Native unscoped user endpoint. Returns only this user's owned chat run metadata. Results require separate current permission and source checks.", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Previous next_cursor. Omit for first page." } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-runs/{runId}/events": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-runs/{runId}/events", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentRunsRunIdEvents", "description": "GET /api/v1/projects/{projectId}/agent-runs/{runId}/events on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the agent_run_events 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.", "x-caveman-operation": "runs.events", "x-caveman-operation-contract": "7a292ee64415d6ffe0d37588a2b3f1b3792712fc68053aee5c83257881e5f082", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-runs/{runId}/evidence": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-runs/{runId}/evidence", "responses": { "200": { "description": "Protected native receipt values. Repository candidates additionally require current payload:read; each receipt retains current authority, custody, and retention checks.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": {}, "minItems": 0, "maxItems": 24 } }, "required": [ "data" ] } } } }, "403": { "description": "Current payload or trace authority unavailable." }, "404": { "description": "Run, source, or receipt unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentRunsRunIdEvidence", "description": "GET /api/v1/projects/{projectId}/agent-runs/{runId}/evidence on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Discloses protected native evidence under current ownership and transactional payload audit.", "parameters": [ { "name": "capability", "in": "query", "required": true, "schema": { "enum": [ "traces.compare", "usage.compare", "repository.prepare_patch", "repository.candidate" ] } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-runs/{runId}/input": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-runs/{runId}/input", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentRunsRunIdInput", "description": "GET /api/v1/projects/{projectId}/agent-runs/{runId}/input on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Discloses retained native input under current ownership and transactional payload audit.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-runs/{runId}/ledger": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-runs/{runId}/ledger", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentRunsRunIdLedger", "description": "GET /api/v1/projects/{projectId}/agent-runs/{runId}/ledger on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Console view of a role session's ledger under current result authority and transactional audit; agents read a run through agent_run_events.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-runs/{runId}/result": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-runs/{runId}/result", "responses": { "200": { "description": "Current authorized result disclosure with separately recorded delivery metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunResult" } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Native user required." }, "404": { "description": "Result, source or current permission unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentRunsRunIdResult", "description": "GET /api/v1/projects/{projectId}/agent-runs/{runId}/result on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the agent_run_result 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.", "x-caveman-operation": "runs.result", "x-caveman-operation-contract": "697a63014b09bb4720220a72b91212cfc7782f7105e1bb1da8ad97e92f02a1d4", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-scenarios/drafts": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-scenarios/drafts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentScenariosDrafts", "description": "POST /api/v1/projects/{projectId}/agent-scenarios/drafts on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the draft_scenario action of the caveman_authoring_write tool (write access). Draft an evaluator or a scenario, list the qualification sets that can qualify a draft, qualify it and request its activation, each bound to the Ask or author session whose case token calls it. A draft is unqualified and not live; a person's connection has no session run and is refused.", "x-caveman-operation": "scenarios.draft", "x-caveman-operation-contract": "9837d9cf23a3e36dc2db02e7c2bdfb6585b00ab6f6f513b2cb4f719020c91c48", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "adapter": { "enum": [ "python-module-task-v1", "node-module-task-v1" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "invariant": { "type": "string", "minLength": 1, "maxLength": 4000 }, "entrypoint": { "type": "string", "maxLength": 200, "pattern": "^([A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*:[A-Za-z_][A-Za-z0-9_]*|(\\.caveman/adapters/)?[A-Za-z0-9_][A-Za-z0-9_./-]*\\.(js|mjs|ts):[A-Za-z_$][A-Za-z0-9_$]*)$" }, "input": {}, "initial_state": { "type": "object" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "arguments": {}, "result": {}, "error": { "type": "string", "maxLength": 500 } }, "required": [ "name", "arguments", "result" ] }, "minItems": 0, "maxItems": 100 }, "read_only_tools": { "type": "array", "description": "Declared tool names whose calls change nothing. A trial may then make those calls in another order between two other calls, and skip one unless its recorded answer differs from that same call's latest earlier answer; every other fixture must be called in order. Omit when any tool has side effects you are unsure of.", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 100, "uniqueItems": true }, "assertions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "subject": { "enum": [ "output", "state" ] }, "pointer": { "type": "string", "maxLength": 1000 }, "operator": { "enum": [ "equals", "contains", "not_contains" ] }, "value": {} }, "allOf": [ { "if": { "properties": { "operator": { "enum": [ "contains", "not_contains" ] } } }, "then": { "properties": { "value": { "type": "string", "minLength": 1 } } } } ], "required": [ "subject", "pointer", "operator", "value" ] }, "minItems": 1, "maxItems": 100 }, "expected_failure": { "type": "object", "additionalProperties": false, "properties": { "exception_type": { "type": "string", "minLength": 1, "maxLength": 200 }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "function": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "exception_type", "path", "function" ] }, "historical": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "expected": { "enum": [ "passed", "failed" ] } }, "required": [ "commit_sha", "expected" ] }, "minItems": 0, "maxItems": 20 }, "provenance": { "type": "object", "additionalProperties": false, "properties": { "evidence_digests": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "fixture_basis": { "const": "synthetic" }, "fixture_rationale": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "evidence_digests", "fixture_basis", "fixture_rationale" ] } }, "required": [ "schema_version", "adapter", "name", "invariant", "entrypoint", "input", "initial_state", "tools", "assertions", "historical", "provenance" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/agent-sentinel": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-sentinel", "responses": { "200": { "description": "Stage runs of this project's repair cases. Personal chat history is separate; results require their own disclosure checks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSentinelPage" } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Native user with payload:read required." }, "404": { "description": "Project, cursor or current authority unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentSentinel", "description": "GET /api/v1/projects/{projectId}/agent-sentinel on the Caveman Cloud control plane. Requires the payload:read scope. Not exposed to autonomous agents: Native user inbox of automatic work. Requires payload disclosure permission; never widens personal chat history.", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/agent-setup": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-setup", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentSetup", "description": "GET /api/v1/projects/{projectId}/agent-setup on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user configuration of shared execution authority; grants and provider bindings remain private.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/agent-setups": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-setups", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentSetups", "description": "POST /api/v1/projects/{projectId}/agent-setups on the Caveman Cloud control plane. Requires any one of the scopes autopilot:manage, scenario:write. Exposed to autonomous agents as the create_setup action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "setups.create", "x-caveman-operation-contract": "c5b375a652826273a6177161e699a3cdb20ccbb083c84b8279869c0d49b8f5b7", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "agent_id": { "type": "string", "format": "uuid" }, "repository_binding_id": { "type": "string", "format": "uuid" }, "tasks": { "type": "array", "minItems": 5, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "dataset_id", "version" ] } } }, "required": [ "agent_id" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage", "scenario:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage", "scenario:write" ] } }, "/projects/{projectId}/agent-setups/{caseId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/agent-setups/{caseId}", "responses": { "200": { "description": "Case projection with its pinned shared allowance and separate case spend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryCaseAllowanceProjection" } } } }, "403": { "description": "Native user authority required." }, "404": { "description": "Case unavailable in this scope." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentSetupsCaseId", "description": "GET /api/v1/projects/{projectId}/agent-setups/{caseId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agent-setups/{caseId}/decisions": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/agent-setups/{caseId}/decisions", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdAgentSetupsCaseIdDecisions", "description": "POST /api/v1/projects/{projectId}/agent-setups/{caseId}/decisions on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot: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" } }, "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.", "x-caveman-operation": "workflows.list_agents", "x-caveman-operation-contract": "67100171dcf2f82b29836b548388bffdc1a1d188412d0cf82be1ecd54efb4663", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "workflows.create_agent", "x-caveman-operation-contract": "a60ccacde59926deab38c0d509a9fad57337a95029d31c62403262fa78b3ffb4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "slug", "name" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "workflows.get_agent", "x-caveman-operation-contract": "6d08fd5d8622b405a77a7a1c534e4e9fde56cd8cffd1b332db532678f3d13af1", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "workflows.update_agent", "x-caveman-operation-contract": "7dc28a8376150320d19933eb58b6ae1c85544b36212a3c502ab1b6c7834e124e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string" }, "name": { "type": "string" } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/agents/{agentId}/cases": { "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}/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" } }, "operationId": "getProjectsProjectIdAgentsAgentIdCases", "description": "GET /api/v1/projects/{projectId}/agents/{agentId}/cases on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/agents/{agentId}/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" } }, "operationId": "postProjectsProjectIdAgentsAgentIdCases", "description": "POST /api/v1/projects/{projectId}/agents/{agentId}/cases on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/agents/{agentId}/execution-binding": { "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}/execution-binding", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentsAgentIdExecutionBinding", "description": "GET /api/v1/projects/{projectId}/agents/{agentId}/execution-binding on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/agents/{agentId}/factory-policy": { "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}/factory-policy", "responses": { "200": { "description": "Current policy and exact shared allowance. Legacy policies have no shared allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryPolicyResponse" } } } }, "400": { "description": "Invalid policy." }, "403": { "description": "Native user authority required." }, "409": { "description": "Stale revision or changed fresh-approval retry." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAgentsAgentIdFactoryPolicy", "description": "GET /api/v1/projects/{projectId}/agents/{agentId}/factory-policy on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "put": { "summary": "PUT /projects/{projectId}/agents/{agentId}/factory-policy", "responses": { "200": { "description": "Current policy and exact shared allowance. Legacy policies have no shared allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryPolicyResponse" } } } }, "400": { "description": "Invalid policy." }, "403": { "description": "Native user authority required." }, "409": { "description": "Stale revision or changed fresh-approval retry." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdAgentsAgentIdFactoryPolicy", "description": "PUT /api/v1/projects/{projectId}/agents/{agentId}/factory-policy on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryPolicyConfiguration" } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/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" } }, "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.", "x-caveman-operation": "workflows.list", "x-caveman-operation-contract": "a7440716b529664fe5acab686589b9a5c1016765866e7615a08a0d12c8865438", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "workflows.create", "x-caveman-operation-contract": "050f64fcf414f011f0e3b752b130eb1c244c6c5e5f6f39433fa9f41be9fe675f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "risk_level": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "slug", "name" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/annotations": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/annotations", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAnnotations", "description": "GET /api/v1/projects/{projectId}/annotations on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the search action of the caveman_annotations tool (read access). Human judgements on traces and eval runs: review notes with a label, a note and an open or resolved status, searchable across the project. Notes can quote captured content, so reading them needs payload access.", "x-caveman-operation": "annotations.search", "x-caveman-operation-contract": "c51d817adf2575dbc8c0c14d7d465fa7824ad76fd66d198e26c9af7fb30423e3", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "trace_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/ask/models": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/ask/models", "responses": { "200": { "description": "The install's Ask models in operator order, each with whether the caller's turn on it would be admitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskModels" } } } }, "401": { "description": "Authentication required." }, "404": { "description": "Project or current authority unavailable." }, "409": { "description": "Ask is not turned on for this deployment." }, "503": { "description": "Shared agent execution unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdAskModels", "description": "GET /api/v1/projects/{projectId}/ask/models on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Console model picker for a person's own Ask turns: which models this install offers and which the caller's turn could run on now.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/autopilot": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/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" } }, "operationId": "getProjectsProjectIdAutopilot", "description": "GET /api/v1/projects/{projectId}/autopilot on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the autopilot action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "x-caveman-operation": "autopilot.get", "x-caveman-operation-contract": "3f3b5fd735640ed789a19ef53a6be12af67b0328c7f0a3d1427c265d676b5b01", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "put": { "summary": "PUT /projects/{projectId}/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" } }, "operationId": "putProjectsProjectIdAutopilot", "description": "PUT /api/v1/projects/{projectId}/autopilot on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Moves the autopilot dial, which can switch changes on for live traffic. A human sets it.", "x-caveman-operation": "autopilot.set", "x-caveman-operation-contract": "ad78e146f05e1f20772c396341c8b3db02e324aa3feda2cc78b51e2b531e1a0e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "mode": { "enum": [ "off", "suggest", "on" ] } }, "required": [ "mode" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/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" } }, "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.", "x-caveman-operation": "fixes.list_moves", "x-caveman-operation-contract": "99b056cb1501c767433278ae451ac3114b541f560dc9213551381a80159cb5c6", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/briefs": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/briefs", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdBriefs", "description": "GET /api/v1/projects/{projectId}/briefs on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list action of the caveman_briefs tool (read access). The Improvements workspace: one written brief per finding worth a look, with its citations, charts, activity, revisions and comments. A brief's impact is the scout's estimate; once a proof is done, its proof (proof_summary on a list row) is the replayed result, always inferred, and the figure to quote.", "x-caveman-operation": "briefs.list", "x-caveman-operation-contract": "2772963583340aa2636498fb839d0035b6bc22a2d5a4bcded656a4e66a1e68f9", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "scout", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "assignee", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/briefs/{briefId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "briefId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/briefs/{briefId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdBriefsBriefId", "description": "GET /api/v1/projects/{projectId}/briefs/{briefId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get action of the caveman_briefs tool (read access). The Improvements workspace: one written brief per finding worth a look, with its citations, charts, activity, revisions and comments. A brief's impact is the scout's estimate; once a proof is done, its proof (proof_summary on a list row) is the replayed result, always inferred, and the figure to quote.", "x-caveman-operation": "briefs.get", "x-caveman-operation-contract": "c1405acfd8d2a27a261cfba1f6d203ebfdb0074ca06faf9efacf04fd2a0e89dd", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /projects/{projectId}/briefs/{briefId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdBriefsBriefId", "description": "PATCH /api/v1/projects/{projectId}/briefs/{briefId} on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the edit action of the caveman_briefs_write tool (write access). Rewrite a brief through the same write path people use (every claim cited, the version you read), move its status, assignee or priority, comment, and run its declared actions: mark done, dismiss, or prove it on recorded traffic (queues a replay whose result reads back as the brief's proof, always inferred). Fix is a person's action from their own session; your agent takes the fix itself by pulling the brief's fix packet and reporting back, which the brief shows as self-reported.", "x-caveman-operation": "briefs.edit", "x-caveman-operation-contract": "206451cb52fa10b7597bfacd5716cc41d682d1932202b6d3a856d192937d2e03", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_version": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "summary_md": { "type": "string", "maxLength": 16384 }, "body_md": { "type": "string", "maxLength": 65536 }, "sources": { "type": "array", "maxItems": 24, "items": { "type": "object", "additionalProperties": false, "properties": { "n": { "type": "integer", "minimum": 1 }, "kind": { "enum": [ "finding", "evidence", "trace", "report", "query" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "href": { "type": "string", "pattern": "^/" }, "detail": { "type": "string", "maxLength": 500 } }, "required": [ "n", "kind", "label" ] } }, "status": { "enum": [ "open", "in_progress", "done", "dismissed" ] }, "priority": { "type": "integer", "minimum": 1, "maximum": 3 }, "assignee_id": { "type": [ "string", "null" ] } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/projects/{projectId}/briefs/{briefId}/actions/{actionKey}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "briefId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/briefs/{briefId}/actions/{actionKey}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdBriefsBriefIdActionsActionKey", "description": "POST /api/v1/projects/{projectId}/briefs/{briefId}/actions/{actionKey} on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the act action of the caveman_briefs_write tool (write access). Rewrite a brief through the same write path people use (every claim cited, the version you read), move its status, assignee or priority, comment, and run its declared actions: mark done, dismiss, or prove it on recorded traffic (queues a replay whose result reads back as the brief's proof, always inferred). Fix is a person's action from their own session; your agent takes the fix itself by pulling the brief's fix packet and reporting back, which the brief shows as self-reported.", "x-caveman-operation": "briefs.act", "x-caveman-operation-contract": "1682adda7de1a00488a9b746c13d5430f04f6a0194c87386afecc72310d4f501", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/projects/{projectId}/briefs/{briefId}/activity": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "briefId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/briefs/{briefId}/activity", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdBriefsBriefIdActivity", "description": "GET /api/v1/projects/{projectId}/briefs/{briefId}/activity on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the activity action of the caveman_briefs tool (read access). The Improvements workspace: one written brief per finding worth a look, with its citations, charts, activity, revisions and comments. A brief's impact is the scout's estimate; once a proof is done, its proof (proof_summary on a list row) is the replayed result, always inferred, and the figure to quote.", "x-caveman-operation": "briefs.activity", "x-caveman-operation-contract": "6baaa20c7114388fad6e639a0d5cce1737049b84d71b6c43bc6b0fc90ff8fb5c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/briefs/{briefId}/comments": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "briefId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/briefs/{briefId}/comments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdBriefsBriefIdComments", "description": "GET /api/v1/projects/{projectId}/briefs/{briefId}/comments on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the comments action of the caveman_briefs tool (read access). The Improvements workspace: one written brief per finding worth a look, with its citations, charts, activity, revisions and comments. A brief's impact is the scout's estimate; once a proof is done, its proof (proof_summary on a list row) is the replayed result, always inferred, and the figure to quote.", "x-caveman-operation": "briefs.comments", "x-caveman-operation-contract": "aa9097c9fb9b3bec71030da580a9787fdb77d7943c1b284580ff67f2ba63a14c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/briefs/{briefId}/comments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdBriefsBriefIdComments", "description": "POST /api/v1/projects/{projectId}/briefs/{briefId}/comments on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the comment action of the caveman_briefs_write tool (write access). Rewrite a brief through the same write path people use (every claim cited, the version you read), move its status, assignee or priority, comment, and run its declared actions: mark done, dismiss, or prove it on recorded traffic (queues a replay whose result reads back as the brief's proof, always inferred). Fix is a person's action from their own session; your agent takes the fix itself by pulling the brief's fix packet and reporting back, which the brief shows as self-reported.", "x-caveman-operation": "briefs.comment", "x-caveman-operation-contract": "999604c9551d72c27c7b089bea5ca1a914a6712085aa4103532993b4fed19dbc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 8000 }, "parent_id": { "type": "string", "format": "uuid" }, "anchor": { "type": "object", "additionalProperties": false, "properties": { "field": { "enum": [ "summary", "body" ] }, "quote": { "type": "string", "minLength": 1, "maxLength": 500 }, "prefix": { "type": "string", "maxLength": 64 }, "suffix": { "type": "string", "maxLength": 64 } }, "required": [ "field", "quote" ] } }, "required": [ "body" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/projects/{projectId}/briefs/{briefId}/comments/{commentId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "briefId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/briefs/{briefId}/comments/{commentId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdBriefsBriefIdCommentsCommentId", "description": "DELETE /api/v1/projects/{projectId}/briefs/{briefId}/comments/{commentId} on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the delete_comment action of the caveman_briefs_write tool (write access). Rewrite a brief through the same write path people use (every claim cited, the version you read), move its status, assignee or priority, comment, and run its declared actions: mark done, dismiss, or prove it on recorded traffic (queues a replay whose result reads back as the brief's proof, always inferred). Fix is a person's action from their own session; your agent takes the fix itself by pulling the brief's fix packet and reporting back, which the brief shows as self-reported.", "x-caveman-operation": "briefs.delete_comment", "x-caveman-operation-contract": "791609ce3490c26dd4c7fdf6217fd9e4aba48e2accac82cc3dd35360fda3951e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] }, "patch": { "summary": "PATCH /projects/{projectId}/briefs/{briefId}/comments/{commentId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdBriefsBriefIdCommentsCommentId", "description": "PATCH /api/v1/projects/{projectId}/briefs/{briefId}/comments/{commentId} on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the update_comment action of the caveman_briefs_write tool (write access). Rewrite a brief through the same write path people use (every claim cited, the version you read), move its status, assignee or priority, comment, and run its declared actions: mark done, dismiss, or prove it on recorded traffic (queues a replay whose result reads back as the brief's proof, always inferred). Fix is a person's action from their own session; your agent takes the fix itself by pulling the brief's fix packet and reporting back, which the brief shows as self-reported.", "x-caveman-operation": "briefs.update_comment", "x-caveman-operation-contract": "e0ed79af639d957532bd60e2db903d900bc88cba73d744a53036e2a0171a3f90", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 8000 }, "resolved": { "type": "boolean" } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/projects/{projectId}/briefs/{briefId}/fix-packet": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "briefId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/briefs/{briefId}/fix-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" } }, "operationId": "postProjectsProjectIdBriefsBriefIdFixPacket", "description": "POST /api/v1/projects/{projectId}/briefs/{briefId}/fix-packet on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the fix_packet action of the caveman_briefs_write tool (write access). Rewrite a brief through the same write path people use (every claim cited, the version you read), move its status, assignee or priority, comment, and run its declared actions: mark done, dismiss, or prove it on recorded traffic (queues a replay whose result reads back as the brief's proof, always inferred). Fix is a person's action from their own session; your agent takes the fix itself by pulling the brief's fix packet and reporting back, which the brief shows as self-reported.", "x-caveman-operation": "briefs.fix_packet", "x-caveman-operation-contract": "1171cef455099e31292a69d2eaef99c94eab0669f2d8838be169402c4fda4963", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/projects/{projectId}/briefs/{briefId}/fix-report": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "briefId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/briefs/{briefId}/fix-report", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdBriefsBriefIdFixReport", "description": "POST /api/v1/projects/{projectId}/briefs/{briefId}/fix-report on the Caveman Cloud control plane. Requires the opportunity:write scope. Exposed to autonomous agents as the fix_report action of the caveman_briefs_write tool (write access). Rewrite a brief through the same write path people use (every claim cited, the version you read), move its status, assignee or priority, comment, and run its declared actions: mark done, dismiss, or prove it on recorded traffic (queues a replay whose result reads back as the brief's proof, always inferred). Fix is a person's action from their own session; your agent takes the fix itself by pulling the brief's fix packet and reporting back, which the brief shows as self-reported.", "x-caveman-operation": "briefs.fix_report", "x-caveman-operation-contract": "a5c79d24ca476b048bf17fe22859bffd8dd343a077e7fcd2dd5001bf029783a6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "run_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "runner": { "enum": [ "", "recipe", "caveman", "claude-code", "codex" ] }, "outcome": { "type": "string" }, "reason": { "type": "string" }, "evidence_source": { "type": "string" }, "summary": { "type": "string" }, "oracles": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "exit": { "type": "integer" }, "duration_ms": { "type": "integer" }, "tail": { "type": "string" } }, "required": [ "name", "exit" ] } }, "changed_files": { "type": "array", "items": { "type": "string" } }, "loc_added": { "type": "integer" }, "loc_removed": { "type": "integer" }, "injection_observed": { "type": "array", "items": { "type": "string" } }, "branch": { "type": "string", "maxLength": 255 }, "head_sha": { "type": "string" }, "pr_url": { "type": "string", "pattern": "^(https://|$)" } }, "required": [ "schema_version", "run_id", "oracles" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/projects/{projectId}/briefs/{briefId}/revisions/{version}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "briefId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/briefs/{briefId}/revisions/{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" } }, "operationId": "getProjectsProjectIdBriefsBriefIdRevisionsVersion", "description": "GET /api/v1/projects/{projectId}/briefs/{briefId}/revisions/{version} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the revision action of the caveman_briefs tool (read access). The Improvements workspace: one written brief per finding worth a look, with its citations, charts, activity, revisions and comments. A brief's impact is the scout's estimate; once a proof is done, its proof (proof_summary on a list row) is the replayed result, always inferred, and the figure to quote.", "x-caveman-operation": "briefs.revision", "x-caveman-operation-contract": "af67cb4e5808a03ca8c181cb67bc27ceca3d05b4a66ea88d760e943e9b22ff6f", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/briefs/summary": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/briefs/summary", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdBriefsSummary", "description": "GET /api/v1/projects/{projectId}/briefs/summary on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the summary action of the caveman_briefs tool (read access). The Improvements workspace: one written brief per finding worth a look, with its citations, charts, activity, revisions and comments. A brief's impact is the scout's estimate; once a proof is done, its proof (proof_summary on a list row) is the replayed result, always inferred, and the figure to quote.", "x-caveman-operation": "briefs.summary", "x-caveman-operation-contract": "70251a2e0c4e6f1b0936e7358b7740a9c4fde600bb14d8b302020075288e378c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "policy.budgets", "x-caveman-operation-contract": "a51dc31d72238393031b144e47295dcdf195be1772ac9ddf18baeebaeb720e59", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read", "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/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" } }, "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.", "x-caveman-operation": "plan.project_plan", "x-caveman-operation-contract": "37f2b02fa9cb3154455dac8a583f49f17ff271bd10ce2df5212052a866897b80", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/charts/catalog": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/charts/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" } }, "operationId": "getProjectsProjectIdChartsCatalog", "description": "GET /api/v1/projects/{projectId}/charts/catalog on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the catalog action of the caveman_charts tool (read access). Run a chart spec (time series, top list or big number) over requests, spans, tool executions or evals; open the traces behind a point; read the field catalog, presets, data-driven suggestions and filter values.", "x-caveman-operation": "charts.catalog", "x-caveman-operation-contract": "014f278521da502d5765a676255a94e2d16e85e173befe103931817d1b469c6b", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/charts/query": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/charts/query", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdChartsQuery", "description": "POST /api/v1/projects/{projectId}/charts/query on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the query action of the caveman_charts tool (read access). Run a chart spec (time series, top list or big number) over requests, spans, tool executions or evals; open the traces behind a point; read the field catalog, presets, data-driven suggestions and filter values.", "x-caveman-operation": "charts.query", "x-caveman-operation-contract": "c524d95e78a148ecc6782e03411c54de7e291ccce4aba4e824582906d6526085", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "chart": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "enum": [ "timeseries", "toplist", "bignumber" ] }, "source": { "enum": [ "requests", "spans", "tools", "evals" ] }, "preset": { "type": [ "string", "null" ] }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "field": { "type": "string" }, "agg": { "enum": [ "count", "sum", "avg", "min", "max", "count_distinct", "percentile" ] }, "p": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "expr": { "type": "string", "maxLength": 2000 } } }, "minItems": 1, "maxItems": 6 }, "filters": { "type": "object", "additionalProperties": false, "properties": { "row": { "type": "string", "maxLength": 2000 }, "trace": { "type": "string", "maxLength": 2000 } } }, "group_by": { "type": "string" }, "options": { "type": "object", "additionalProperties": false, "properties": { "unit": { "enum": [ "duration", "cost", "count", "percent", "bytes" ] }, "viz": { "enum": [ "line", "bar" ] }, "stacked": { "type": "boolean" }, "interval": { "enum": [ "auto", "hour", "day", "week" ] }, "sort": { "enum": [ "value_desc", "value_asc", "name_asc", "name_desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "layout": { "type": "object", "additionalProperties": false, "properties": { "w": { "enum": [ 3, 4, 6, 8, 12 ] }, "h": { "enum": [ 1, 2, 3 ] } }, "required": [ "w", "h" ] }, "section_id": { "type": [ "string", "null" ] } }, "required": [ "title", "type", "source", "measures" ] }, "range": { "type": "object", "additionalProperties": false, "properties": { "preset": { "enum": [ "1h", "6h", "24h", "3d", "7d", "14d", "30d", "60d", "90d" ] }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "dashboard": { "type": "object", "additionalProperties": false, "properties": { "filters": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 20 }, "search": { "type": "string", "maxLength": 200 }, "group_by": { "type": "string" } } } }, "required": [ "chart", "range" ] } } } }, "parameters": [ { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/charts/query-batch": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/charts/query-batch", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdChartsQueryBatch", "description": "POST /api/v1/projects/{projectId}/charts/query-batch on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: The dashboard view's own read: one line per chart, written as each finishes. An agent runs a chart with the charts query action, which answers one JSON document.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/charts/samples": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/charts/samples", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdChartsSamples", "description": "POST /api/v1/projects/{projectId}/charts/samples on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the samples action of the caveman_charts tool (read access). Run a chart spec (time series, top list or big number) over requests, spans, tool executions or evals; open the traces behind a point; read the field catalog, presets, data-driven suggestions and filter values.", "x-caveman-operation": "charts.samples", "x-caveman-operation-contract": "003bb575b438d069124f5a94ebf40f4c8abb2f292c06ff96b75f3bced59ba076", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "chart": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "enum": [ "timeseries", "toplist", "bignumber" ] }, "source": { "enum": [ "requests", "spans", "tools", "evals" ] }, "preset": { "type": [ "string", "null" ] }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "field": { "type": "string" }, "agg": { "enum": [ "count", "sum", "avg", "min", "max", "count_distinct", "percentile" ] }, "p": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "expr": { "type": "string", "maxLength": 2000 } } }, "minItems": 1, "maxItems": 6 }, "filters": { "type": "object", "additionalProperties": false, "properties": { "row": { "type": "string", "maxLength": 2000 }, "trace": { "type": "string", "maxLength": 2000 } } }, "group_by": { "type": "string" }, "options": { "type": "object", "additionalProperties": false, "properties": { "unit": { "enum": [ "duration", "cost", "count", "percent", "bytes" ] }, "viz": { "enum": [ "line", "bar" ] }, "stacked": { "type": "boolean" }, "interval": { "enum": [ "auto", "hour", "day", "week" ] }, "sort": { "enum": [ "value_desc", "value_asc", "name_asc", "name_desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "layout": { "type": "object", "additionalProperties": false, "properties": { "w": { "enum": [ 3, 4, 6, 8, 12 ] }, "h": { "enum": [ 1, 2, 3 ] } }, "required": [ "w", "h" ] }, "section_id": { "type": [ "string", "null" ] } }, "required": [ "title", "type", "source", "measures" ] }, "range": { "type": "object", "additionalProperties": false, "properties": { "preset": { "enum": [ "1h", "6h", "24h", "3d", "7d", "14d", "30d", "60d", "90d" ] }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "dashboard": { "type": "object", "additionalProperties": false, "properties": { "filters": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 20 }, "search": { "type": "string", "maxLength": 200 }, "group_by": { "type": "string" } } }, "group": { "type": [ "string", "null" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "chart", "range" ] } } } }, "parameters": [ { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/charts/values": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/charts/values", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdChartsValues", "description": "GET /api/v1/projects/{projectId}/charts/values on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the values action of the caveman_charts tool (read access). Run a chart spec (time series, top list or big number) over requests, spans, tool executions or evals; open the traces behind a point; read the field catalog, presets, data-driven suggestions and filter values.", "x-caveman-operation": "charts.values", "x-caveman-operation-contract": "c07e4a45791dac4f4f10a9c51188b3d6b96a1efdf63cf62acca297eec49b74a0", "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "field", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/ci/runs": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/ci/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" } }, "operationId": "postProjectsProjectIdCiRuns", "description": "POST /api/v1/projects/{projectId}/ci/runs on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Mints a spend-capped gateway key returned once to the caller. An agent must never mint credentials (the boundary POST /keys keeps).", "x-caveman-operation": "ci.start", "x-caveman-operation-contract": "c70bab039af16a1f381d42b32b5162d5a66800bc0156095368b2b24bc42a9cda", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "event": { "enum": [ "pull_request", "push", "merge_group" ] }, "pr_number": { "type": "integer", "minimum": 1 }, "base_sha": { "type": "string" }, "base_ref": { "type": "string" }, "job": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" }, "suite": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100 }, "matrix": { "type": "object" }, "test_ids_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "lockfile_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "max_usd": { "type": "number", "minimum": 0 }, "fork": { "type": "boolean" }, "request_id": { "type": "string", "format": "uuid" }, "repository_id": { "type": "integer", "minimum": 1 }, "sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "ref": { "type": "string" }, "run_id": { "type": "string", "pattern": "^[0-9]{1,20}$" }, "run_attempt": { "type": "integer", "minimum": 1 } }, "required": [ "request_id", "event", "job", "repository_id", "sha", "ref", "run_id", "run_attempt" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/ci/runs/{runId}/finish": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/ci/runs/{runId}/finish", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdCiRunsRunIdFinish", "description": "POST /api/v1/projects/{projectId}/ci/runs/{runId}/finish on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Reads or completes a run whose key was minted to a person or a CI identity. Agents read its verdict through verdicts.get.", "x-caveman-operation": "ci.finish", "x-caveman-operation-contract": "962bd166cc75629655f16720f7171b5fde37116ce4474d8c47468a3dc086e1a2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status": { "enum": [ "completed", "failed", "cancelled" ] }, "junit": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } }, "required": [ "status" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/ci/settings": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /projects/{projectId}/ci/settings", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdCiSettings", "description": "PUT /api/v1/projects/{projectId}/ci/settings on the Caveman Cloud control plane. Requires the experiment:approve_s3 scope. Not exposed to autonomous agents: Turning CI checks on lets the bound repository's workflows mint spend-capped gateway keys. It is an audited owner or admin decision.", "x-caveman-operation": "ci.set_checks", "x-caveman-operation-contract": "07618e486a449711e1488e9b90ed97ed711137fa3037ca3e465b2c85d80feac4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "checks_enabled": { "type": "boolean" } }, "required": [ "checks_enabled" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } }, "/projects/{projectId}/ci/suites": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/ci/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" } }, "operationId": "getProjectsProjectIdCiSuites", "description": "GET /api/v1/projects/{projectId}/ci/suites on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the ci_suites action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "ci.suites", "x-caveman-operation-contract": "13d83120d06dea03bcf83ad6846c03875998865a1255b1e737285a5281a3ed97", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/ci/suites/{suiteFingerprint}/mode": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "suiteFingerprint", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /projects/{projectId}/ci/suites/{suiteFingerprint}/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" } }, "operationId": "putProjectsProjectIdCiSuitesSuiteFingerprintMode", "description": "PUT /api/v1/projects/{projectId}/ci/suites/{suiteFingerprint}/mode on the Caveman Cloud control plane. Requires the experiment:approve_s3 scope. Not exposed to autonomous agents: Gate mode blocks merges. Changing it is an audited owner or admin decision (SPEC §4.12).", "x-caveman-operation": "ci.set_mode", "x-caveman-operation-contract": "c6100196f68933e57aa240cd07e1b6a17eaa3cdb564d20e6535252e9f53dbac9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "mode": { "enum": [ "advisory", "gate" ] }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } }, "/projects/{projectId}/cloud/operations/{operationId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/cloud/operations/{operationId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdCloudOperationsOperationId", "description": "POST /api/v1/projects/{projectId}/cloud/operations/{operationId} on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the execute_operation action of the caveman_project_setup tool (write access). Project settings for the bound project: semantic-cache shadowing and its options, pixel density, routing previews. Optimizations themselves are chosen per request (x-cave-optimize, x-cave-cache), not switched on here. Changing the semantic-cache threshold or TTL is refused server-side unless the caller holds policy:publish_s2_s3, which a scoped agent connection does not.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/connectors": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/connectors", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdConnectors", "description": "GET /api/v1/projects/{projectId}/connectors on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Connector rows exist to manage stored admin credentials. Agents never handle or enumerate credential state; the usage they sync is readable through the reports surfaces.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "post": { "summary": "POST /projects/{projectId}/connectors", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdConnectors", "description": "POST /api/v1/projects/{projectId}/connectors on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Accepts a provider ADMIN KEY in the request body. Agents never handle a credential -- the standing rule the connect skill restates -- so this door is human-only.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/projects/{projectId}/connectors/{connectorId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/connectors/{connectorId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdConnectorsConnectorId", "description": "DELETE /api/v1/projects/{projectId}/connectors/{connectorId} on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Revoking a stored admin credential is the human owner's decision, like every other credential lifecycle action.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/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" } }, "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.", "x-caveman-operation": "fixes.latest_improvement_report", "x-caveman-operation-contract": "5425db90371f71e1ee189e1b953aa6120766c7cd5ed9d3c7144c812d359fa21e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "fixes.get_improvement_report", "x-caveman-operation-contract": "d6a2d4eeb947f1afeba526c3ede9176802676202285cdef032760e3682ec0fa5", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/criteria": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/criteria", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdCriteria", "description": "GET /api/v1/projects/{projectId}/criteria on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_criteria action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "criteria.list", "x-caveman-operation-contract": "5469f536db542ea008136002722aa64d604af4e930ea1574b058070b6b9f5d21", "parameters": [ { "name": "workload_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "trust", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gating", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/criteria", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdCriteria", "description": "POST /api/v1/projects/{projectId}/criteria on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the create_criterion action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "criteria.create", "x-caveman-operation-contract": "0cf08a82ccae25166504c0128f0bc89f302aa4a35f3d8acc3f356e3ee125d8f7", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "question", "output_grader", "assertion", "code" ] }, "scope": { "enum": [ "span", "trace", "task", "row" ] }, "runtime": { "enum": [ "python", "javascript", "typescript" ] }, "source": { "type": "string", "maxLength": 32768 }, "min_score": { "type": "number", "minimum": 0, "maximum": 1 }, "judge": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "connection": { "type": "string", "minLength": 1, "maxLength": 200 }, "model_id": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } }, "required": [ "connection" ] }, { "type": "null" } ] }, "workload_id": { "type": [ "string", "null" ], "format": "uuid" }, "statement": { "type": "string", "maxLength": 500 }, "pass_def": { "type": "string" }, "fail_def": { "type": "string" }, "na_def": { "type": "string" }, "answer": { "enum": [ "pass_fail", "score", "category", "pairwise", "answer_match" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "grader_type": { "type": "string" }, "options": { "type": "object" }, "input_mapping": { "type": "object" }, "gating": { "type": "boolean" } }, "required": [ "name", "kind", "scope" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/criteria/{criterionId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "criterionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/criteria/{criterionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdCriteriaCriterionId", "description": "GET /api/v1/projects/{projectId}/criteria/{criterionId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_criterion action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "criteria.get", "x-caveman-operation-contract": "1bd8105b9f3889f257dc9225a29c67456b2952ee2148ebb21714bbd63b1327ed", "parameters": [ { "name": "version", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /projects/{projectId}/criteria/{criterionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdCriteriaCriterionId", "description": "PATCH /api/v1/projects/{projectId}/criteria/{criterionId} on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Criteria are the fixed scoring an improving agent is held to (ADR 0050). An agent must not edit or drop what it is scored on; it proposes, and a person changes them.", "x-caveman-operation": "criteria.edit", "x-caveman-operation-contract": "94b3357d85f30e1c986df6367bdb8c1fcf7ffd682f89d8dbb9473afb90785744", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "statement": { "type": "string", "maxLength": 500 }, "pass_def": { "type": "string" }, "fail_def": { "type": "string" }, "na_def": { "type": "string" }, "params": { "type": "object" }, "gating": { "type": "boolean" }, "judge": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "connection": { "type": "string", "minLength": 1, "maxLength": 200 }, "model_id": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } }, "required": [ "connection" ] }, { "type": "null" } ] } }, "required": [ "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/criteria/{criterionId}/skip": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "criterionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/criteria/{criterionId}/skip", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdCriteriaCriterionIdSkip", "description": "POST /api/v1/projects/{projectId}/criteria/{criterionId}/skip on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Criteria are the fixed scoring an improving agent is held to (ADR 0050). An agent must not edit or drop what it is scored on; it proposes, and a person changes them.", "x-caveman-operation": "criteria.skip", "x-caveman-operation-contract": "2c24be32ae7365f7e82627f7666dc67cb05a4b840f92b743222bc069ff608d9b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "action": { "enum": [ "skip", "restore" ] }, "reason": { "type": "string", "maxLength": 280 } }, "required": [ "revision", "action" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/criteria/{criterionId}/spot-check": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "criterionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/criteria/{criterionId}/spot-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" } }, "operationId": "postProjectsProjectIdCriteriaCriterionIdSpotCheck", "description": "POST /api/v1/projects/{projectId}/criteria/{criterionId}/spot-check on the Caveman Cloud control plane. Requires the payload:read scope. Not exposed to autonomous agents: Spot-check labels are human gold anchors for judge trust (SPEC §4.6). An agent cannot stand in for a human reviewer.", "x-caveman-operation": "spot_checks.next", "x-caveman-operation-contract": "0581f6e609183bd4ac7a490d90bcd2c8e5693dddc65411af120445fe021c539d", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/criteria/{criterionId}/trend": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "criterionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/criteria/{criterionId}/trend", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdCriteriaCriterionIdTrend", "description": "GET /api/v1/projects/{projectId}/criteria/{criterionId}/trend on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the criterion_trend action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "criteria.trend", "x-caveman-operation-contract": "1e59c96a190ad2c5ae2e4198e2423efaea79adf5ef8a37c454e0aa5bbf39c869", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "compare_from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "compare_to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "compare_a", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "compare_b", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/criteria/{criterionId}/trust": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "criterionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/criteria/{criterionId}/trust", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdCriteriaCriterionIdTrust", "description": "GET /api/v1/projects/{projectId}/criteria/{criterionId}/trust on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the criterion_trust action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "criteria.trust", "x-caveman-operation-contract": "d76bcd8fbfe83b35ba0063ffc586639e026a0ef6f19e49df2d259d710d76bbd0", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/criteria/{criterionId}/turn-on": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "criterionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/criteria/{criterionId}/turn-on", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdCriteriaCriterionIdTurnOn", "description": "POST /api/v1/projects/{projectId}/criteria/{criterionId}/turn-on on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Turning a criterion on starts grading and spends the judge budget set for it (ADR 0096). An agent proposes what to track; a person decides it runs.", "x-caveman-operation": "criteria.turn_on", "x-caveman-operation-contract": "c96e22e60cdaed805c0b2f76f56f16c2e3e8e8849ace338de214504882e30cb9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "daily_budget_usd": { "type": "number", "minimum": 0, "maximum": 1000000 } }, "required": [ "revision", "daily_budget_usd" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/criteria/{criterionId}/versions": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "criterionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/criteria/{criterionId}/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" } }, "operationId": "getProjectsProjectIdCriteriaCriterionIdVersions", "description": "GET /api/v1/projects/{projectId}/criteria/{criterionId}/versions on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the criterion_versions action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "criteria.versions", "x-caveman-operation-contract": "09d54d1af8634a94f59ce9f3a998ff76eae2c4ca128a4489f41e10b79cefaeae", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/criteria/{criterionId}/versions/{version}/restore": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "criterionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/criteria/{criterionId}/versions/{version}/restore", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdCriteriaCriterionIdVersionsVersionRestore", "description": "POST /api/v1/projects/{projectId}/criteria/{criterionId}/versions/{version}/restore on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Criteria are the fixed scoring an improving agent is held to (ADR 0050). An agent must not edit or drop what it is scored on; it proposes, and a person changes them.", "x-caveman-operation": "criteria.restore_version", "x-caveman-operation-contract": "48c2484905e68931567b8b4d3a7f7c79a4eb62be82f94bbc442ccb50c30124ca", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/criteria/catalog": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/criteria/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" } }, "operationId": "getProjectsProjectIdCriteriaCatalog", "description": "GET /api/v1/projects/{projectId}/criteria/catalog on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the criteria_catalog action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "criteria.catalog", "x-caveman-operation-contract": "93da781c03626c48234d70ececc53ce9aac730f989b39d7fd73212b74d97e850", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/criteria/proposals": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/criteria/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" } }, "operationId": "postProjectsProjectIdCriteriaProposals", "description": "POST /api/v1/projects/{projectId}/criteria/proposals on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the propose_criterion action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "criteria.propose", "x-caveman-operation-contract": "b35be6248c339b080813bcd6ad997c663fbc296b70d1d957a578560db39f684d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "workload_id": { "type": [ "string", "null" ], "format": "uuid" }, "scope": { "enum": [ "span", "trace", "task" ] }, "level": { "enum": [ "step", "outcome" ] }, "kind": { "enum": [ "assertion", "question", "output_grader", "code" ] }, "statement": { "type": "string", "maxLength": 500 }, "pass_def": { "type": "string" }, "fail_def": { "type": "string" }, "na_def": { "type": "string" }, "selector": { "type": "object" }, "params": { "type": "object" }, "code": { "type": "object", "additionalProperties": false, "properties": { "ref": { "type": "string", "maxLength": 500 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "ref", "sha256" ] }, "motivating_units": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "scope": { "enum": [ "span", "trace", "task" ] }, "unit_id": { "type": "string", "minLength": 1, "maxLength": 512 }, "task_key": { "type": [ "string", "null" ] }, "trace_id": { "type": [ "string", "null" ] }, "cell_id": { "type": [ "string", "null" ] } }, "required": [ "scope", "unit_id" ] }, "maxItems": 5 } }, "required": [ "scope", "level", "kind", "statement" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/criteria/test": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/criteria/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" } }, "operationId": "postProjectsProjectIdCriteriaTest", "description": "POST /api/v1/projects/{projectId}/criteria/test on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the test_criterion action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "criteria.test", "x-caveman-operation-contract": "33b18cfa12f380b249718f4c5e6368d69041689282246a14e2eb6c6d78638f71", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "criterion": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "question", "output_grader", "assertion", "code" ] }, "scope": { "enum": [ "span", "trace", "task", "row" ] }, "runtime": { "enum": [ "python", "javascript", "typescript" ] }, "source": { "type": "string", "maxLength": 32768 }, "min_score": { "type": "number", "minimum": 0, "maximum": 1 }, "judge": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "connection": { "type": "string", "minLength": 1, "maxLength": 200 }, "model_id": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } }, "required": [ "connection" ] }, { "type": "null" } ] }, "workload_id": { "type": [ "string", "null" ], "format": "uuid" }, "statement": { "type": "string", "maxLength": 500 }, "pass_def": { "type": "string" }, "fail_def": { "type": "string" }, "na_def": { "type": "string" }, "answer": { "enum": [ "pass_fail", "score", "category", "pairwise", "answer_match" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "grader_type": { "type": "string" }, "options": { "type": "object" }, "input_mapping": { "type": "object" }, "gating": { "type": "boolean" } }, "required": [ "kind", "scope" ] }, { "type": "object", "additionalProperties": false, "properties": { "criterion_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "criterion_id" ] } ] }, "on": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "recent" }, "scope": { "enum": [ "trace", "task" ] }, "workload_id": { "type": [ "string", "null" ], "format": "uuid" }, "window_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "filter": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "maxItems": 32 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 } }, "required": [ "kind", "scope" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "dataset" }, "dataset_id": { "type": "string", "format": "uuid" }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 } }, "required": [ "kind", "dataset_id" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "inline" }, "input": {}, "output": {}, "expected": {}, "baseline": {}, "metadata": { "type": "object" } }, "required": [ "kind", "output" ] } ] } }, "required": [ "criterion", "on" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/criteria/track": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/criteria/track", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdCriteriaTrack", "description": "POST /api/v1/projects/{projectId}/criteria/track on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the track_criterion action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "criteria.track", "x-caveman-operation-contract": "52f494571b086533f3080b2c0b9bbe9586e106a4e97f40db728fcd293606ca43", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 500 }, "pass_def": { "type": "string" }, "fail_def": { "type": "string" }, "na_def": { "type": "string" }, "scope": { "enum": [ "trace", "task" ] }, "level": { "enum": [ "step", "outcome" ] }, "filter": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "maxItems": 32 }, "sample_rate": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "daily_budget_usd": { "type": "number", "minimum": 0, "maximum": 1000000 }, "backfill": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "max_units": { "type": "integer", "minimum": 1, "maximum": 10000 }, "filter": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "maxItems": 32 }, "criterion_id": { "type": "string", "format": "uuid" }, "budget_usd": { "type": "number", "minimum": 0, "maximum": 1000000 } }, "required": [ "from", "to" ] } }, "required": [ "statement", "daily_budget_usd" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/dashboards": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/dashboards", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdDashboards", "description": "GET /api/v1/projects/{projectId}/dashboards on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list action of the caveman_dashboards tool (read access). The project's custom dashboards and the read-only built-ins (Cost and quality, Coding agent insights), with every chart's spec.", "x-caveman-operation": "dashboards.list", "x-caveman-operation-contract": "58937abfbe34874048d99c0024c982bcebdc588a926fbd4efd7ea35fef1c60f4", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/dashboards", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdDashboards", "description": "POST /api/v1/projects/{projectId}/dashboards on the Caveman Cloud control plane. Requires the dashboard:write scope. Exposed to autonomous agents as the create action of the caveman_dashboards_write tool (write access). Create, clone, rename and delete project dashboards, and add, change or remove one chart at a time. Every saved chart must compile; verify it with charts.query first.", "x-caveman-operation": "dashboards.create", "x-caveman-operation-contract": "c5a28bf3d1180ef37bd86434b2c565ade81758198d1649ff71cf433d6fc3d9e9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "enum": [ "logs", "experiments" ] }, "document": { "type": "object", "additionalProperties": false, "properties": { "filters": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 20 }, "search": { "type": "string", "maxLength": 200 }, "group_by": { "type": "string" }, "range": { "type": "object", "additionalProperties": false, "properties": { "preset": { "enum": [ "1h", "6h", "24h", "3d", "7d", "14d", "30d", "60d", "90d" ] }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "sections": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "maxLength": 120 } }, "required": [ "title" ] }, "maxItems": 20 }, "charts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "enum": [ "timeseries", "toplist", "bignumber" ] }, "source": { "enum": [ "requests", "spans", "tools", "evals" ] }, "preset": { "type": [ "string", "null" ] }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "field": { "type": "string" }, "agg": { "enum": [ "count", "sum", "avg", "min", "max", "count_distinct", "percentile" ] }, "p": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "expr": { "type": "string", "maxLength": 2000 } } }, "minItems": 1, "maxItems": 6 }, "filters": { "type": "object", "additionalProperties": false, "properties": { "row": { "type": "string", "maxLength": 2000 }, "trace": { "type": "string", "maxLength": 2000 } } }, "group_by": { "type": "string" }, "options": { "type": "object", "additionalProperties": false, "properties": { "unit": { "enum": [ "duration", "cost", "count", "percent", "bytes" ] }, "viz": { "enum": [ "line", "bar" ] }, "stacked": { "type": "boolean" }, "interval": { "enum": [ "auto", "hour", "day", "week" ] }, "sort": { "enum": [ "value_desc", "value_asc", "name_asc", "name_desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "layout": { "type": "object", "additionalProperties": false, "properties": { "w": { "enum": [ 3, 4, 6, 8, 12 ] }, "h": { "enum": [ 1, 2, 3 ] } }, "required": [ "w", "h" ] }, "section_id": { "type": [ "string", "null" ] } }, "required": [ "title", "type", "source", "measures" ] }, "maxItems": 60 } } }, "source_dashboard_id": { "type": "string" } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "dashboard:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "dashboard:write" ] } }, "/projects/{projectId}/dashboards/{dashboardId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dashboardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/dashboards/{dashboardId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdDashboardsDashboardId", "description": "DELETE /api/v1/projects/{projectId}/dashboards/{dashboardId} on the Caveman Cloud control plane. Requires the dashboard:write scope. Exposed to autonomous agents as the delete action of the caveman_dashboards_write tool (write access). Create, clone, rename and delete project dashboards, and add, change or remove one chart at a time. Every saved chart must compile; verify it with charts.query first.", "x-caveman-operation": "dashboards.delete", "x-caveman-operation-contract": "0d1b3997a3e5b9224231fd82a847e9e4a493f154c548948e069673b8d3af1e9c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "dashboard:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "dashboard:write" ] }, "get": { "summary": "GET /projects/{projectId}/dashboards/{dashboardId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdDashboardsDashboardId", "description": "GET /api/v1/projects/{projectId}/dashboards/{dashboardId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get action of the caveman_dashboards tool (read access). The project's custom dashboards and the read-only built-ins (Cost and quality, Coding agent insights), with every chart's spec.", "x-caveman-operation": "dashboards.get", "x-caveman-operation-contract": "bf0d04d58baf37bc5ab9848823be43f0d9f57fcbb8a433259054f4ac42a0b29c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /projects/{projectId}/dashboards/{dashboardId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdDashboardsDashboardId", "description": "PATCH /api/v1/projects/{projectId}/dashboards/{dashboardId} on the Caveman Cloud control plane. Requires the dashboard:write scope. Exposed to autonomous agents as the update action of the caveman_dashboards_write tool (write access). Create, clone, rename and delete project dashboards, and add, change or remove one chart at a time. Every saved chart must compile; verify it with charts.query first.", "x-caveman-operation": "dashboards.update", "x-caveman-operation-contract": "197990cf8812da4364fd13f22fd51670e55d9ef9ec90ccd7a6689a0b3e218e9b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "starred": { "type": "boolean" }, "document": { "type": "object", "additionalProperties": false, "properties": { "filters": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 20 }, "search": { "type": "string", "maxLength": 200 }, "group_by": { "type": "string" }, "range": { "type": "object", "additionalProperties": false, "properties": { "preset": { "enum": [ "1h", "6h", "24h", "3d", "7d", "14d", "30d", "60d", "90d" ] }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "sections": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "maxLength": 120 } }, "required": [ "title" ] }, "maxItems": 20 }, "charts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "enum": [ "timeseries", "toplist", "bignumber" ] }, "source": { "enum": [ "requests", "spans", "tools", "evals" ] }, "preset": { "type": [ "string", "null" ] }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "field": { "type": "string" }, "agg": { "enum": [ "count", "sum", "avg", "min", "max", "count_distinct", "percentile" ] }, "p": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "expr": { "type": "string", "maxLength": 2000 } } }, "minItems": 1, "maxItems": 6 }, "filters": { "type": "object", "additionalProperties": false, "properties": { "row": { "type": "string", "maxLength": 2000 }, "trace": { "type": "string", "maxLength": 2000 } } }, "group_by": { "type": "string" }, "options": { "type": "object", "additionalProperties": false, "properties": { "unit": { "enum": [ "duration", "cost", "count", "percent", "bytes" ] }, "viz": { "enum": [ "line", "bar" ] }, "stacked": { "type": "boolean" }, "interval": { "enum": [ "auto", "hour", "day", "week" ] }, "sort": { "enum": [ "value_desc", "value_asc", "name_asc", "name_desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "layout": { "type": "object", "additionalProperties": false, "properties": { "w": { "enum": [ 3, 4, 6, 8, 12 ] }, "h": { "enum": [ 1, 2, 3 ] } }, "required": [ "w", "h" ] }, "section_id": { "type": [ "string", "null" ] } }, "required": [ "title", "type", "source", "measures" ] }, "maxItems": 60 } } } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "dashboard:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "dashboard:write" ] } }, "/projects/{projectId}/dashboards/{dashboardId}/charts": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dashboardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/dashboards/{dashboardId}/charts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdDashboardsDashboardIdCharts", "description": "POST /api/v1/projects/{projectId}/dashboards/{dashboardId}/charts on the Caveman Cloud control plane. Requires the dashboard:write scope. Exposed to autonomous agents as the add_chart action of the caveman_dashboards_write tool (write access). Create, clone, rename and delete project dashboards, and add, change or remove one chart at a time. Every saved chart must compile; verify it with charts.query first.", "x-caveman-operation": "dashboards.add_chart", "x-caveman-operation-contract": "5f982a1c804aee5c42f2ddf82dcd13db72604c8f5a3fe26e328986e47736df7d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "chart": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "enum": [ "timeseries", "toplist", "bignumber" ] }, "source": { "enum": [ "requests", "spans", "tools", "evals" ] }, "preset": { "type": [ "string", "null" ] }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "field": { "type": "string" }, "agg": { "enum": [ "count", "sum", "avg", "min", "max", "count_distinct", "percentile" ] }, "p": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "expr": { "type": "string", "maxLength": 2000 } } }, "minItems": 1, "maxItems": 6 }, "filters": { "type": "object", "additionalProperties": false, "properties": { "row": { "type": "string", "maxLength": 2000 }, "trace": { "type": "string", "maxLength": 2000 } } }, "group_by": { "type": "string" }, "options": { "type": "object", "additionalProperties": false, "properties": { "unit": { "enum": [ "duration", "cost", "count", "percent", "bytes" ] }, "viz": { "enum": [ "line", "bar" ] }, "stacked": { "type": "boolean" }, "interval": { "enum": [ "auto", "hour", "day", "week" ] }, "sort": { "enum": [ "value_desc", "value_asc", "name_asc", "name_desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "layout": { "type": "object", "additionalProperties": false, "properties": { "w": { "enum": [ 3, 4, 6, 8, 12 ] }, "h": { "enum": [ 1, 2, 3 ] } }, "required": [ "w", "h" ] }, "section_id": { "type": [ "string", "null" ] } }, "required": [ "title", "type", "source", "measures" ] }, "section_id": { "type": [ "string", "null" ] } }, "required": [ "chart" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "dashboard:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "dashboard:write" ] } }, "/projects/{projectId}/dashboards/{dashboardId}/charts/{chartId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dashboardId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chartId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/dashboards/{dashboardId}/charts/{chartId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdDashboardsDashboardIdChartsChartId", "description": "DELETE /api/v1/projects/{projectId}/dashboards/{dashboardId}/charts/{chartId} on the Caveman Cloud control plane. Requires the dashboard:write scope. Exposed to autonomous agents as the delete_chart action of the caveman_dashboards_write tool (write access). Create, clone, rename and delete project dashboards, and add, change or remove one chart at a time. Every saved chart must compile; verify it with charts.query first.", "x-caveman-operation": "dashboards.delete_chart", "x-caveman-operation-contract": "9958dc69c51774605620e9540f92bd51267d7c2eaee47f7a455c9efb3b0b3913", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "dashboard:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "dashboard:write" ] }, "patch": { "summary": "PATCH /projects/{projectId}/dashboards/{dashboardId}/charts/{chartId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdDashboardsDashboardIdChartsChartId", "description": "PATCH /api/v1/projects/{projectId}/dashboards/{dashboardId}/charts/{chartId} on the Caveman Cloud control plane. Requires the dashboard:write scope. Exposed to autonomous agents as the update_chart action of the caveman_dashboards_write tool (write access). Create, clone, rename and delete project dashboards, and add, change or remove one chart at a time. Every saved chart must compile; verify it with charts.query first.", "x-caveman-operation": "dashboards.update_chart", "x-caveman-operation-contract": "a3fdf4b93acbbbd5953d845cb5f38f47caafc88fe7372f95e0140e231b6d57b6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "chart": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "enum": [ "timeseries", "toplist", "bignumber" ] }, "source": { "enum": [ "requests", "spans", "tools", "evals" ] }, "preset": { "type": [ "string", "null" ] }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "field": { "type": "string" }, "agg": { "enum": [ "count", "sum", "avg", "min", "max", "count_distinct", "percentile" ] }, "p": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "expr": { "type": "string", "maxLength": 2000 } } }, "minItems": 1, "maxItems": 6 }, "filters": { "type": "object", "additionalProperties": false, "properties": { "row": { "type": "string", "maxLength": 2000 }, "trace": { "type": "string", "maxLength": 2000 } } }, "group_by": { "type": "string" }, "options": { "type": "object", "additionalProperties": false, "properties": { "unit": { "enum": [ "duration", "cost", "count", "percent", "bytes" ] }, "viz": { "enum": [ "line", "bar" ] }, "stacked": { "type": "boolean" }, "interval": { "enum": [ "auto", "hour", "day", "week" ] }, "sort": { "enum": [ "value_desc", "value_asc", "name_asc", "name_desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "layout": { "type": "object", "additionalProperties": false, "properties": { "w": { "enum": [ 3, 4, 6, 8, 12 ] }, "h": { "enum": [ 1, 2, 3 ] } }, "required": [ "w", "h" ] }, "section_id": { "type": [ "string", "null" ] } } } }, "required": [ "chart" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "dashboard:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "dashboard:write" ] } }, "/projects/{projectId}/eval-annotations": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-annotations", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalAnnotations", "description": "GET /api/v1/projects/{projectId}/eval-annotations on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the list_annotation_queue action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.list_annotation_queue", "x-caveman-operation-contract": "e42d67afad56748f7b19eb9f850c3a596a1b49263f2c479530ec4550e0527b66", "parameters": [ { "name": "assignee_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/eval-annotations/{annotationId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "annotationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /projects/{projectId}/eval-annotations/{annotationId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdEvalAnnotationsAnnotationId", "description": "PATCH /api/v1/projects/{projectId}/eval-annotations/{annotationId} on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Changes human review labels, assignments or resolution state. Agents can read review state but cannot impersonate a human reviewer.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-baseline": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-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" } }, "operationId": "getProjectsProjectIdEvalBaseline", "description": "GET /api/v1/projects/{projectId}/eval-baseline on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_baseline action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.get_baseline", "x-caveman-operation-contract": "ae0bbf01e315132e39b147f9bb4dc0ed44bcd2d8d2b735e7231bab9bdc8f1861", "parameters": [ { "name": "workbench_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "put": { "summary": "PUT /projects/{projectId}/eval-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" } }, "operationId": "putProjectsProjectIdEvalBaseline", "description": "PUT /api/v1/projects/{projectId}/eval-baseline on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the set_baseline action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.set_baseline", "x-caveman-operation-contract": "e2994c27e068dd5165b0dcb61fda7d8f27e4635bb905cd249292230f44773ce9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "workbench_id": { "type": [ "string", "null" ], "format": "uuid" }, "run_id": { "type": [ "string", "null" ], "format": "uuid" }, "target_key": { "type": "string", "maxLength": 96 }, "gate_policy": { "enum": [ "kernel", "strict" ], "description": "The policy the experiment's comparisons are read by when a comparison names none: kernel follows the statistics, strict fails when any criterion got worse on any case. Needs workbench_id. Sent without run_id it leaves the baseline as it is." } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-datasets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalDatasets", "description": "GET /api/v1/projects/{projectId}/eval-datasets on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_datasets action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "datasets.list", "x-caveman-operation-contract": "df4c089a6973d4bc7545a4903a7e60c5462ce61019700f3cb2a5549eca7c35c3", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/eval-datasets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalDatasets", "description": "POST /api/v1/projects/{projectId}/eval-datasets on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the create_dataset action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.create", "x-caveman-operation-contract": "ece37a703198f606ad5a25f35faefb993a3c18c40a9d60b0393a17fce2868d0d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "document": { "title": "Caveman evaluation dataset", "description": "Canonical dataset snapshot used by an evaluation workbench run.", "type": "object", "required": [ "schema_version", "columns", "rows" ], "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "columns": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "object", "required": [ "key", "name", "type", "role" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "enum": [ "string", "number", "boolean", "json", "image_url", "messages" ] }, "role": { "enum": [ "input", "expected", "metadata", "output" ] } } } }, "rows": { "type": "array", "maxItems": 10000, "items": { "type": "object", "required": [ "row_key", "values" ], "additionalProperties": false, "properties": { "row_key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "values": { "type": "object" }, "tags": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "uniqueItems": true } } } } } }, "upsert": { "type": "boolean", "description": "Update the live resource of this name in the project instead of refusing the name. A dataset whose rows are unchanged is left as it is, so its next run reuses its version." } }, "required": [ "name", "document" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/eval-datasets/{datasetId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdEvalDatasetsDatasetId", "description": "DELETE /api/v1/projects/{projectId}/eval-datasets/{datasetId} on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Archives a shared evaluation dataset and removes it from authoring flows. Agents may create and version datasets; a human retires shared evidence assets.", "x-caveman-operation": "datasets.archive", "x-caveman-operation-contract": "13eb866e37a149fc46b6225a9aa6711d9cf9e98586ceb0a1bd299be5a63fc6ef", "parameters": [ { "name": "revision", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] }, "get": { "summary": "GET /projects/{projectId}/eval-datasets/{datasetId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalDatasetsDatasetId", "description": "GET /api/v1/projects/{projectId}/eval-datasets/{datasetId} on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_dataset action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "datasets.get", "x-caveman-operation-contract": "f19ddaaf9ac0a43dd4e6af6ccfe6f0db70b78217da2432cea3bc37a01ae34416", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] }, "put": { "summary": "PUT /projects/{projectId}/eval-datasets/{datasetId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdEvalDatasetsDatasetId", "description": "PUT /api/v1/projects/{projectId}/eval-datasets/{datasetId} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the update_dataset action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.update", "x-caveman-operation-contract": "ef9265c434378cb879b708f85d918511e5268ca4c285bcdd52b4f6c741eef7b5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "document": { "title": "Caveman evaluation dataset", "description": "Canonical dataset snapshot used by an evaluation workbench run.", "type": "object", "required": [ "schema_version", "columns", "rows" ], "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "columns": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "object", "required": [ "key", "name", "type", "role" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "enum": [ "string", "number", "boolean", "json", "image_url", "messages" ] }, "role": { "enum": [ "input", "expected", "metadata", "output" ] } } } }, "rows": { "type": "array", "maxItems": 10000, "items": { "type": "object", "required": [ "row_key", "values" ], "additionalProperties": false, "properties": { "row_key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "values": { "type": "object" }, "tags": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "uniqueItems": true } } } } } } }, "required": [ "revision", "name", "document" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/diff": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-datasets/{datasetId}/diff", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalDatasetsDatasetIdDiff", "description": "GET /api/v1/projects/{projectId}/eval-datasets/{datasetId}/diff on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the diff_dataset action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "datasets.diff", "x-caveman-operation-contract": "6959913dd22e63aed88dc1b4bc7d3f3643e9dbc6ee05c0e7046cd096e50b851b", "parameters": [ { "name": "from_version", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to_version", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/export": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-datasets/{datasetId}/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" } }, "operationId": "getProjectsProjectIdEvalDatasetsDatasetIdExport", "description": "GET /api/v1/projects/{projectId}/eval-datasets/{datasetId}/export on the Caveman Cloud control plane. Requires the payload:read scope. Not exposed to autonomous agents: Downloads a dataset's rows as a CSV or JSONL file. Bulk data egress as a file requires a human actor; an agent reads the same rows as JSON through get_dataset and get_dataset_version.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/generate": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-datasets/{datasetId}/generate", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalDatasetsDatasetIdGenerate", "description": "POST /api/v1/projects/{projectId}/eval-datasets/{datasetId}/generate on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Spends on the project's own model keys the moment it is asked for, up to budget_usd. An agent files it as an eval proposal (kind dataset, action generate) for a person to accept, and reads the rows it proposes.", "x-caveman-operation": "datasets.generate", "x-caveman-operation-contract": "ace6e16c1169e7b3c8ca87b181687d5a4dcba9a03a8d5b499209f919f028655d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string", "maxLength": 2000 }, "seed_row_keys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" }, "maxItems": 10 }, "count": { "type": "integer", "minimum": 1, "maximum": 50 }, "provider": { "type": "string", "minLength": 1 }, "model": { "type": "string", "minLength": 1 }, "budget_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 5 } }, "required": [ "provider", "model" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/import": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-datasets/{datasetId}/import", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalDatasetsDatasetIdImport", "description": "POST /api/v1/projects/{projectId}/eval-datasets/{datasetId}/import on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the import_dataset action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.import", "x-caveman-operation-contract": "e1e5238d47accafbf840a94ed994c74a889f61361928e5dfcca571c2ec60d75b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "format": { "enum": [ "csv", "jsonl" ] }, "data": { "type": "string", "minLength": 1 } }, "required": [ "format", "data" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/proposals": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-datasets/{datasetId}/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" } }, "operationId": "getProjectsProjectIdEvalDatasetsDatasetIdProposals", "description": "GET /api/v1/projects/{projectId}/eval-datasets/{datasetId}/proposals on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the list_dataset_proposals action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "datasets.proposals", "x-caveman-operation-contract": "15c3e30ae630da0ebe7b69caf075a8af5e9b8daec913ef355b1d0b4415fe5838", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/proposals/{proposalId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-datasets/{datasetId}/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" } }, "operationId": "getProjectsProjectIdEvalDatasetsDatasetIdProposalsProposalId", "description": "GET /api/v1/projects/{projectId}/eval-datasets/{datasetId}/proposals/{proposalId} on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_dataset_proposal action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "datasets.proposal", "x-caveman-operation-contract": "2a22032c6a3cb58bba4b64be000d89263d93a61853a4b2e8443c07794e310975", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/proposals/{proposalId}/decision": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-datasets/{datasetId}/proposals/{proposalId}/decision", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectEvalDatasetsDatasetProposalsProposalDecision", "description": "POST /api/v1/projects/{projectId}/eval-datasets/{datasetId}/proposals/{proposalId}/decision on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the decide_dataset_proposal action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.decide_proposal", "x-caveman-operation-contract": "6bae870c1adcbec476ee53eb2b7d70e0961d94f1a9d0a65c28d1f9e478216244", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "decision": { "enum": [ "accept", "reject" ] }, "row_keys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" }, "maxItems": 50 } }, "required": [ "decision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/rows": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /projects/{projectId}/eval-datasets/{datasetId}/rows", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdEvalDatasetsDatasetIdRows", "description": "PATCH /api/v1/projects/{projectId}/eval-datasets/{datasetId}/rows on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the update_dataset_rows action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.rows_update", "x-caveman-operation-contract": "68db4457f09d2cbbbaa205ac1e86976047e817d65b7acf6fa5db656a8e5763e2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "row_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" }, "revision": { "type": "integer", "minimum": 1 }, "values": { "type": "object" }, "tags": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "split": { "type": "string", "pattern": "^$|^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" } }, "required": [ "row_key" ] }, "minItems": 1, "maxItems": 500 } }, "required": [ "rows" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] }, "post": { "summary": "POST /projects/{projectId}/eval-datasets/{datasetId}/rows", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalDatasetsDatasetIdRows", "description": "POST /api/v1/projects/{projectId}/eval-datasets/{datasetId}/rows on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the add_dataset_rows action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.rows_add", "x-caveman-operation-contract": "4f7ef06f8825396847fbed11a06f41939fd4271c59f1f0c8f7ad05cbbefdf709", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "row_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" }, "values": { "type": "object" }, "tags": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "split": { "type": "string", "pattern": "^$|^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" } }, "required": [ "values" ] }, "minItems": 1, "maxItems": 500 } }, "required": [ "rows" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/rows/delete": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-datasets/{datasetId}/rows/delete", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalDatasetsDatasetIdRowsDelete", "description": "POST /api/v1/projects/{projectId}/eval-datasets/{datasetId}/rows/delete on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the delete_dataset_rows action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.rows_delete", "x-caveman-operation-contract": "0295a841d1415808a26492e139adc6c84ee54f847e158f4bd7e0eaff1e8afe55", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "row_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "row_key" ] }, "minItems": 1, "maxItems": 500 } }, "required": [ "rows" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/versions": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-datasets/{datasetId}/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" } }, "operationId": "getProjectsProjectIdEvalDatasetsDatasetIdVersions", "description": "GET /api/v1/projects/{projectId}/eval-datasets/{datasetId}/versions on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_dataset_versions action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "datasets.versions", "x-caveman-operation-contract": "e7a8d437767d9c13b872cad1971fefda0dbfee7eaecd86155b5f1da5a767841a", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/eval-datasets/{datasetId}/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" } }, "operationId": "postProjectsProjectIdEvalDatasetsDatasetIdVersions", "description": "POST /api/v1/projects/{projectId}/eval-datasets/{datasetId}/versions on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the snapshot_dataset action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.snapshot", "x-caveman-operation-contract": "10fc4692f3c18d905b19cada050b0df262f45dcb29b11d41abb576cdc65ae3aa", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "source": { "type": "object", "additionalProperties": true } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/versions/{version}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-datasets/{datasetId}/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" } }, "operationId": "getProjectsProjectIdEvalDatasetsDatasetIdVersionsVersion", "description": "GET /api/v1/projects/{projectId}/eval-datasets/{datasetId}/versions/{version} on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_dataset_version action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "datasets.version", "x-caveman-operation-contract": "dd3bfe449269ccc902062389878ee162eb4b9a4f36b7e99c1f51c7086e4121ac", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] }, "patch": { "summary": "PATCH /projects/{projectId}/eval-datasets/{datasetId}/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" } }, "operationId": "patchProjectsProjectIdEvalDatasetsDatasetIdVersionsVersion", "description": "PATCH /api/v1/projects/{projectId}/eval-datasets/{datasetId}/versions/{version} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the name_dataset_version action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.name_version", "x-caveman-operation-contract": "3b9575e39810f800ae118fa439fbe3ee566ddb85b7394b30f77dc8814e5d7002", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 } }, "required": [ "name" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets/{datasetId}/versions/{version}/restore": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-datasets/{datasetId}/versions/{version}/restore", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalDatasetsDatasetIdVersionsVersionRestore", "description": "POST /api/v1/projects/{projectId}/eval-datasets/{datasetId}/versions/{version}/restore on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the restore_dataset_version action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.restore", "x-caveman-operation-contract": "8ca3b1ca0e322c455f73a1b4cfb436e33cfd56746b797681222e614b891bd946", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-datasets/from-traffic": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-datasets/from-traffic", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalDatasetsFromTraffic", "description": "POST /api/v1/projects/{projectId}/eval-datasets/from-traffic on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the dataset_from_traffic action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "datasets.from_traffic", "x-caveman-operation-contract": "b8e0a2e20ffe504de2f57f32b5551575a11b8871f7f64c31e4edca7b8e9c4b41", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "dataset_id": { "type": "string", "format": "uuid" }, "scope": { "enum": [ "span", "trace", "task" ] }, "filter": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "maxItems": 32 }, "window_hours": { "type": "integer", "minimum": 1, "maximum": 720 }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 }, "verdict": { "type": "object", "additionalProperties": false, "properties": { "criterion_id": { "type": "string", "format": "uuid" }, "is": { "enum": [ "failed", "passed" ] } }, "required": [ "criterion_id", "is" ] }, "columns": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "boolean" }, "output": { "type": "boolean" }, "expected_from_output": { "type": "boolean" }, "metadata": { "type": "array", "items": { "enum": [ "cost_usd", "errors", "model", "scope", "status", "steps", "tool_calls", "trace_id", "unit_id" ] } } }, "required": [ "input" ] } }, "required": [ "scope" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-drafts": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-drafts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalDrafts", "description": "GET /api/v1/projects/{projectId}/eval-drafts on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_eval_drafts action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "eval_drafts.list", "x-caveman-operation-contract": "ff019be7770bf64e0959e8f62639ac52819de85872c4d498501c4bf65ab63105", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/eval-drafts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalDrafts", "description": "POST /api/v1/projects/{projectId}/eval-drafts on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the draft_evals_from_traffic action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "eval_drafts.request", "x-caveman-operation-contract": "964849168e02905345bcac6e45755fa88be8ef9d9275ffd120818257213b5d00", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-drafts/{runId}/approve": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-drafts/{runId}/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" } }, "operationId": "postProjectsProjectIdEvalDraftsRunIdApprove", "description": "POST /api/v1/projects/{projectId}/eval-drafts/{runId}/approve on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Approving a drafted suite makes its datasets and qualified criteria active for every comparison. A person decides.", "x-caveman-operation": "eval_drafts.approve", "x-caveman-operation-contract": "775c941c250b45b57004fcceca22d4b7be4df23ac227d7c8de0ca7f666056006", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/eval-drafts/{runId}/decline": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-drafts/{runId}/decline", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalDraftsRunIdDecline", "description": "POST /api/v1/projects/{projectId}/eval-drafts/{runId}/decline on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Declining a drafted suite discards what Caveman drafted. A person decides.", "x-caveman-operation": "eval_drafts.decline", "x-caveman-operation-contract": "2a428d20c6e062a6a694a864d9e3694be81c27fcf787071a83420ada88e60de7", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/eval-evaluators": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-evaluators", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalEvaluators", "description": "GET /api/v1/projects/{projectId}/eval-evaluators on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_evaluators action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evaluators.list", "x-caveman-operation-contract": "55db15d293536d670bc23f9d5f610b1752a6dead2e6bdfc4db3eb50694484d35", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/eval-evaluators", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalEvaluators", "description": "POST /api/v1/projects/{projectId}/eval-evaluators on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the create_evaluator action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evaluators.create", "x-caveman-operation-contract": "7de7cc70b04eae67398d4086d13755785ba80e3c4b6409ed0379bbc142b8ff34", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "config": { "title": "Caveman reusable evaluator", "description": "Versioned evaluator configuration. grader_type is validated against grader-registry.json by control-api.", "type": "object", "required": [ "schema_version", "grader_type", "options", "input_mapping" ], "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "grader_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "options": { "type": "object" }, "input_mapping": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } } } } }, "required": [ "name", "config" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-evaluators/{evaluatorId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/eval-evaluators/{evaluatorId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdEvalEvaluatorsEvaluatorId", "description": "DELETE /api/v1/projects/{projectId}/eval-evaluators/{evaluatorId} on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Archives a reusable evaluator used by shared workbenches. Agents may create and version evaluators; a human retires shared quality policy.", "x-caveman-operation": "evaluators.archive", "x-caveman-operation-contract": "989baa35dbdb83b668485499c8db8341e7c552a10dc77d1fbad5b57953549a89", "parameters": [ { "name": "revision", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] }, "get": { "summary": "GET /projects/{projectId}/eval-evaluators/{evaluatorId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalEvaluatorsEvaluatorId", "description": "GET /api/v1/projects/{projectId}/eval-evaluators/{evaluatorId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_evaluator action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evaluators.get", "x-caveman-operation-contract": "f602a3e76637dc20ca67031ccf92b4567854b43f9662dcc4dc691db21f6ba992", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "put": { "summary": "PUT /projects/{projectId}/eval-evaluators/{evaluatorId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdEvalEvaluatorsEvaluatorId", "description": "PUT /api/v1/projects/{projectId}/eval-evaluators/{evaluatorId} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the update_evaluator action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evaluators.update", "x-caveman-operation-contract": "2c7356fd797311f886f83a807dd9151f47502349095d63422d9abbde561bbf1e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "config": { "title": "Caveman reusable evaluator", "description": "Versioned evaluator configuration. grader_type is validated against grader-registry.json by control-api.", "type": "object", "required": [ "schema_version", "grader_type", "options", "input_mapping" ], "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "grader_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "options": { "type": "object" }, "input_mapping": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } } } } }, "required": [ "revision", "name", "config" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-evaluators/{evaluatorId}/qualifications": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-evaluators/{evaluatorId}/qualifications", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalEvaluatorsEvaluatorIdQualifications", "description": "GET /api/v1/projects/{projectId}/eval-evaluators/{evaluatorId}/qualifications on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_qualifications action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "qualifications.list", "x-caveman-operation-contract": "0863de6cd4b4b966a11c8f60a4df6b02f5469036be2d9442b5374ab60071a786", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/eval-evaluators/{evaluatorId}/qualify": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-evaluators/{evaluatorId}/qualify", "responses": { "200": { "description": "Canonical evaluation runs launched or their qualification refreshed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatorQualification" } } } }, "422": { "description": "Independent set must predate authoring and support exact evaluator input semantics." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalEvaluatorsEvaluatorIdQualify", "description": "POST /api/v1/projects/{projectId}/eval-evaluators/{evaluatorId}/qualify on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the calibrate_evaluator action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 }, "set_id": { "type": "string", "format": "uuid" } }, "required": [ "version", "set_id" ] } } } }, "x-caveman-operation": "evaluators.calibrate", "x-caveman-operation-contract": "40dbfaa6b89540d0f2354440943d35014edccae78f5c3846325d36d94c3cccb2", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-experiments": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-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" } }, "operationId": "getProjectsProjectIdEvalExperiments", "description": "GET /api/v1/projects/{projectId}/eval-experiments on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_experiments action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.list_experiments", "x-caveman-operation-contract": "975a803f4f742fbe2cf8a048353ae59f74884795878833afb148d2a84fa20203", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/eval-plan": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-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" } }, "operationId": "postProjectsProjectIdEvalPlan", "description": "POST /api/v1/projects/{projectId}/eval-plan on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the plan action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "evals.plan", "x-caveman-operation-contract": "12b46c670c70121371752f4c3d93174aab9f51ebc2f5c385043345d21566c066", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "workload_id": { "type": "string", "format": "uuid" }, "run": { "type": "object", "additionalProperties": false, "properties": { "source": { "enum": [ "eval_run", "experiment", "scenario_run", "factory_comparison" ] }, "run_id": { "type": "string", "format": "uuid" } }, "required": [ "source", "run_id" ] }, "metric": { "enum": [ "preference", "pass_rate" ] }, "margin": { "type": "number", "exclusiveMinimum": 0 }, "claim": { "enum": [ "cost_and_quality", "quality_only" ] }, "criteria": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "cases_available": { "type": "integer", "minimum": 0 }, "trials": { "type": "integer", "minimum": 0 }, "power": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } }, "required": [ "workload_id" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/eval-proposals": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-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" } }, "operationId": "getProjectsProjectIdEvalProposals", "description": "GET /api/v1/projects/{projectId}/eval-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_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.list_proposals", "x-caveman-operation-contract": "9ff4236b38c60d8f5b11f127ef6a21175822ead28c920dc7c709950950924df4", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/eval-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" } }, "operationId": "postProjectsProjectIdEvalProposals", "description": "POST /api/v1/projects/{projectId}/eval-proposals on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the propose action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.propose", "x-caveman-operation-contract": "dd0f70d09340fc711812c1714d0da9a714d3e20cd0bb7bd4f46c5fd615408789", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "criterion", "dataset", "monitor", "experiment", "prompt_improvement", "explanation" ] }, "action": { "enum": [ "create", "update", "generate", "run", "note" ] }, "target_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "rationale": { "type": "string", "maxLength": 4000 }, "ref": { "type": "string", "maxLength": 200 }, "request": { "type": "object" }, "test_on": { "type": "object" } }, "required": [ "kind", "title", "request" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-proposals/{proposalId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-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" } }, "operationId": "getProjectsProjectIdEvalProposalsProposalId", "description": "GET /api/v1/projects/{projectId}/eval-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_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.get_proposal", "x-caveman-operation-contract": "d8546689688565c6a9e44ea31969a8bf800d7356e06d2998d3eab9060e3aed95", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /projects/{projectId}/eval-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" } }, "operationId": "patchProjectsProjectIdEvalProposalsProposalId", "description": "PATCH /api/v1/projects/{projectId}/eval-proposals/{proposalId} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the edit_proposal action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.edit_proposal", "x-caveman-operation-contract": "052c56234722135afe8714061bd6d87a73b4c60509f0c8ff181073229f6d92b9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "rationale": { "type": "string", "maxLength": 4000 }, "request": { "type": "object" }, "test_on": { "type": "object" } }, "required": [ "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-proposals/{proposalId}/accept": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-proposals/{proposalId}/accept", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalProposalsProposalIdAccept", "description": "POST /api/v1/projects/{projectId}/eval-proposals/{proposalId}/accept on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Accepting runs the operation the proposal holds: it creates or changes an eval object and may start paid judging. A person decides.", "x-caveman-operation": "evals.accept_proposal", "x-caveman-operation-contract": "2a8bf68ebcf4c05e818218dcc32a9193f6924b1d0de145650cec3e2bba3d8aa7", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-proposals/{proposalId}/decline": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-proposals/{proposalId}/decline", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalProposalsProposalIdDecline", "description": "POST /api/v1/projects/{projectId}/eval-proposals/{proposalId}/decline on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Declining is the person's answer to a proposal an agent made.", "x-caveman-operation": "evals.decline_proposal", "x-caveman-operation-contract": "d4d8f7a9d248e28680fb469b0ee2d0d445eddb7aa8a539da3dc07850ca70e566", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-qualification-sets": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-qualification-sets", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalQualificationSets", "description": "GET /api/v1/projects/{projectId}/eval-qualification-sets on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the qualification_sets action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "qualifications.sets", "x-caveman-operation-contract": "49f4a8031bffd423cd1235c95ce1cd70cf82e05cc326c0958c188307405f65e0", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/eval-qualification-sets", "responses": { "201": { "description": "Immutable independent set registered. Labels and subject semantics are supplied by authorized native users, never the evaluator author." }, "422": { "description": "Independent sets or population metadata are incompatible." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalQualificationSets", "description": "POST /api/v1/projects/{projectId}/eval-qualification-sets on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Independent holdout labels must not be authored by the agent whose evaluator they qualify.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatorQualificationSetConfiguration" } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/eval-qualifications/{qualificationId}/activate": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "qualificationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-qualifications/{qualificationId}/activate", "responses": { "200": { "description": "Current qualified evaluator pinned to a canonical monitor in the independently configured population." }, "422": { "description": "Qualification or scoped activation authority is unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalQualificationsQualificationIdActivate", "description": "POST /api/v1/projects/{projectId}/eval-qualifications/{qualificationId}/activate on the Caveman Cloud control plane. Requires the autopilot:manage scope. Exposed to autonomous agents as the activate_qualification action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "qualifications.activate", "x-caveman-operation-contract": "f6fd147ac94fea8d857d727980a269f1eeb9b6de28be7c515e648f1b26fa9dad", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/eval-qualifications/{qualificationId}/cancel": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "qualificationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-qualifications/{qualificationId}/cancel", "responses": { "200": { "description": "Pending evaluation and conditional activation cancelled atomically; historical measurements retained.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatorQualification" } } } }, "409": { "description": "Monitor already created; pause through its native lifecycle." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalQualificationsQualificationIdCancel", "description": "POST /api/v1/projects/{projectId}/eval-qualifications/{qualificationId}/cancel on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the cancel_qualification action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "qualifications.cancel", "x-caveman-operation-contract": "37e1f7375efce93660a78b3578c0dbe2968b644ef39052d81425d3d419d52c26", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-qualifications/{qualificationId}/refresh": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "qualificationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-qualifications/{qualificationId}/refresh", "responses": { "200": { "description": "Qualification projection refreshed from actual canonical evaluation results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatorQualification" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalQualificationsQualificationIdRefresh", "description": "POST /api/v1/projects/{projectId}/eval-qualifications/{qualificationId}/refresh on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the refresh_qualification action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "qualifications.refresh", "x-caveman-operation-contract": "03b899eb0c7211b605083ea12d245b9ec8a4033a2f71e8eecf62cc15cbbbc4cf", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-scenarios": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-scenarios", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalScenarios", "description": "GET /api/v1/projects/{projectId}/eval-scenarios on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the list_scenarios action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "scenarios.list", "x-caveman-operation-contract": "dd125831f93cdc0aefbe66bad3a6e3059cc2c58178cc9cd77b1c13cf71eb7bd2", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] }, "post": { "summary": "POST /projects/{projectId}/eval-scenarios", "responses": { "201": { "description": "Canonical immutable dataset scenario version, unexecuted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTaskScenarioVersion" } } } }, "422": { "description": "Unsupported task definition." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalScenarios", "description": "POST /api/v1/projects/{projectId}/eval-scenarios on the Caveman Cloud control plane. Requires any one of the scopes eval:write, scenario:write. Exposed to autonomous agents as the create_scenario action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "adapter": { "enum": [ "python-module-task-v1", "node-module-task-v1" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "invariant": { "type": "string", "minLength": 1, "maxLength": 4000 }, "entrypoint": { "type": "string", "maxLength": 200, "pattern": "^([A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*:[A-Za-z_][A-Za-z0-9_]*|(\\.caveman/adapters/)?[A-Za-z0-9_][A-Za-z0-9_./-]*\\.(js|mjs|ts):[A-Za-z_$][A-Za-z0-9_$]*)$" }, "input": {}, "initial_state": { "type": "object" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "arguments": {}, "result": {}, "error": { "type": "string", "maxLength": 500 } }, "required": [ "name", "arguments", "result" ] }, "minItems": 0, "maxItems": 100 }, "read_only_tools": { "type": "array", "description": "Declared tool names whose calls change nothing. A trial may then make those calls in another order between two other calls, and skip one unless its recorded answer differs from that same call's latest earlier answer; every other fixture must be called in order. Omit when any tool has side effects you are unsure of.", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 100, "uniqueItems": true }, "assertions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "subject": { "enum": [ "output", "state" ] }, "pointer": { "type": "string", "maxLength": 1000 }, "operator": { "enum": [ "equals", "contains", "not_contains" ] }, "value": {} }, "allOf": [ { "if": { "properties": { "operator": { "enum": [ "contains", "not_contains" ] } } }, "then": { "properties": { "value": { "type": "string", "minLength": 1 } } } } ], "required": [ "subject", "pointer", "operator", "value" ] }, "minItems": 1, "maxItems": 100 }, "expected_failure": { "type": "object", "additionalProperties": false, "properties": { "exception_type": { "type": "string", "minLength": 1, "maxLength": 200 }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "function": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "exception_type", "path", "function" ] }, "historical": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "expected": { "enum": [ "passed", "failed" ] } }, "required": [ "commit_sha", "expected" ] }, "minItems": 0, "maxItems": 20 }, "provenance": { "type": "object", "additionalProperties": false, "properties": { "evidence_digests": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "fixture_basis": { "const": "synthetic" }, "fixture_rationale": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "evidence_digests", "fixture_basis", "fixture_rationale" ] } }, "required": [ "schema_version", "adapter", "name", "invariant", "entrypoint", "input", "initial_state", "tools", "assertions", "historical", "provenance" ] } } } }, "x-caveman-operation": "scenarios.create", "x-caveman-operation-contract": "94e8152c2393710705ea27e9f4e4dbeeaa46508c29cf6a98d16d25c516766f47", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write", "scenario:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write", "scenario:write" ] } }, "/projects/{projectId}/eval-scenarios/{datasetId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /projects/{projectId}/eval-scenarios/{datasetId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdEvalScenariosDatasetId", "description": "PUT /api/v1/projects/{projectId}/eval-scenarios/{datasetId} on the Caveman Cloud control plane. Requires any one of the scopes eval:write, scenario:write. Exposed to autonomous agents as the update_scenario action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "scenarios.update", "x-caveman-operation-contract": "680cf4f1417788dc220bedde74e5ca2e2f1f67d6c73f0d867fcd69997a00d9eb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "definition": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "adapter": { "enum": [ "python-module-task-v1", "node-module-task-v1" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "invariant": { "type": "string", "minLength": 1, "maxLength": 4000 }, "entrypoint": { "type": "string", "maxLength": 200, "pattern": "^([A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*:[A-Za-z_][A-Za-z0-9_]*|(\\.caveman/adapters/)?[A-Za-z0-9_][A-Za-z0-9_./-]*\\.(js|mjs|ts):[A-Za-z_$][A-Za-z0-9_$]*)$" }, "input": {}, "initial_state": { "type": "object" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "arguments": {}, "result": {}, "error": { "type": "string", "maxLength": 500 } }, "required": [ "name", "arguments", "result" ] }, "minItems": 0, "maxItems": 100 }, "read_only_tools": { "type": "array", "description": "Declared tool names whose calls change nothing. A trial may then make those calls in another order between two other calls, and skip one unless its recorded answer differs from that same call's latest earlier answer; every other fixture must be called in order. Omit when any tool has side effects you are unsure of.", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 100, "uniqueItems": true }, "assertions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "subject": { "enum": [ "output", "state" ] }, "pointer": { "type": "string", "maxLength": 1000 }, "operator": { "enum": [ "equals", "contains", "not_contains" ] }, "value": {} }, "allOf": [ { "if": { "properties": { "operator": { "enum": [ "contains", "not_contains" ] } } }, "then": { "properties": { "value": { "type": "string", "minLength": 1 } } } } ], "required": [ "subject", "pointer", "operator", "value" ] }, "minItems": 1, "maxItems": 100 }, "expected_failure": { "type": "object", "additionalProperties": false, "properties": { "exception_type": { "type": "string", "minLength": 1, "maxLength": 200 }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "function": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "exception_type", "path", "function" ] }, "historical": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "expected": { "enum": [ "passed", "failed" ] } }, "required": [ "commit_sha", "expected" ] }, "minItems": 0, "maxItems": 20 }, "provenance": { "type": "object", "additionalProperties": false, "properties": { "evidence_digests": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "fixture_basis": { "const": "synthetic" }, "fixture_rationale": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "evidence_digests", "fixture_basis", "fixture_rationale" ] } }, "required": [ "schema_version", "adapter", "name", "invariant", "entrypoint", "input", "initial_state", "tools", "assertions", "historical", "provenance" ] } }, "required": [ "revision", "definition" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write", "scenario:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write", "scenario:write" ] } }, "/projects/{projectId}/eval-scenarios/{datasetId}/versions/{version}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-scenarios/{datasetId}/versions/{version}", "responses": { "200": { "description": "Frozen scenario version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTaskScenarioVersion" } } } }, "404": { "description": "Scenario version unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalScenariosDatasetIdVersionsVersion", "description": "GET /api/v1/projects/{projectId}/eval-scenarios/{datasetId}/versions/{version} on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_scenario action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "scenarios.get", "x-caveman-operation-contract": "ccc9426d59b8e364bbbe07522d806f163674a3cdcdc9e0b2f24dba837ee2416e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/eval-scenarios/{datasetId}/versions/{version}/export.zip": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-scenarios/{datasetId}/versions/{version}/export.zip", "responses": { "200": { "description": "Frozen scenario, SHA256 lock and the task runner for its adapter (run_scenario.py for Python, run_scenario.mjs for Node). Does not assert VM isolation or successful execution.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Scenario version unavailable." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectEvalScenariosDatasetVersionsVersionExportZip", "description": "GET /api/v1/projects/{projectId}/eval-scenarios/{datasetId}/versions/{version}/export.zip on the Caveman Cloud control plane. Requires the payload:read scope. Not exposed to autonomous agents: Bulk scenario download is a native authenticated data export; JSON discovery and authored scenarios use scoped reads.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/eval-scenarios/{datasetId}/versions/{version}/runs/compare": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-scenarios/{datasetId}/versions/{version}/runs/compare", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectEvalScenariosDatasetVersionsVersionRunsCompare", "description": "GET /api/v1/projects/{projectId}/eval-scenarios/{datasetId}/versions/{version}/runs/compare on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the compare_scenarios action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "scenarios.compare", "x-caveman-operation-contract": "a88d1ae20956986b0d6777f6905721f829edb5fd4a7df2e16a28900ebd421498", "parameters": [ { "name": "baseline_run_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "candidate_run_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/eval-workbenches": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-workbenches", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalWorkbenches", "description": "GET /api/v1/projects/{projectId}/eval-workbenches on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_workbenches action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.list", "x-caveman-operation-contract": "8d7817bd99ad05f6f2567411b747e979b02d0d9b0b0acd023332436a1c7499b2", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/eval-workbenches", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalWorkbenches", "description": "POST /api/v1/projects/{projectId}/eval-workbenches on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the create_workbench action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.create", "x-caveman-operation-contract": "f3cb3c91e780dd78184572f95a2d830810f0da348cb4a5f33899bbdb44cfee57", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "document": { "title": "Caveman evaluation workbench", "description": "Versioned dataset-target-evaluator document used by UI, REST, CI and agent tools.", "type": "object", "required": [ "schema_version", "datasets", "targets", "evaluators" ], "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "datasets": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "dataset_id" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "dataset_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "document_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "dependentRequired": { "version": [ "document_sha256" ], "document_sha256": [ "version" ] } } }, "active_dataset_key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "targets": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "oneOf": [ { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "prompt" }, "config": { "type": "object", "required": [ "prompt_id", "prompt_version", "provider", "model" ], "additionalProperties": false, "properties": { "prompt_id": { "type": "string", "format": "uuid" }, "prompt_version": { "type": "integer", "minimum": 1 }, "provider": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 1048576 }, "response_format": { "enum": [ "text", "json" ] } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "agent" }, "config": { "type": "object", "required": [ "agent_id", "endpoint", "method", "authentication" ], "additionalProperties": false, "properties": { "agent_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "endpoint": { "type": "string", "format": "uri", "pattern": "^https://[^?#]+$" }, "method": { "const": "POST" }, "authentication": { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "const": "none" } } }, "output_path": { "type": "string", "pattern": "^/" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "workflow" }, "config": { "type": "object", "required": [ "workflow_id", "endpoint", "method", "authentication" ], "additionalProperties": false, "properties": { "workflow_id": { "type": "string", "format": "uuid" }, "endpoint": { "type": "string", "format": "uri", "pattern": "^https://[^?#]+$" }, "method": { "const": "POST" }, "authentication": { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "const": "none" } } }, "output_path": { "type": "string", "pattern": "^/" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "recorded" }, "config": { "type": "object", "required": [ "output_column" ], "additionalProperties": false, "properties": { "output_column": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "external" }, "config": { "description": "The caller ran this step: a run of it carries each output (evals.run outputs). At most one per document.", "type": "object", "additionalProperties": false } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "http" }, "config": { "type": "object", "required": [ "endpoint", "method", "authentication" ], "additionalProperties": false, "properties": { "endpoint": { "type": "string", "format": "uri", "pattern": "^https://[^?#]+$" }, "method": { "const": "POST" }, "authentication": { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "const": "none" } } }, "output_path": { "type": "string", "pattern": "^/" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "model" }, "config": { "type": "object", "required": [ "user_template", "provider", "model" ], "additionalProperties": false, "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 1048576 }, "response_format": { "enum": [ "text", "json" ] }, "user_template": { "type": "string", "minLength": 1, "maxLength": 262144 }, "system_template": { "type": "string", "maxLength": 262144 } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "evaluator" }, "config": { "type": "object", "additionalProperties": false, "required": [ "evaluator_id", "evaluator_version", "config_sha256" ], "properties": { "evaluator_id": { "type": "string", "format": "uuid" }, "evaluator_version": { "type": "integer", "minimum": 1 }, "config_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "scenario" }, "config": { "type": "object", "additionalProperties": false, "required": [ "dataset_id", "version", "scenario_sha256", "repository_commit_sha", "recipe_id", "recipe_sha256" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "scenario_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "repository_commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "recipe_id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "recipe_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } ], "unevaluatedProperties": false } ] } }, "evaluators": { "type": "array", "maxItems": 24, "items": { "oneOf": [ { "type": "object", "required": [ "key", "name", "source", "evaluator_id", "evaluator_version", "config_sha256" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "source": { "const": "saved" }, "target_keys": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "evaluator_id": { "type": "string", "format": "uuid" }, "evaluator_version": { "type": "integer", "minimum": 1 }, "config_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "input_mapping": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } } } } }, { "type": "object", "required": [ "key", "name", "source", "grader_type", "options", "input_mapping" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "source": { "const": "inline" }, "target_keys": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "grader_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "options": { "type": "object" }, "input_mapping": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } } } } }, { "type": "object", "required": [ "key", "name", "source", "criterion_id", "criterion_version" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "source": { "const": "criterion" }, "target_keys": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "criterion_id": { "type": "string", "format": "uuid" }, "criterion_version": { "type": "integer", "minimum": 1 }, "input_mapping": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } } } } } ] } }, "settings": { "type": "object", "required": [ "concurrency", "row_height" ], "additionalProperties": false, "properties": { "concurrency": { "type": "integer", "minimum": 1, "maximum": 24 }, "row_height": { "enum": [ "compact", "comfortable" ] }, "trials": { "type": "integer", "minimum": 1, "maximum": 10 }, "judge_order": { "enum": [ "randomized", "fixed" ] }, "judge_seed": { "type": "integer", "minimum": 0 } } }, "comparison": { "type": "object", "additionalProperties": false, "properties": { "primary_evaluator_key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "confidence_level": { "enum": [ 0.9, 0.95, 0.99 ] }, "minimum_samples": { "type": "integer", "minimum": 2, "maximum": 10000 }, "baseline_target_key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } } } }, "upsert": { "type": "boolean", "description": "Update the live resource of this name in the project instead of refusing the name. A dataset whose rows are unchanged is left as it is, so its next run reuses its version." } }, "required": [ "name", "document" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/eval-workbenches/{workbenchId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdEvalWorkbenchesWorkbenchId", "description": "DELETE /api/v1/projects/{projectId}/eval-workbenches/{workbenchId} on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Archives a shared workbench and removes it from active experiment authoring. A human owns retirement of shared evaluation work.", "x-caveman-operation": "evals.archive", "x-caveman-operation-contract": "ffe3c4130ef404e7ebb783216eb5786fd28d63e62293d6c1981b51bf2d197c0e", "parameters": [ { "name": "revision", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] }, "get": { "summary": "GET /projects/{projectId}/eval-workbenches/{workbenchId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalWorkbenchesWorkbenchId", "description": "GET /api/v1/projects/{projectId}/eval-workbenches/{workbenchId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_workbench action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.get", "x-caveman-operation-contract": "bc9c7fb3325c73b3e342f2f600cfedc51f7b784b0775ad7c1a7e9772b9f6642e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "put": { "summary": "PUT /projects/{projectId}/eval-workbenches/{workbenchId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdEvalWorkbenchesWorkbenchId", "description": "PUT /api/v1/projects/{projectId}/eval-workbenches/{workbenchId} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the update_workbench action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.update", "x-caveman-operation-contract": "92d55e5e51d09611ce2d974c28c556dd436f87484ba7301a2913e5a819b712c1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "document": { "title": "Caveman evaluation workbench", "description": "Versioned dataset-target-evaluator document used by UI, REST, CI and agent tools.", "type": "object", "required": [ "schema_version", "datasets", "targets", "evaluators" ], "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "datasets": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "dataset_id" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "dataset_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "document_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "dependentRequired": { "version": [ "document_sha256" ], "document_sha256": [ "version" ] } } }, "active_dataset_key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "targets": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "oneOf": [ { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "prompt" }, "config": { "type": "object", "required": [ "prompt_id", "prompt_version", "provider", "model" ], "additionalProperties": false, "properties": { "prompt_id": { "type": "string", "format": "uuid" }, "prompt_version": { "type": "integer", "minimum": 1 }, "provider": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 1048576 }, "response_format": { "enum": [ "text", "json" ] } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "agent" }, "config": { "type": "object", "required": [ "agent_id", "endpoint", "method", "authentication" ], "additionalProperties": false, "properties": { "agent_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "endpoint": { "type": "string", "format": "uri", "pattern": "^https://[^?#]+$" }, "method": { "const": "POST" }, "authentication": { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "const": "none" } } }, "output_path": { "type": "string", "pattern": "^/" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "workflow" }, "config": { "type": "object", "required": [ "workflow_id", "endpoint", "method", "authentication" ], "additionalProperties": false, "properties": { "workflow_id": { "type": "string", "format": "uuid" }, "endpoint": { "type": "string", "format": "uri", "pattern": "^https://[^?#]+$" }, "method": { "const": "POST" }, "authentication": { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "const": "none" } } }, "output_path": { "type": "string", "pattern": "^/" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "recorded" }, "config": { "type": "object", "required": [ "output_column" ], "additionalProperties": false, "properties": { "output_column": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "external" }, "config": { "description": "The caller ran this step: a run of it carries each output (evals.run outputs). At most one per document.", "type": "object", "additionalProperties": false } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "http" }, "config": { "type": "object", "required": [ "endpoint", "method", "authentication" ], "additionalProperties": false, "properties": { "endpoint": { "type": "string", "format": "uri", "pattern": "^https://[^?#]+$" }, "method": { "const": "POST" }, "authentication": { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "const": "none" } } }, "output_path": { "type": "string", "pattern": "^/" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "model" }, "config": { "type": "object", "required": [ "user_template", "provider", "model" ], "additionalProperties": false, "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 1048576 }, "response_format": { "enum": [ "text", "json" ] }, "user_template": { "type": "string", "minLength": 1, "maxLength": 262144 }, "system_template": { "type": "string", "maxLength": 262144 } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "evaluator" }, "config": { "type": "object", "additionalProperties": false, "required": [ "evaluator_id", "evaluator_version", "config_sha256" ], "properties": { "evaluator_id": { "type": "string", "format": "uuid" }, "evaluator_version": { "type": "integer", "minimum": 1 }, "config_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "type": "object", "required": [ "key", "name", "kind", "input_mapping", "config" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": [ "prompt", "agent", "workflow", "recorded", "external", "http", "model", "evaluator", "scenario" ] }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } }, "config": { "type": "object" } } }, { "properties": { "kind": { "const": "scenario" }, "config": { "type": "object", "additionalProperties": false, "required": [ "dataset_id", "version", "scenario_sha256", "repository_commit_sha", "recipe_id", "recipe_sha256" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "scenario_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "repository_commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "recipe_id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "recipe_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } ], "unevaluatedProperties": false } ] } }, "evaluators": { "type": "array", "maxItems": 24, "items": { "oneOf": [ { "type": "object", "required": [ "key", "name", "source", "evaluator_id", "evaluator_version", "config_sha256" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "source": { "const": "saved" }, "target_keys": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "evaluator_id": { "type": "string", "format": "uuid" }, "evaluator_version": { "type": "integer", "minimum": 1 }, "config_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "input_mapping": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } } } } }, { "type": "object", "required": [ "key", "name", "source", "grader_type", "options", "input_mapping" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "source": { "const": "inline" }, "target_keys": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "grader_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "options": { "type": "object" }, "input_mapping": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } } } } }, { "type": "object", "required": [ "key", "name", "source", "criterion_id", "criterion_version" ], "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "source": { "const": "criterion" }, "target_keys": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } }, "criterion_id": { "type": "string", "format": "uuid" }, "criterion_version": { "type": "integer", "minimum": 1 }, "input_mapping": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } }, "dataset_input_mappings": { "type": "object", "additionalProperties": { "type": "object", "required": [ "candidate" ], "additionalProperties": false, "properties": { "candidate": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "reference": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } }, "baseline": { "type": "object", "required": [ "source", "key" ], "additionalProperties": false, "properties": { "source": { "enum": [ "dataset", "target" ] }, "key": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, { "const": "$target" } ] } } } } } } } } ] } }, "settings": { "type": "object", "required": [ "concurrency", "row_height" ], "additionalProperties": false, "properties": { "concurrency": { "type": "integer", "minimum": 1, "maximum": 24 }, "row_height": { "enum": [ "compact", "comfortable" ] }, "trials": { "type": "integer", "minimum": 1, "maximum": 10 }, "judge_order": { "enum": [ "randomized", "fixed" ] }, "judge_seed": { "type": "integer", "minimum": 0 } } }, "comparison": { "type": "object", "additionalProperties": false, "properties": { "primary_evaluator_key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" }, "confidence_level": { "enum": [ 0.9, 0.95, 0.99 ] }, "minimum_samples": { "type": "integer", "minimum": 2, "maximum": 10000 }, "baseline_target_key": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$" } } } } } }, "required": [ "revision", "name", "document" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/restore": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-workbenches/{workbenchId}/restore", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalWorkbenchesWorkbenchIdRestore", "description": "POST /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/restore on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the restore_workbench_version action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.restore", "x-caveman-operation-contract": "056f330c56169444d85010b059b352eb664abb1e64385328a7214fd158580521", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "revision", "version" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/runs": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-workbenches/{workbenchId}/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" } }, "operationId": "getProjectsProjectIdEvalWorkbenchesWorkbenchIdRuns", "description": "GET /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_workbench_runs action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.runs", "x-caveman-operation-contract": "308cc9713c4b24c4b5b6335302ea590de0551a9ab4b6bab1a603aaf2ed80c159", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/eval-workbenches/{workbenchId}/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" } }, "operationId": "postProjectsProjectIdEvalWorkbenchesWorkbenchIdRuns", "description": "POST /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the run_workbench action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.run", "x-caveman-operation-contract": "bd454d9b3bf665576272d817904ef13b7f011a3dd7b4f85f14f02fd96ad41463", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "all", "target", "row", "cell", "evaluator" ] }, "target_key": { "type": "string" }, "row_key": { "type": "string" }, "evaluator_key": { "type": "string" }, "source_run_id": { "type": "string", "format": "uuid" }, "trials": { "type": "integer", "minimum": 1, "maximum": 10 }, "split": { "type": "string" }, "tags": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "budget_usd": { "type": "number", "minimum": 0, "maximum": 1000, "description": "The most the run may spend, at list prices. Required when trials is over 1, and for any run an agent connection or a project key starts." }, "mode": { "enum": [ "full", "partial" ], "description": "partial: the run holds only some of the cases (a quick look at a sample). A partial run is never a baseline and never compared. Left out, the run is full." }, "commit": { "type": "object", "additionalProperties": false, "properties": { "sha": { "type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$" }, "ref": { "type": "string", "maxLength": 255, "pattern": "^[^\\s]*$" }, "base_sha": { "type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$" }, "base_ref": { "type": "string", "maxLength": 255, "pattern": "^[^\\s]*$" }, "pr_number": { "type": "integer", "minimum": 0, "maximum": 1000000000 } }, "description": "The change the run was made for, as the caller reports it (a CI job's commit, ref, base and pull request). Returned on the run's scope; nothing grades or compares on it." } }, "required": [ "kind" ] }, "concurrency": { "type": "integer", "minimum": 1, "maximum": 24 }, "outputs": { "type": "array", "minItems": 1, "maxItems": 100000, "items": { "type": "object", "additionalProperties": false, "properties": { "row_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$" }, "trial": { "type": "integer", "minimum": 1, "maximum": 10 }, "output": {}, "error": { "type": "string", "maxLength": 2000 }, "trace_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "latency_ms": { "type": "number", "minimum": 0 }, "cost_usd": { "type": "number", "minimum": 0 }, "attempts": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "row_key" ] }, "description": "Outputs the caller produced, one per trial of a row, for an experiment with an external target. The run holds the rows they name; Caveman grades them and never reads them as its own execution." } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalWorkbenchesWorkbenchIdRunsRunId", "description": "GET /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId} on the Caveman Cloud control plane. Requires any one of the scopes payload:read, trace:read_metadata. Exposed to autonomous agents as the get_workbench_run action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.result", "x-caveman-operation-contract": "9d4ccd8b91b38c6960f3cc4dae2e9744dbd21061cf26622594db9044747767fe", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read", "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read", "trace:read_metadata" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/annotations": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/annotations", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectEvalWorkbenchesWorkbenchRunsRunAnnotations", "description": "GET /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/annotations on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the list_run_annotations action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.list_run_annotations", "x-caveman-operation-contract": "277055a8884df9f65f2f07a603ac7f6468ac422477eccefa9b4651fc2467c186", "parameters": [ { "name": "cell_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] }, "post": { "summary": "POST /projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/annotations", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectEvalWorkbenchesWorkbenchRunsRunAnnotations", "description": "POST /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/annotations on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Creates human review labels and comments. Agents can read review state but cannot impersonate a human reviewer.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/cancel": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/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" } }, "operationId": "postProjectsProjectIdEvalWorkbenchesWorkbenchIdRunsRunIdCancel", "description": "POST /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/cancel on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the cancel_workbench_run action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.cancel", "x-caveman-operation-contract": "2b11e9cac452df107ec9279ab1252fcb9d146a47dfd811864afe6e88abe95897", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/export.csv": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/export.csv", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalWorkbenchesWorkbenchIdRunsRunIdExportCsv", "description": "GET /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/export.csv on the Caveman Cloud control plane. Requires the payload:read scope. Not exposed to autonomous agents: Exports authored inputs and model outputs as a tenant-data download. Bulk data egress requires a human actor.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/promote": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/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" } }, "operationId": "postProjectsProjectIdEvalWorkbenchesWorkbenchIdRunsRunIdPromote", "description": "POST /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs/{runId}/promote on the Caveman Cloud control plane. Requires the experiment:approve_s3 scope. Not exposed to autonomous agents: Promotes passing workbench evidence into a strict rollout-authority suite. Human approval is required.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/runs/compare": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/eval-workbenches/{workbenchId}/runs/compare", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdEvalWorkbenchesWorkbenchIdRunsCompare", "description": "GET /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs/compare on the Caveman Cloud control plane. Requires any one of the scopes payload:read, trace:read_metadata. Exposed to autonomous agents as the compare_runs action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.compare", "x-caveman-operation-contract": "ee85ea9d6d3543fe69fc1df575a60ab238523e34fd67a1d538e3e500dc0e3d7b", "parameters": [ { "name": "baseline_run_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "candidate_run_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "policy", "in": "query", "required": false, "schema": { "enum": [ "kernel", "strict" ] } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read", "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read", "trace:read_metadata" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/runs/estimate": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-workbenches/{workbenchId}/runs/estimate", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalWorkbenchesWorkbenchIdRunsEstimate", "description": "POST /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/runs/estimate on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the estimate_run action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "x-caveman-operation": "evals.estimate_run", "x-caveman-operation-contract": "073923ba78773d8829a3f0be13c7f83e65584ce3059d9bb4c5b1845423a82a48", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "all", "target", "row", "cell", "evaluator" ] }, "target_key": { "type": "string" }, "row_key": { "type": "string" }, "evaluator_key": { "type": "string" }, "source_run_id": { "type": "string", "format": "uuid" }, "trials": { "type": "integer", "minimum": 1, "maximum": 10 }, "split": { "type": "string" }, "tags": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "budget_usd": { "type": "number", "minimum": 0, "maximum": 1000, "description": "The most the run may spend, at list prices. Required when trials is over 1, and for any run an agent connection or a project key starts." }, "mode": { "enum": [ "full", "partial" ], "description": "partial: the run holds only some of the cases (a quick look at a sample). A partial run is never a baseline and never compared. Left out, the run is full." }, "commit": { "type": "object", "additionalProperties": false, "properties": { "sha": { "type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$" }, "ref": { "type": "string", "maxLength": 255, "pattern": "^[^\\s]*$" }, "base_sha": { "type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$" }, "base_ref": { "type": "string", "maxLength": 255, "pattern": "^[^\\s]*$" }, "pr_number": { "type": "integer", "minimum": 0, "maximum": 1000000000 } }, "description": "The change the run was made for, as the caller reports it (a CI job's commit, ref, base and pull request). Returned on the run's scope; nothing grades or compares on it." } }, "required": [ "kind" ] } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/unarchive": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-workbenches/{workbenchId}/unarchive", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdEvalWorkbenchesWorkbenchIdUnarchive", "description": "POST /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/unarchive on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Brings an archived experiment back into authoring flows. A human retires and restores shared evidence assets.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/eval-workbenches/{workbenchId}/versions": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workbenchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/eval-workbenches/{workbenchId}/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" } }, "operationId": "postProjectsProjectIdEvalWorkbenchesWorkbenchIdVersions", "description": "POST /api/v1/projects/{projectId}/eval-workbenches/{workbenchId}/versions on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the snapshot_workbench action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.snapshot", "x-caveman-operation-contract": "6df794637edd3cba08950b8cde80037de13dc2eadde07a80d6a3d8fb575b1f3f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "const": "manual" } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/factory-models": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/factory-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" } }, "operationId": "getProjectsProjectIdFactoryModels", "description": "GET /api/v1/projects/{projectId}/factory-models on the Caveman Cloud control plane. Requires the settings:read scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] }, "put": { "summary": "PUT /projects/{projectId}/factory-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" } }, "operationId": "putProjectsProjectIdFactoryModels", "description": "PUT /api/v1/projects/{projectId}/factory-models on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Native user authority over factory case admission, bounded policy, binding approval and cancellation. An agent session must never read a case, resolve a setup blocker, approve an execution binding, admit paid improvement work or cancel a fence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/github/admin-proof-init": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/github/admin-proof-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" } }, "operationId": "postProjectsProjectIdGithubAdminProofInit", "description": "POST /api/v1/projects/{projectId}/github/admin-proof-init on the Caveman Cloud control plane. Requires the repo:connect scope. Not exposed to autonomous agents: Starts a GitHub user authorization that proves a human administers the repository. An agent asking for it would be asking a person to grant authority on its behalf.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "owner", "name" ], "properties": { "owner": { "type": "string" }, "name": { "type": "string" }, "return_to": { "type": "string", "maxLength": 512, "description": "Console path the browser returns to when GitHub sends it back: relative, under /onboarding/ or /cave-agent, no fragment. Omitted keeps /cave-agent." } } } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] } }, "/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" } }, "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.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "return_to": { "type": "string", "maxLength": 512, "description": "Console path the browser returns to when GitHub sends it back: relative, under /onboarding/ or /cave-agent, no fragment. Omitted keeps /cave-agent." } } } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] } }, "/projects/{projectId}/github/repositories": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/github/repositories", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdGithubRepositories", "description": "GET /api/v1/projects/{projectId}/github/repositories on the Caveman Cloud control plane. Requires the repo:connect scope. Not exposed to autonomous agents: Lists repositories for the human repository connection ceremony. Choosing the repository is the person's call.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] } }, "/projects/{projectId}/gitlab": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/gitlab", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdGitlab", "description": "DELETE /api/v1/projects/{projectId}/gitlab on the Caveman Cloud control plane. Requires the repo:connect scope. Not exposed to autonomous agents: Revokes the repository connection and its dedicated SCM credentials. Source access changes remain a human administrator decision.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] }, "get": { "summary": "GET /projects/{projectId}/gitlab", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdGitlab", "description": "GET /api/v1/projects/{projectId}/gitlab on the Caveman Cloud control plane. Requires the repo:read scope. Not exposed to autonomous agents: Shows service-credential assurance for the human repository connection ceremony.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:read" ] }, "post": { "summary": "POST /projects/{projectId}/gitlab", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdGitlab", "description": "POST /api/v1/projects/{projectId}/gitlab on the Caveman Cloud control plane. Requires the repo:connect scope. Not exposed to autonomous agents: Accepts and verifies dedicated SCM secrets supplied by an organization administrator. Source credentials are never agent tool arguments.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] } }, "/projects/{projectId}/guardrails": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/guardrails", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdGuardrails", "description": "GET /api/v1/projects/{projectId}/guardrails on the Caveman Cloud control plane. Requires any one of the scopes settings:read, policy:draft. Exposed to autonomous agents as the guardrails action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "x-caveman-operation": "policy.guardrails", "x-caveman-operation-contract": "f167e6092af66a79476ddda183555e89b198a75c5be52c96ab61ee21b79db779", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read", "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read", "policy:draft" ] }, "put": { "summary": "PUT /projects/{projectId}/guardrails", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdGuardrails", "description": "PUT /api/v1/projects/{projectId}/guardrails on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: A guardrail is the control that constrains this agent's own traffic; an agent able to edit one is able to remove it. Human-only regardless of agent competence.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/guardrails/hits": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/guardrails/hits", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdGuardrailsHits", "description": "GET /api/v1/projects/{projectId}/guardrails/hits on the Caveman Cloud control plane. Requires any one of the scopes settings:read, policy:draft. Exposed to autonomous agents as the guardrail_hits action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "x-caveman-operation": "policy.guardrail_hits", "x-caveman-operation-contract": "86330cf5248f384103f660cb2edfbd9288e81a039c7e773f493dd01cc64c4ddd", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read", "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read", "policy:draft" ] } }, "/projects/{projectId}/guardrails/test": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/guardrails/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" } }, "operationId": "postProjectsProjectIdGuardrailsTest", "description": "POST /api/v1/projects/{projectId}/guardrails/test on the Caveman Cloud control plane. Requires the policy:draft scope. Exposed to autonomous agents as the test_guardrails action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "x-caveman-operation": "policy.test_guardrails", "x-caveman-operation-contract": "c0e22e191d3a194c70939912a5e220a89d736f0709e3df0d00de0a05f65ffa5e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string" }, "direction": { "enum": [ "request", "response" ] } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/judges": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/judges", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdJudges", "description": "GET /api/v1/projects/{projectId}/judges on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the list_judges action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "judges.list", "x-caveman-operation-contract": "461627b68d1f420f37c3c9621bbd4553a5434437c95e8ac75066f69e0aeb41a0", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/projects/{projectId}/judges/{judgeId}/calibrations": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "judgeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/judges/{judgeId}/calibrations", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdJudgesJudgeIdCalibrations", "description": "GET /api/v1/projects/{projectId}/judges/{judgeId}/calibrations on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the judge_calibration action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "judges.calibration", "x-caveman-operation-contract": "b3195d4064805deb064289d84f254a61fc884f288c2c8e3dde6cfc8956c04ed1", "parameters": [ { "name": "criterion_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] } }, "/projects/{projectId}/judges/{judgeId}/test": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "judgeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/judges/{judgeId}/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" } }, "operationId": "postProjectsProjectIdJudgesJudgeIdTest", "description": "POST /api/v1/projects/{projectId}/judges/{judgeId}/test on the Caveman Cloud control plane. Requires the provider:manage scope. Not exposed to autonomous agents: Calls a judge with the project's stored credential. Agents never use or verify the secrets that pay for judging.", "x-caveman-operation": "judges.test", "x-caveman-operation-contract": "3234f249a7116fd49eb327f72feaccb07dcfc615df4abde3c6a3e692624fe9df", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/projects/{projectId}/judgments": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/judgments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdJudgments", "description": "GET /api/v1/projects/{projectId}/judgments on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_judgments action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "judgments.list", "x-caveman-operation-contract": "34d5feb568e08656abfefd61afe9edd73ceb5d0a95f2be0c5b90acb53e6d3238", "parameters": [ { "name": "unit_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "task_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "trace_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "monitor_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "criterion_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workload_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "verdict", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "latest", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/judgments/{judgmentId}/explanation": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "judgmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/judgments/{judgmentId}/explanation", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdJudgmentsJudgmentIdExplanation", "description": "POST /api/v1/projects/{projectId}/judgments/{judgmentId}/explanation on the Caveman Cloud control plane. Requires the payload:read scope. Not exposed to autonomous agents: Spends a cross-family LLM call on captured content when a person opens a failed judgment (SPEC §4.3). Agents read failing steps and evidence refs instead.", "x-caveman-operation": "judgments.explain", "x-caveman-operation-contract": "5ff6325f99dd53693c3dd48d771feb5eab7a99047ff558a37cc30c82f069ec73", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "keys.create", "x-caveman-operation-contract": "2ba8a98578316a600173ae9a249bfd9d6fe778904f6552c57124ebc078923d8e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "scopes": { "type": "array", "items": { "type": "string" } }, "member_user_id": { "type": "string" }, "default_workflow": { "type": "string" }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "rpm_limit": { "type": "integer" }, "tpm_limit": { "type": "integer" }, "max_parallel": { "type": "integer" }, "budget_usd": { "type": "number" }, "budget_soft_usd": { "type": "number" }, "budget_period": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "allowed_ips": { "type": "array", "items": { "type": "string" } }, "guardrails": { "type": [ "array", "null" ], "items": { "type": "string" } }, "expires_in": { "type": "string" }, "expires_at": { "type": "string" } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] } }, "/projects/{projectId}/keys/{keyId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/keys/{keyId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdKeysKeyId", "description": "GET /api/v1/projects/{projectId}/keys/{keyId} 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] }, "patch": { "summary": "PATCH /projects/{projectId}/keys/{keyId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdKeysKeyId", "description": "PATCH /api/v1/projects/{projectId}/keys/{keyId} 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] } }, "/projects/{projectId}/keys/{keyId}/block": { "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}/block", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdKeysKeyIdBlock", "description": "POST /api/v1/projects/{projectId}/keys/{keyId}/block 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] } }, "/projects/{projectId}/keys/{keyId}/unblock": { "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}/unblock", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdKeysKeyIdUnblock", "description": "POST /api/v1/projects/{projectId}/keys/{keyId}/unblock 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "key:manage" ] } }, "/projects/{projectId}/members": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/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" } }, "operationId": "getProjectsProjectIdMembers", "description": "GET /api/v1/projects/{projectId}/members on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Project membership is organization identity administration reserved for human operators.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] }, "post": { "summary": "POST /projects/{projectId}/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" } }, "operationId": "postProjectsProjectIdMembers", "description": "POST /api/v1/projects/{projectId}/members on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Creates or changes project membership, an organization identity administration action reserved for human operators.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/projects/{projectId}/members/{userId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/members/{userId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdMembersUserId", "description": "DELETE /api/v1/projects/{projectId}/members/{userId} on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Removes project membership, an organization identity administration action reserved for human operators.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/projects/{projectId}/metric-alerts": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/metric-alerts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdMetricAlerts", "description": "GET /api/v1/projects/{projectId}/metric-alerts on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list action of the caveman_alerts tool (read access). Metric alerts on the project: the watched big-number query, threshold, window, optional webhook, dashboard (a saved id or a builtin:* id) and last evaluated state and error.", "x-caveman-operation": "alerts.list", "x-caveman-operation-contract": "9ada057b7a596e6938006a1f47f5321c502c66391aba764dec71396c7c4ade70", "parameters": [ { "name": "dashboard_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/metric-alerts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdMetricAlerts", "description": "POST /api/v1/projects/{projectId}/metric-alerts on the Caveman Cloud control plane. Requires the dashboard:write scope. Exposed to autonomous agents as the create action of the caveman_alerts_write tool (write access). Create, change, pause and delete metric alerts. A firing or resolved alert files an Inbox item and emails the organization's owners and admins, at most once per notify interval; it can also post to a webhook an admin already configured.", "x-caveman-operation": "alerts.create", "x-caveman-operation-contract": "bdb1010a904c33826bb9b1d65651ca071d934195518f05e848dae9eeed708ae0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "dashboard_id": { "type": [ "string", "null" ], "maxLength": 64 }, "chart_id": { "type": [ "string", "null" ] }, "query": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "enum": [ "timeseries", "toplist", "bignumber" ] }, "source": { "enum": [ "requests", "spans", "tools", "evals" ] }, "preset": { "type": [ "string", "null" ] }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "field": { "type": "string" }, "agg": { "enum": [ "count", "sum", "avg", "min", "max", "count_distinct", "percentile" ] }, "p": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "expr": { "type": "string", "maxLength": 2000 } } }, "minItems": 1, "maxItems": 6 }, "filters": { "type": "object", "additionalProperties": false, "properties": { "row": { "type": "string", "maxLength": 2000 }, "trace": { "type": "string", "maxLength": 2000 } } }, "group_by": { "type": "string" }, "options": { "type": "object", "additionalProperties": false, "properties": { "unit": { "enum": [ "duration", "cost", "count", "percent", "bytes" ] }, "viz": { "enum": [ "line", "bar" ] }, "stacked": { "type": "boolean" }, "interval": { "enum": [ "auto", "hour", "day", "week" ] }, "sort": { "enum": [ "value_desc", "value_asc", "name_asc", "name_desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "layout": { "type": "object", "additionalProperties": false, "properties": { "w": { "enum": [ 3, 4, 6, 8, 12 ] }, "h": { "enum": [ 1, 2, 3 ] } }, "required": [ "w", "h" ] }, "section_id": { "type": [ "string", "null" ] } }, "required": [ "title", "type", "source", "measures" ] }, "comparator": { "enum": [ ">", ">=", "<", "<=" ] }, "threshold": { "type": "number" }, "window_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 }, "notify_interval_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 }, "no_data": { "enum": [ "keep", "resolve", "trigger" ] }, "webhook_id": { "type": [ "string", "null" ], "format": "uuid" }, "paused": { "type": "boolean" } }, "required": [ "name", "query", "comparator", "threshold", "window_minutes", "notify_interval_minutes" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "dashboard:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "dashboard:write" ] } }, "/projects/{projectId}/metric-alerts/{alertId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/metric-alerts/{alertId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdMetricAlertsAlertId", "description": "DELETE /api/v1/projects/{projectId}/metric-alerts/{alertId} on the Caveman Cloud control plane. Requires the dashboard:write scope. Exposed to autonomous agents as the delete action of the caveman_alerts_write tool (write access). Create, change, pause and delete metric alerts. A firing or resolved alert files an Inbox item and emails the organization's owners and admins, at most once per notify interval; it can also post to a webhook an admin already configured.", "x-caveman-operation": "alerts.delete", "x-caveman-operation-contract": "de0fa88b380619cf8f18134fec4f716c8db3b1898798f8acb24e7f4e95e9c9c2", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "dashboard:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "dashboard:write" ] }, "patch": { "summary": "PATCH /projects/{projectId}/metric-alerts/{alertId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdMetricAlertsAlertId", "description": "PATCH /api/v1/projects/{projectId}/metric-alerts/{alertId} on the Caveman Cloud control plane. Requires the dashboard:write scope. Exposed to autonomous agents as the update action of the caveman_alerts_write tool (write access). Create, change, pause and delete metric alerts. A firing or resolved alert files an Inbox item and emails the organization's owners and admins, at most once per notify interval; it can also post to a webhook an admin already configured.", "x-caveman-operation": "alerts.update", "x-caveman-operation-contract": "30a5e275a9e4d0f8be5718d8c6afe2adec2caab7aef971b6f6a11b8226994599", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "dashboard_id": { "type": [ "string", "null" ], "maxLength": 64 }, "chart_id": { "type": [ "string", "null" ] }, "query": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "enum": [ "timeseries", "toplist", "bignumber" ] }, "source": { "enum": [ "requests", "spans", "tools", "evals" ] }, "preset": { "type": [ "string", "null" ] }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "field": { "type": "string" }, "agg": { "enum": [ "count", "sum", "avg", "min", "max", "count_distinct", "percentile" ] }, "p": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "expr": { "type": "string", "maxLength": 2000 } } }, "minItems": 1, "maxItems": 6 }, "filters": { "type": "object", "additionalProperties": false, "properties": { "row": { "type": "string", "maxLength": 2000 }, "trace": { "type": "string", "maxLength": 2000 } } }, "group_by": { "type": "string" }, "options": { "type": "object", "additionalProperties": false, "properties": { "unit": { "enum": [ "duration", "cost", "count", "percent", "bytes" ] }, "viz": { "enum": [ "line", "bar" ] }, "stacked": { "type": "boolean" }, "interval": { "enum": [ "auto", "hour", "day", "week" ] }, "sort": { "enum": [ "value_desc", "value_asc", "name_asc", "name_desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "layout": { "type": "object", "additionalProperties": false, "properties": { "w": { "enum": [ 3, 4, 6, 8, 12 ] }, "h": { "enum": [ 1, 2, 3 ] } }, "required": [ "w", "h" ] }, "section_id": { "type": [ "string", "null" ] } }, "required": [ "title", "type", "source", "measures" ] }, "comparator": { "enum": [ ">", ">=", "<", "<=" ] }, "threshold": { "type": "number" }, "window_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 }, "notify_interval_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 }, "no_data": { "enum": [ "keep", "resolve", "trigger" ] }, "webhook_id": { "type": [ "string", "null" ], "format": "uuid" }, "paused": { "type": "boolean" } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "dashboard:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "dashboard:write" ] } }, "/projects/{projectId}/models/last-call": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/models/last-call", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdModelsLastCall", "description": "GET /api/v1/projects/{projectId}/models/last-call on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the model_api_last_call 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.", "x-caveman-operation": "reports.model_api_last_call", "x-caveman-operation-contract": "baa42fa7d169ba94bdb67feefc822a2e2cd2b4066b5dad8c32edf519e6bf3161", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/models/usage": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/models/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" } }, "operationId": "getProjectsProjectIdModelsUsage", "description": "GET /api/v1/projects/{projectId}/models/usage on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the model_api_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.", "x-caveman-operation": "reports.model_api_usage", "x-caveman-operation-contract": "165be8d2b3d481f1aaf8424eb142daf463697b53eac69a5c92bef323a5423d38", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/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" } }, "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.", "x-caveman-operation": "fixes.list_novelty", "x-caveman-operation-contract": "3a5dc4a85c5fddb87a218ab815eaa114e3e329f3687975e535f9187192ea81a6", "parameters": [ { "name": "classification", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Dismiss or mark opportunities implemented, create an experiment from an opportunity, record outcomes, and submit practice findings. Legacy optimization proposal creation is retired.", "x-caveman-operation": "fixes.dismiss_novelty", "x-caveman-operation-contract": "80d129552d9bc3910c89ec1774638719e5e0fb6bbdf32293af14fde005fee064", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Dismiss or mark opportunities implemented, create an experiment from an opportunity, record outcomes, and submit practice findings. Legacy optimization proposal creation is retired.", "x-caveman-operation": "fixes.promote_novelty", "x-caveman-operation-contract": "efd0cabcdbab31b092cefbc904dbf1d0ed8e8228b02696c66e9f430f9629fb9f", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/projects/{projectId}/onboarding": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/onboarding", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdOnboarding", "description": "GET /api/v1/projects/{projectId}/onboarding on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: A person's own first hour. The evidence an agent would want (opportunities, improvement report, imports) is already exposed through caveman_fixes and caveman_plan; this surface only adds what the human said about themselves.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /projects/{projectId}/onboarding", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdOnboarding", "description": "PATCH /api/v1/projects/{projectId}/onboarding on the Caveman Cloud control plane. Requires the settings:read scope. Not exposed to autonomous agents: Records what a HUMAN says they did, on a row their teammates read. An agent marking someone's onboarding done would put words in their mouth.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/projects/{projectId}/onboarding/learn": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/onboarding/learn", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdOnboardingLearn", "description": "GET /api/v1/projects/{projectId}/onboarding/learn on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Stage status for the human-facing learning page. Agents read the same evidence directly from the opportunities and continuous-improvement surfaces.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/onboarding/learn", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdOnboardingLearn", "description": "POST /api/v1/projects/{projectId}/onboarding/learn on the Caveman Cloud control plane. Requires the policy:draft scope. Not exposed to autonomous agents: Pulls the whole fleet's daily detection scan forward. Day-keyed so it cannot be repeated, but the decision to spend that scan early is the operator's.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/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" } }, "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.", "x-caveman-operation": "fixes.list_outcomes", "x-caveman-operation-contract": "cd8c96388edb3e7a59b5c827e6e20a9ebc1162efe24673a295328d269000ce82", "parameters": [ { "name": "correlation_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "correlation_kind", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Dismiss or mark opportunities implemented, create an experiment from an opportunity, record outcomes, and submit practice findings. Legacy optimization proposal creation is retired.", "x-caveman-operation": "fixes.record_outcome", "x-caveman-operation-contract": "3d6c58f64fef2053f06fa40d8ac0c548d622cd27f703053dd6ffa2bde7eaeab6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "correlation_id": { "type": "string" }, "correlation_kind": { "type": "string" }, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "observed_outcome": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "verified_outcome": { "type": "string" } }, "required": [ "correlation_kind", "correlation_id", "source", "observed_outcome", "confidence", "evidence_refs", "occurred_at" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "outcome:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Project settings for the bound project: semantic-cache shadowing and its options, pixel density, routing previews. Optimizations themselves are chosen per request (x-cave-optimize, x-cave-cache), not switched on here. Changing the semantic-cache threshold or TTL is refused server-side unless the caller holds policy:publish_s2_s3, which a scoped agent connection does not.", "x-caveman-operation": "project_setup.set_pixel_density", "x-caveman-operation-contract": "2f9e708ac62285109ae0736295f007451acbd93760b9f09e68da8b6be8e929bb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "level": { "enum": [ "conservative", "balanced", "max" ] } }, "required": [ "level" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:publish_s0_s1" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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", "responses": { "409": { "description": "cave_policy_deactivates — the draft would end an optimizer's approved-canary activation, and the caller did not confirm it. A listed always-on cache hint keeps running and keeps its verified savings; only the activation ends.", "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 optimizer id. 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" } }, "requestBody": { "required": false, "description": "Optional. Only carries the operator's acknowledgement of which approved-canary activations this publish would end; an empty body publishes when none would.", "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" } } } } } } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:publish_s2_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:publish_s2_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "policy.current", "x-caveman-operation-contract": "b59b1ef38198308ae7f80a481a9bb1238fdc39abacc42985d1ca5c14cf679f34", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "policy.delivery_status", "x-caveman-operation-contract": "ac4aec53b447572051e1c195cbe213206410320a51e779aef33df3b5dddf4d83", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org: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" } }, "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.", "x-caveman-operation": "fixes.practice_evidence", "x-caveman-operation-contract": "db6dba6e7515f716ec8ea8929f60590ced9169b7547c8af8cda7ef15c4f866e7", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/projects/{projectId}/prompt-environments": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/prompt-environments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdPromptEnvironments", "description": "GET /api/v1/projects/{projectId}/prompt-environments on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the list_environments action of the caveman_prompts tool (read access). Registered prompts and their versions.", "x-caveman-operation": "prompts.list_environments", "x-caveman-operation-contract": "c5299fe14a84e397594675948e8c6fc0e48f4590c28ab176146d5a1f0492953c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] }, "post": { "summary": "POST /projects/{projectId}/prompt-environments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdPromptEnvironments", "description": "POST /api/v1/projects/{projectId}/prompt-environments on the Caveman Cloud control plane. Requires the prompt:write scope. Exposed to autonomous agents as the create_environment action of the caveman_prompts_write tool (write access). Register prompts, add immutable versions, pin versions, and delete prompts. Author comparisons through Evals.", "x-caveman-operation": "prompts.create_environment", "x-caveman-operation-contract": "563c5de325fc5892ae6daa6e74e5b70fa592a0c66eaf780e9aa1766480f01669", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,47}$" } }, "required": [ "name" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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 and their versions.", "x-caveman-operation": "prompts.list", "x-caveman-operation-contract": "5c4afea2ad8306d8f37ae8218d78fb02239956b9ec264d154b1086f7d9a77b45", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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, add immutable versions, pin versions, and delete prompts. Author comparisons through Evals.", "x-caveman-operation": "prompts.create", "x-caveman-operation-contract": "2a64e2cc0fbbcc384f5a9d3f34f1db5e71c3b57581dd70598d6279359ab4d2e5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commit_message": { "type": "string" }, "description": { "type": "string" }, "model_defaults": {}, "name": { "type": "string", "minLength": 1 }, "system_text": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "object" } }, "user_text": { "type": "string" }, "variables": {} }, "required": [ "name" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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, add immutable versions, pin versions, and delete prompts. Author comparisons through Evals.", "x-caveman-operation": "prompts.delete", "x-caveman-operation-contract": "090670353cd6d1325ec2962abcdee3807a5f658105e08b6f2a81ea3bf6e0757a", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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 and their versions.", "x-caveman-operation": "prompts.get", "x-caveman-operation-contract": "fc411f92c0115806202319d76a7944ab8ac743aaa83136dfc377fa8ae61cecc9", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] } }, "/projects/{projectId}/prompts/{promptId}/environments": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/prompts/{promptId}/environments", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdPromptsPromptIdEnvironments", "description": "GET /api/v1/projects/{projectId}/prompts/{promptId}/environments on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the environments action of the caveman_prompts tool (read access). Registered prompts and their versions.", "x-caveman-operation": "prompts.environments", "x-caveman-operation-contract": "9eb2596da0253aefd3ce18f4feda3f538f970ed728dffecc30e2a1f2c7468107", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] } }, "/projects/{projectId}/prompts/{promptId}/environments/{environment}/promote": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "environment", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/prompts/{promptId}/environments/{environment}/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" } }, "operationId": "postProjectsProjectPromptsPromptEnvironmentsEnvironmentPromote", "description": "POST /api/v1/projects/{projectId}/prompts/{promptId}/environments/{environment}/promote on the Caveman Cloud control plane. Requires the prompt:write scope. Not exposed to autonomous agents: Changes the prompt that production traffic and SDK callers run. A person promotes; an agent proposes a version.", "x-caveman-operation": "prompts.promote", "x-caveman-operation-contract": "71604c46a0236dd08e3f183cece7ff3cbd759d50f6ba9fbc8831bdf728fa85f3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "version" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] } }, "/projects/{projectId}/prompts/{promptId}/environments/{environment}/rollback": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "environment", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/prompts/{promptId}/environments/{environment}/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" } }, "operationId": "postProjectsProjectPromptsPromptEnvironmentsEnvironmentRollback", "description": "POST /api/v1/projects/{projectId}/prompts/{promptId}/environments/{environment}/rollback on the Caveman Cloud control plane. Requires the prompt:write scope. Not exposed to autonomous agents: Changes the prompt that production traffic and SDK callers run. A person rolls back.", "x-caveman-operation": "prompts.rollback", "x-caveman-operation-contract": "901803c4f75adbe9ea58f8f6c66dad927335dea424dba9fcf283798c84b60a49", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "from_version": { "type": "integer", "minimum": 1 }, "note": { "type": "string", "maxLength": 500 } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] } }, "/projects/{projectId}/prompts/{promptId}/improvements": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/prompts/{promptId}/improvements", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdPromptsPromptIdImprovements", "description": "GET /api/v1/projects/{projectId}/prompts/{promptId}/improvements on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the improvements action of the caveman_prompts tool (read access). Registered prompts and their versions.", "x-caveman-operation": "prompts.improvements", "x-caveman-operation-contract": "a22d35b9346d121741c673aa818351e4cc18b2d7a60580f47e52c1af7446ae6b", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] }, "post": { "summary": "POST /projects/{projectId}/prompts/{promptId}/improvements", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdPromptsPromptIdImprovements", "description": "POST /api/v1/projects/{projectId}/prompts/{promptId}/improvements on the Caveman Cloud control plane. Requires the prompt:write scope. Not exposed to autonomous agents: Spends on the project's own model keys, up to the budget a person sets: one proposer call, then a comparison run. An agent drafts it as a proposal for a person to accept, and reads the result.", "x-caveman-operation": "prompts.improve", "x-caveman-operation-contract": "f52bab391ec9c2fa1b8e43a14e86ca7856a65db1e29907df1a53d776341eedb6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_version": { "type": "integer", "minimum": 1 }, "criteria": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 24 }, "annotations": { "type": "boolean" }, "budget_usd": { "type": "number", "exclusiveMinimum": 0 }, "model": { "type": "string", "pattern": "^[^/]+/.+$" }, "instructions": { "type": "string", "maxLength": 4000 } }, "required": [ "dataset_id", "criteria", "budget_usd" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:write" ] } }, "/projects/{projectId}/prompts/{promptId}/improvements/{improvementId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "improvementId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/prompts/{promptId}/improvements/{improvementId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdPromptsPromptIdImprovementsImprovementId", "description": "GET /api/v1/projects/{projectId}/prompts/{promptId}/improvements/{improvementId} on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the improvement action of the caveman_prompts tool (read access). Registered prompts and their versions.", "x-caveman-operation": "prompts.improvement", "x-caveman-operation-contract": "dfe4425c339ab5f1d68778fc84db2a1397d5e6bc6bd96948f0db4e7151a6fdb9", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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, add immutable versions, pin versions, and delete prompts. Author comparisons through Evals.", "x-caveman-operation": "prompts.pin_version", "x-caveman-operation-contract": "229ce55a1606a834fe18b97e5d54378ab3b537bf5fe6e8c9dccfddb54df639a8", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 } }, "required": [ "version" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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, add immutable versions, pin versions, and delete prompts. Author comparisons through Evals.", "x-caveman-operation": "prompts.add_version", "x-caveman-operation-contract": "eb8bff3024d93f40cdaeedfdec3a8f2150d936a2159cbf58b4b9a0ab56a1ad64", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_version": { "type": "integer", "minimum": 1 }, "commit_message": { "type": "string" }, "model_defaults": {}, "system_text": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "object" } }, "user_text": { "type": "string" }, "variables": {} } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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 and their versions.", "x-caveman-operation": "prompts.get_version", "x-caveman-operation-contract": "f0d894ed894f6b763fe4087467392ffe8aaba2e892f95af4e69670866b54459c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "prompt:read" ] } }, "/projects/{projectId}/prompts/resolve": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/prompts/resolve", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdPromptsResolve", "description": "GET /api/v1/projects/{projectId}/prompts/resolve on the Caveman Cloud control plane. Requires the prompt:read scope. Exposed to autonomous agents as the resolve action of the caveman_prompts tool (read access). Registered prompts and their versions.", "x-caveman-operation": "prompts.resolve", "x-caveman-operation-contract": "bbb52fdd4fe26cf7085b5d08d35d365daa80b51bb87c046a7247d98c5838eedb", "parameters": [ { "name": "slug", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The prompt's name." } }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "prompt:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "providers.list", "x-caveman-operation-contract": "897c3ae0664ab8abbacf1c1e4da3eee9814a1d47580db2d90203459e85fc06d3", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "provider:manage" ] } }, "/projects/{projectId}/quality": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/quality", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdQuality", "description": "GET /api/v1/projects/{projectId}/quality on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the status action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "quality.status", "x-caveman-operation-contract": "26108fc3589299831524fecb8dad7bfe6eb3732b7a66641ece4dcaf1480e2a01", "parameters": [ { "name": "workload_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workflow", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/quality-monitors/{monitorId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/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" } }, "operationId": "deleteProjectsProjectIdQualityMonitorsMonitorId", "description": "DELETE /api/v1/projects/{projectId}/quality-monitors/{monitorId} on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Deleting a monitor removes its action log and unit decisions for good; a person decides that. An agent pauses or archives one with set_status.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/quality-monitors/{monitorId}/actions": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/quality-monitors/{monitorId}/actions", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdQualityMonitorsMonitorIdActions", "description": "GET /api/v1/projects/{projectId}/quality-monitors/{monitorId}/actions on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the actions action of the caveman_monitors tool (read access). Quality monitors, their verdicts, the actions their rules fired, and an estimate of a monitor draft's volume and judge cost from recorded traffic.", "x-caveman-operation": "monitors.actions", "x-caveman-operation-contract": "5d30865d9d5889552ff3784af8f4cf4fc40bd270b6f42dd1242ac68bce38a9c0", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/quality-monitors/{monitorId}/actions/test": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/quality-monitors/{monitorId}/actions/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" } }, "operationId": "postProjectsProjectIdQualityMonitorsMonitorIdActionsTest", "description": "POST /api/v1/projects/{projectId}/quality-monitors/{monitorId}/actions/test on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: A test posts to a webhook, an egress channel; an agent that could trigger one could probe an operator's receivers.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/quality-monitors/{monitorId}/alerts": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /projects/{projectId}/quality-monitors/{monitorId}/alerts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdQualityMonitorsMonitorIdAlerts", "description": "PUT /api/v1/projects/{projectId}/quality-monitors/{monitorId}/alerts on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the set_alerts action of the caveman_monitors_write tool (write access). Pause or resume existing quality monitors, and run a monitor of criteria over traces already recorded, inside its daily judge budget. Creating, replacing, and archiving monitors stays human-only because grader endpoints receive captured payloads.", "x-caveman-operation": "monitors.set_alerts", "x-caveman-operation-contract": "b4cfda878cc6e02c2240f76bf582603b8ce5eecd840b0b2b347425f4902b9bbb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "conditions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$" }, "name": { "type": "string", "maxLength": 120 }, "criterion_id": { "anyOf": [ { "const": "*" }, { "type": "string", "format": "uuid" } ] }, "metric": { "enum": [ "failure_rate", "pass_rate", "mean_score", "judged_volume" ] }, "window_minutes": { "type": "integer", "minimum": 15, "maximum": 10080 }, "compare": { "enum": [ "absolute", "change" ] }, "direction": { "enum": [ "above", "below" ] }, "threshold": { "type": "number" }, "min_sample": { "type": "integer", "minimum": 0 }, "renotify_minutes": { "type": "integer", "minimum": 0, "maximum": 10080 }, "recovery": { "type": "boolean" }, "notify": { "type": "object", "additionalProperties": false, "properties": { "inbox": { "type": "boolean" }, "webhook_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 4 } } } }, "required": [ "criterion_id", "metric", "window_minutes", "compare", "direction", "threshold" ] }, "maxItems": 16 } }, "required": [ "conditions" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/quality-monitors/{monitorId}/alerts/dry-run": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/quality-monitors/{monitorId}/alerts/dry-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" } }, "operationId": "postProjectsProjectIdQualityMonitorsMonitorIdAlertsDryRun", "description": "POST /api/v1/projects/{projectId}/quality-monitors/{monitorId}/alerts/dry-run on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the alert_dry_run action of the caveman_monitors tool (read access). Quality monitors, their verdicts, the actions their rules fired, and an estimate of a monitor draft's volume and judge cost from recorded traffic.", "x-caveman-operation": "monitors.alert_dry_run", "x-caveman-operation-contract": "9c7cea562f61152bf527088e9212945e89ee81d0ffe13942a2d8bc7a7f5c0357", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "condition": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$" }, "name": { "type": "string", "maxLength": 120 }, "criterion_id": { "anyOf": [ { "const": "*" }, { "type": "string", "format": "uuid" } ] }, "metric": { "enum": [ "failure_rate", "pass_rate", "mean_score", "judged_volume" ] }, "window_minutes": { "type": "integer", "minimum": 15, "maximum": 10080 }, "compare": { "enum": [ "absolute", "change" ] }, "direction": { "enum": [ "above", "below" ] }, "threshold": { "type": "number" }, "min_sample": { "type": "integer", "minimum": 0 }, "renotify_minutes": { "type": "integer", "minimum": 0, "maximum": 10080 }, "recovery": { "type": "boolean" }, "notify": { "type": "object", "additionalProperties": false, "properties": { "inbox": { "type": "boolean" }, "webhook_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 4 } } } }, "required": [ "criterion_id", "metric", "window_minutes", "compare", "direction", "threshold" ] }, "lookback_days": { "type": "integer", "minimum": 1, "maximum": 30 } }, "required": [ "condition" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/quality-monitors/{monitorId}/backfill": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/quality-monitors/{monitorId}/backfill", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdQualityMonitorsMonitorIdBackfill", "description": "GET /api/v1/projects/{projectId}/quality-monitors/{monitorId}/backfill on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the backfill_status action of the caveman_monitors tool (read access). Quality monitors, their verdicts, the actions their rules fired, and an estimate of a monitor draft's volume and judge cost from recorded traffic.", "x-caveman-operation": "monitors.backfill_status", "x-caveman-operation-contract": "567246829a2e2b20845c9ec4a15b0f8b76dfdfa39c30178ed8dd6627a4239e9e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/quality-monitors/{monitorId}/backfill", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdQualityMonitorsMonitorIdBackfill", "description": "POST /api/v1/projects/{projectId}/quality-monitors/{monitorId}/backfill on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the backfill action of the caveman_monitors_write tool (write access). Pause or resume existing quality monitors, and run a monitor of criteria over traces already recorded, inside its daily judge budget. Creating, replacing, and archiving monitors stays human-only because grader endpoints receive captured payloads.", "x-caveman-operation": "monitors.backfill", "x-caveman-operation-contract": "6d14155ad27619fdebc538d2a8b41d5e05f0fd86654dc40e784fc027703d891c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "max_units": { "type": "integer", "minimum": 1, "maximum": 10000 }, "filter": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "maxItems": 32 }, "criterion_id": { "type": "string", "format": "uuid" }, "budget_usd": { "type": "number", "minimum": 0, "maximum": 1000000 } }, "required": [ "from", "to" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/quality-monitors/{monitorId}/backfill/cancel": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "monitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/quality-monitors/{monitorId}/backfill/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" } }, "operationId": "postProjectsProjectIdQualityMonitorsMonitorIdBackfillCancel", "description": "POST /api/v1/projects/{projectId}/quality-monitors/{monitorId}/backfill/cancel on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the cancel_backfill action of the caveman_monitors_write tool (write access). Pause or resume existing quality monitors, and run a monitor of criteria over traces already recorded, inside its daily judge budget. Creating, replacing, and archiving monitors stays human-only because grader endpoints receive captured payloads.", "x-caveman-operation": "monitors.cancel_backfill", "x-caveman-operation-contract": "e43975ded4bffa0a79be34577a8d9e44d4eb566df5369c9cfd9bfc3a16f6cc7f", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/quality-monitors/estimate": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/quality-monitors/estimate", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdQualityMonitorsEstimate", "description": "POST /api/v1/projects/{projectId}/quality-monitors/estimate on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the estimate action of the caveman_monitors tool (read access). Quality monitors, their verdicts, the actions their rules fired, and an estimate of a monitor draft's volume and judge cost from recorded traffic.", "x-caveman-operation": "monitors.estimate", "x-caveman-operation-contract": "05594f8324067b0739418718c333e214d59017b685e9e8e0b8574b60fae08169", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scope": { "enum": [ "span", "trace", "task", "session" ] }, "filter": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "maxItems": 32 }, "sample_rate": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "criteria": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 16 }, "task_idle_minutes": { "type": "integer", "minimum": 2, "maximum": 1440 } }, "required": [ "scope" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/quality/setup": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/quality/setup", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdQualitySetup", "description": "GET /api/v1/projects/{projectId}/quality/setup on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the setup_proposals action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "quality_setup.proposals", "x-caveman-operation-contract": "36fc69bf36f143723683b9025346b8a416444958c2514db3fe2475369d06d611", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/quality/setup/{workloadId}/approve": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workloadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/quality/setup/{workloadId}/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" } }, "operationId": "postProjectsProjectIdQualitySetupWorkloadIdApprove", "description": "POST /api/v1/projects/{projectId}/quality/setup/{workloadId}/approve on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Turn on approves criteria, the judge and the budget to qualify and run them (ADR 0063 addendum). A person decides.", "x-caveman-operation": "quality_setup.approve", "x-caveman-operation-contract": "c7da0c9753ffe6cb78e248136c53a074379428163b8ceb6d8521da569893a716", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "skip": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "edits": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "draft_id": { "type": "string", "format": "uuid" }, "statement": { "type": "string", "maxLength": 300 }, "pass_def": { "type": "string", "maxLength": 1000 }, "fail_def": { "type": "string", "maxLength": 1000 }, "na_def": { "type": "string", "maxLength": 1000 } }, "required": [ "draft_id" ] } }, "daily_budget_usd": { "type": "number", "minimum": 0 } }, "required": [ "request_id", "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/quality/setup/{workloadId}/decline": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workloadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/quality/setup/{workloadId}/decline", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdQualitySetupWorkloadIdDecline", "description": "POST /api/v1/projects/{projectId}/quality/setup/{workloadId}/decline on the Caveman Cloud control plane. Requires the autopilot:manage scope. Not exposed to autonomous agents: Turn on approves criteria, the judge and the budget to qualify and run them (ADR 0063 addendum). A person decides.", "x-caveman-operation": "quality_setup.decline", "x-caveman-operation-contract": "13edd80d67bbec11f54315052534605e73689be35b79f67178c86566c41f5082", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "autopilot:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "autopilot:manage" ] } }, "/projects/{projectId}/quality/setup/draft": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/quality/setup/draft", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdQualitySetupDraft", "description": "POST /api/v1/projects/{projectId}/quality/setup/draft on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the draft_quality_setup action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "quality_setup.draft", "x-caveman-operation-contract": "68eb8d0a0bf0ba0f54f003be146c47fe1a4a0a06c1862d6ea12bc8904d17437e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "workload_id": { "type": "string", "format": "uuid" } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/projects/{projectId}/repo-contributors": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/repo-contributors", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdRepoContributors", "description": "GET /api/v1/projects/{projectId}/repo-contributors on the Caveman Cloud control plane. Requires the member:manage scope. Exposed to autonomous agents as the repo_contributors 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.", "x-caveman-operation": "people.repo_contributors", "x-caveman-operation-contract": "8bb8424c33e23b27c6f4e60238f470fe91be936b47481f9abcd5967d8dee88f4", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/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" } }, "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.", "x-caveman-operation": "policy.retention", "x-caveman-operation-contract": "97c42f6e613100bba6bb7ab76c8ec56773d24432717e7cc503e111f60bb47c78", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "settings:read" ] } }, "/projects/{projectId}/review": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/review", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdReview", "description": "GET /api/v1/projects/{projectId}/review on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_review action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "review.list", "x-caveman-operation-contract": "d41f5b9616616fc6f2fa221a5f81ff555d83892824192117f41a14c325da627e", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "assignee", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "criterion_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "unlabelled_by_me", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/review", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdReview", "description": "POST /api/v1/projects/{projectId}/review on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the queue_review action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "review.add", "x-caveman-operation-contract": "6bfab3b2ecb0d8546d1755f626c28303436c6243681dbb90f865f075cae53e29", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "units": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "scope": { "enum": [ "span", "trace", "task", "row", "cell" ] }, "unit_id": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "scope", "unit_id" ] }, "minItems": 1, "maxItems": 200 }, "from": { "type": "object", "additionalProperties": false, "properties": { "scope": { "enum": [ "span", "trace", "task" ] }, "filter": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "maxItems": 32 }, "window_hours": { "type": "integer", "minimum": 1, "maximum": 720 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 } }, "required": [ "scope" ] }, "criterion_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 16 }, "assignee_id": { "type": "string", "format": "uuid" } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/review/{itemId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /projects/{projectId}/review/{itemId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdReviewItemId", "description": "PATCH /api/v1/projects/{projectId}/review/{itemId} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the label_review action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "review.update", "x-caveman-operation-contract": "47cb4f427b7d9e90344a7c7c9bcc1f471687be1476a85c2006f9ef641c5b135b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "label": { "enum": [ "pass", "fail", "not_applicable", null ] }, "score": { "type": [ "number", "null" ] }, "category": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "text": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "note": { "type": "string", "maxLength": 2000 }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "enum": [ "open", "done", "skipped" ] }, "write_to_expected": { "type": "boolean" }, "expected_column": { "type": "string" } }, "required": [ "revision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/review/agreement": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/review/agreement", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdReviewAgreement", "description": "GET /api/v1/projects/{projectId}/review/agreement on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the review_agreement action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "quality.review_agreement", "x-caveman-operation-contract": "9ff29c69c7f8ea9c2f907e65a5fe3351badcd28e64bc54f10ddc60078ddb505c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/review/bulk": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/review/bulk", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdReviewBulk", "description": "POST /api/v1/projects/{projectId}/review/bulk on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the bulk_review action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.bulk_review", "x-caveman-operation-contract": "50c1936b7847112967baf6d5075895d42205787ff65f7c5921bed6ccf373e24f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "action": { "enum": [ "assign", "skip", "label", "add_to_dataset" ] }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "id" ] }, "minItems": 1, "maxItems": 200 }, "label": { "enum": [ "pass", "fail", "not_applicable", null ] }, "score": { "type": [ "number", "null" ] }, "category": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "text": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "note": { "type": "string", "maxLength": 2000 }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" }, "dataset_id": { "type": "string", "format": "uuid" } }, "required": [ "action", "items" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/review/schemas": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/review/schemas", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdReviewSchemas", "description": "GET /api/v1/projects/{projectId}/review/schemas on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_review_schemas action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "quality.list_review_schemas", "x-caveman-operation-contract": "14ebf126f600f0d582faf363fb4d6a101d8cd45c7c3df937cc80ebc26eb3864e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "put": { "summary": "PUT /projects/{projectId}/review/schemas", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdReviewSchemas", "description": "PUT /api/v1/projects/{projectId}/review/schemas on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the set_review_schema action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "x-caveman-operation": "evals.set_review_schema", "x-caveman-operation-contract": "a3a4ea0abab88add417ccc74d03252602cbce193f0d79f283eb3e05bbc664526", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "criterion_id": { "type": [ "string", "null" ], "format": "uuid" }, "schema": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "pass_fail", "score", "category", "text" ] }, "min": { "type": "number" }, "max": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "reviewers": { "type": "integer", "minimum": 1, "maximum": 10 } }, "required": [ "kind" ] } }, "required": [ "schema" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/review/summary": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/review/summary", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdReviewSummary", "description": "GET /api/v1/projects/{projectId}/review/summary on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the review_summary action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "review.summary", "x-caveman-operation-contract": "bcb104a71fc0beaf3ddb35193b005714f66316e3ade28ada20d6dfe45cc5be42", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/route-autoclimb": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/route-autoclimb", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdRouteAutoclimb", "description": "GET /api/v1/projects/{projectId}/route-autoclimb on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the route_autoclimb action of the caveman_policy tool (read access). Current policy, delivery status, budgets, retention and consent posture for the bound project.", "x-caveman-operation": "autoclimb.get", "x-caveman-operation-contract": "57aabe5798580df66377c73f8ba192ca3403d1c940eff41396b15d669072fcb5", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /projects/{projectId}/route-autoclimb", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdRouteAutoclimb", "description": "PATCH /api/v1/projects/{projectId}/route-autoclimb on the Caveman Cloud control plane. Requires the policy:publish_s2_s3 scope. Not exposed to autonomous agents: Sets how much provider money automatic backtests may spend and whether Caveman publishes routes without asking. Turning on auto-publish grants publishing, so a human with publish permission decides.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:publish_s2_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:publish_s2_s3" ] } }, "/projects/{projectId}/route-autoclimb/exclusions": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/route-autoclimb/exclusions", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdRouteAutoclimbExclusions", "description": "GET /api/v1/projects/{projectId}/route-autoclimb/exclusions on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the exclusions action of the caveman_autoclimb tool (read access). What Caveman is proving on one workload, what stops it, what proving has cost there, and which candidate models a person excluded. Starting, stopping and excluding stay with people.", "x-caveman-operation": "autoclimb.exclusions", "x-caveman-operation-contract": "0215bd054b795b5e5386e76e23da7c2bba515bed33d0879638bf27d1b794f8ad", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /projects/{projectId}/route-autoclimb/exclusions", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdRouteAutoclimbExclusions", "description": "POST /api/v1/projects/{projectId}/route-autoclimb/exclusions on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Stops Caveman proving a candidate model for a workload until a person clears it. Which models Caveman may test on a customer's traffic is a person's call.", "x-caveman-operation": "autoclimb.exclude", "x-caveman-operation-contract": "03e23ca9e19c5671eb7844208e92674ea527ffca5bb378e778b5c2775464fea1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "workflow": { "type": "string", "pattern": "^[a-z0-9_-]{1,200}$" }, "candidate_model": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "workflow", "candidate_model" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/route-autoclimb/exclusions/{exclusionId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "exclusionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /projects/{projectId}/route-autoclimb/exclusions/{exclusionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteProjectsProjectIdRouteAutoclimbExclusionsExclusionId", "description": "DELETE /api/v1/projects/{projectId}/route-autoclimb/exclusions/{exclusionId} on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Lets Caveman prove an excluded candidate again, which spends the project's proving budget on the customer's keys. A person clears what a person excluded.", "x-caveman-operation": "autoclimb.unexclude", "x-caveman-operation-contract": "f76f9b9f8bff28b99334677f9f7fa13fac96f100ddc7e9b4953757e673d8d688", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/route-autoclimb/workloads/{workflow}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workflow", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/route-autoclimb/workloads/{workflow}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdRouteAutoclimbWorkloadsWorkflow", "description": "GET /api/v1/projects/{projectId}/route-autoclimb/workloads/{workflow} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the workload action of the caveman_autoclimb tool (read access). What Caveman is proving on one workload, what stops it, what proving has cost there, and which candidate models a person excluded. Starting, stopping and excluding stay with people.", "x-caveman-operation": "autoclimb.workload", "x-caveman-operation-contract": "ffe96a2b50d557d6288e7ed795c977cc672fb30b50d9aa599eadb22bfb02c9cc", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/router-learning-consent": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "PATCH /projects/{projectId}/router-learning-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" } }, "operationId": "patchProjectsProjectIdRouterLearningConsent", "description": "PATCH /api/v1/projects/{projectId}/router-learning-consent on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Changes whether tenant traffic may train shared routing models. An optimizer cannot grant itself access to customer data; a human must make this legal and data-use decision.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/projects/{projectId}/routes/compare": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/routes/compare", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdRoutesCompare", "description": "POST /api/v1/projects/{projectId}/routes/compare on the Caveman Cloud control plane. Requires the experiment:run scope. Not exposed to autonomous agents: Spends the project's provider money replaying saved requests against candidate models; a person starts it from the route builder or the CLI.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/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" } }, "operationId": "postProjectsProjectIdSampleData", "description": "POST /api/v1/projects/{projectId}/sample-data on the Caveman Cloud control plane. Requires the policy:draft 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/projects/{projectId}/scenario-connections": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/scenario-connections", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioConnection" } } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdScenarioConnections", "description": "GET /api/v1/projects/{projectId}/scenario-connections on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_scenario_projects_projectid_scenario_connections action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "parameters": [], "x-caveman-operation": "evals.get_scenario_projects_projectid_scenario_connections", "x-caveman-operation-contract": "6b0ee57c89b4e8a72f49578405ddafd4afea8866b57a2688719867af1503816e", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] }, "post": { "summary": "POST /projects/{projectId}/scenario-connections", "responses": { "201": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioConnection" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdScenarioConnections", "description": "POST /api/v1/projects/{projectId}/scenario-connections on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Sandbox credential management and recording rollout gate approval remain human-only.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "endpoint": { "type": "string", "format": "uri" }, "reset_endpoint": { "type": "string", "format": "uri" }, "environment": { "const": "sandbox" }, "revision": { "type": "integer" } }, "required": [ "name", "endpoint", "reset_endpoint", "environment" ] }, "secret": { "type": "string", "minLength": 8, "writeOnly": true } }, "required": [ "connection", "secret" ] } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/scenario-runs/{runId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/scenario-runs/{runId}", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioRun" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdScenarioRunsRunId", "description": "GET /api/v1/projects/{projectId}/scenario-runs/{runId} on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_scenario_projects_projectid_scenario_runs_runid action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "parameters": [], "x-caveman-operation": "evals.get_scenario_projects_projectid_scenario_runs_runid", "x-caveman-operation-contract": "c7a3c3e5eff847c01411553751aeb438220c1dec3397c7972f6e5709e1a6f33f", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/scenario-runs/{runId}/cancel": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/scenario-runs/{runId}/cancel", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdScenarioRunsRunIdCancel", "description": "POST /api/v1/projects/{projectId}/scenario-runs/{runId}/cancel on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the post_scenario_projects_projectid_scenario_runs_runid_cancel action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "x-caveman-operation": "evals.post_scenario_projects_projectid_scenario_runs_runid_cancel", "x-caveman-operation-contract": "ce28fdc960864cd8f73bbf5ad02e1bfdad02f044b30a254c5d0528f57cbce9de", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/scenario-runs/{runId}/events": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/scenario-runs/{runId}/events", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioEvent" } } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdScenarioRunsRunIdEvents", "description": "GET /api/v1/projects/{projectId}/scenario-runs/{runId}/events on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_scenario_projects_projectid_scenario_runs_runid_events action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-operation": "evals.get_scenario_projects_projectid_scenario_runs_runid_events", "x-caveman-operation-contract": "4343a8df6f8d657ce1fbceffc34960f35e290d77ecc831a70c737398b37b3984", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/scenario-runs/{runId}/gate": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/scenario-runs/{runId}/gate", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioGate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdScenarioRunsRunIdGate", "description": "GET /api/v1/projects/{projectId}/scenario-runs/{runId}/gate on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_scenario_projects_projectid_scenario_runs_runid_gate action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "parameters": [ { "name": "candidate", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "purpose", "in": "query", "required": false, "schema": { "enum": [ "regression", "rollout" ] } } ], "x-caveman-operation": "evals.get_scenario_projects_projectid_scenario_runs_runid_gate", "x-caveman-operation-contract": "1fbb860f75cb61f3041a8790424be106bc39fe5f232410e702f63f93b85cecf9", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] }, "post": { "summary": "POST /projects/{projectId}/scenario-runs/{runId}/gate", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioGate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdScenarioRunsRunIdGate", "description": "POST /api/v1/projects/{projectId}/scenario-runs/{runId}/gate on the Caveman Cloud control plane. Requires the experiment:approve_s3 scope. Not exposed to autonomous agents: Sandbox credential management and recording rollout gate approval remain human-only.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "candidate": { "type": "string" } }, "required": [ "candidate" ] } } } }, "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } }, "/projects/{projectId}/scenario-runs/{runId}/regression": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/scenario-runs/{runId}/regression", "responses": { "201": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioSuite" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdScenarioRunsRunIdRegression", "description": "POST /api/v1/projects/{projectId}/scenario-runs/{runId}/regression on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the post_scenario_projects_projectid_scenario_runs_runid_regression action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "trial_id": { "type": "string", "minLength": 1 } }, "required": [ "trial_id" ] } } } }, "x-caveman-operation": "evals.post_scenario_projects_projectid_scenario_runs_runid_regression", "x-caveman-operation-contract": "5802c202592967583def30737946b1155cfe49d6fc348c8b8c93f12e1805d7bb", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/scenario-suites": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/scenario-suites", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioSuite" } } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdScenarioSuites", "description": "GET /api/v1/projects/{projectId}/scenario-suites on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_scenario_projects_projectid_scenario_suites action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "parameters": [], "x-caveman-operation": "evals.get_scenario_projects_projectid_scenario_suites", "x-caveman-operation-contract": "8c8291df42967f47c057a40f8140b6932374403834cbdc8aa8ea974832df8693", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] }, "post": { "summary": "POST /projects/{projectId}/scenario-suites", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioSuite" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdScenarioSuites", "description": "POST /api/v1/projects/{projectId}/scenario-suites on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the post_scenario_projects_projectid_scenario_suites action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "document": { "type": "object", "properties": { "schema_version": { "const": 1 }, "cases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "situation": { "type": "string" }, "persona": { "type": "string" }, "source": { "enum": [ "operator", "trace", "synthetic", "regression" ] }, "source_id": { "type": "string" }, "split": { "enum": [ "optimization", "holdout" ] }, "script": { "type": [ "array", "null" ], "items": { "type": "string" } }, "fixtures": {}, "fixture_version": { "type": "string" }, "criteria": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "kind": { "enum": [ "tool_result", "fixture_state", "llm" ] }, "tool": { "type": "string" }, "path": { "type": "string" }, "equals": {} }, "required": [ "id", "description", "kind" ], "additionalProperties": false } } }, "required": [ "id", "name", "situation", "source", "split", "script", "fixtures", "fixture_version", "criteria" ], "additionalProperties": false }, "minItems": 1, "maxItems": 400 }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "connection_id": { "type": "string", "format": "uuid" }, "agent_version": { "type": "string" }, "policy_version": { "type": "string" }, "parameters": { "type": [ "object", "null" ] } }, "required": [ "id", "name", "connection_id", "agent_version", "policy_version" ], "additionalProperties": false }, "minItems": 1, "maxItems": 8 }, "mode": { "enum": [ "frozen", "adaptive" ] }, "trials": { "type": "integer", "minimum": 1, "maximum": 100 }, "max_turns": { "type": "integer", "minimum": 1, "maximum": 50 }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 600 }, "budget_micros": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "call_budget_micros": { "type": "integer", "minimum": 1 }, "simulator": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "version": { "type": "string" } }, "required": [ "provider", "model", "version" ], "additionalProperties": false }, "judge": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "version": { "type": "string" } }, "required": [ "provider", "model", "version" ], "additionalProperties": false }, "seed": { "type": "integer" } }, "required": [ "schema_version", "cases", "variants", "mode", "trials", "max_turns", "timeout_seconds", "budget_micros", "call_budget_micros" ], "additionalProperties": false }, "revision": { "type": "integer", "minimum": 0 } }, "required": [ "name", "document" ] } } } }, "x-caveman-operation": "evals.post_scenario_projects_projectid_scenario_suites", "x-caveman-operation-contract": "446e173e37ed8a36f9a1ebaa777b805b06a6fdc15de1382881d762c93fb1f9df", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/scenario-suites/{suiteId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "suiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /projects/{projectId}/scenario-suites/{suiteId}", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioSuite" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdScenarioSuitesSuiteId", "description": "PUT /api/v1/projects/{projectId}/scenario-suites/{suiteId} on the Caveman Cloud control plane. Requires the eval:write scope. Exposed to autonomous agents as the put_scenario_projects_projectid_scenario_suites_suiteid action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "document": { "type": "object", "properties": { "schema_version": { "const": 1 }, "cases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "situation": { "type": "string" }, "persona": { "type": "string" }, "source": { "enum": [ "operator", "trace", "synthetic", "regression" ] }, "source_id": { "type": "string" }, "split": { "enum": [ "optimization", "holdout" ] }, "script": { "type": [ "array", "null" ], "items": { "type": "string" } }, "fixtures": {}, "fixture_version": { "type": "string" }, "criteria": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "kind": { "enum": [ "tool_result", "fixture_state", "llm" ] }, "tool": { "type": "string" }, "path": { "type": "string" }, "equals": {} }, "required": [ "id", "description", "kind" ], "additionalProperties": false } } }, "required": [ "id", "name", "situation", "source", "split", "script", "fixtures", "fixture_version", "criteria" ], "additionalProperties": false }, "minItems": 1, "maxItems": 400 }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "connection_id": { "type": "string", "format": "uuid" }, "agent_version": { "type": "string" }, "policy_version": { "type": "string" }, "parameters": { "type": [ "object", "null" ] } }, "required": [ "id", "name", "connection_id", "agent_version", "policy_version" ], "additionalProperties": false }, "minItems": 1, "maxItems": 8 }, "mode": { "enum": [ "frozen", "adaptive" ] }, "trials": { "type": "integer", "minimum": 1, "maximum": 100 }, "max_turns": { "type": "integer", "minimum": 1, "maximum": 50 }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 600 }, "budget_micros": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "call_budget_micros": { "type": "integer", "minimum": 1 }, "simulator": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "version": { "type": "string" } }, "required": [ "provider", "model", "version" ], "additionalProperties": false }, "judge": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "version": { "type": "string" } }, "required": [ "provider", "model", "version" ], "additionalProperties": false }, "seed": { "type": "integer" } }, "required": [ "schema_version", "cases", "variants", "mode", "trials", "max_turns", "timeout_seconds", "budget_micros", "call_budget_micros" ], "additionalProperties": false } }, "required": [ "revision", "name", "document" ] } } } }, "x-caveman-operation": "evals.put_scenario_projects_projectid_scenario_suites_suiteid", "x-caveman-operation-contract": "b3dae565e574d28f7384c6a274158cdc3c8dd4069b9f51d83612c96d21d6572c", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/scenario-suites/{suiteId}/runs": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "suiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/scenario-suites/{suiteId}/runs", "responses": { "200": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioRun" } } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdScenarioSuitesSuiteIdRuns", "description": "GET /api/v1/projects/{projectId}/scenario-suites/{suiteId}/runs on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the get_scenario_projects_projectid_scenario_suites_suiteid_runs action of the caveman_evals tool (read access). Versioned datasets, reusable evaluators, workbench documents, strict suites, and evaluation evidence.", "parameters": [], "x-caveman-operation": "evals.get_scenario_projects_projectid_scenario_suites_suiteid_runs", "x-caveman-operation-contract": "7fcdc2a830d371eb515e96c66799a43250c161b4ec90cac4fb9d47331ff7e261", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] }, "post": { "summary": "POST /projects/{projectId}/scenario-suites/{suiteId}/runs", "responses": { "202": { "description": "Tenant-scoped simulation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioRun" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdScenarioSuitesSuiteIdRuns", "description": "POST /api/v1/projects/{projectId}/scenario-suites/{suiteId}/runs on the Caveman Cloud control plane. Requires the experiment:run scope. Exposed to autonomous agents as the post_scenario_projects_projectid_scenario_suites_suiteid_runs action of the caveman_evals_write tool (write access). Author versioned datasets, reusable evaluators and workbenches; create strict suites, ingest evidence, and run baselines. Evidence ingest supports dry_run — always dry-run first. Ask Caveman to draft quality criteria again within the drafting allowance, propose a criterion for a person to turn on, and hold the pull request that adds the Caveman check to CI. Track a criterion on a slice of traces in one step: from an agent it lands proposed, and a person turns it on. Queue units for review and label them (an agent's label is recorded as an agent's, never as human gold), and make a dataset from recorded traffic.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "split": { "enum": [ "optimization", "holdout" ] } }, "required": [ "revision", "split" ] } } } }, "x-caveman-operation": "evals.post_scenario_projects_projectid_scenario_suites_suiteid_runs", "x-caveman-operation-contract": "6d6996cef0ea3295090383347df1396b1cac5b822cd30ddf8fb16d49aae9b608", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:run" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:run" ] } }, "/projects/{projectId}/semantic-cache": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/semantic-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" } }, "operationId": "getProjectsProjectIdSemanticCache", "description": "GET /api/v1/projects/{projectId}/semantic-cache on the Caveman Cloud control plane. Requires the org:read scope. Exposed to autonomous agents as the get_semantic_cache 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.", "x-caveman-operation": "context.get_semantic_cache", "x-caveman-operation-contract": "6b7a88afa2f43cb7c1bae6c52af51ee9dc4b77740b2709a7833238aaa1b4ae46", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:read" ] }, "put": { "summary": "PUT /projects/{projectId}/semantic-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" } }, "operationId": "putProjectsProjectIdSemanticCache", "description": "PUT /api/v1/projects/{projectId}/semantic-cache on the Caveman Cloud control plane. Requires the policy:publish_s0_s1 scope. Exposed to autonomous agents as the set_semantic_cache action of the caveman_project_setup tool (write access). Project settings for the bound project: semantic-cache shadowing and its options, pixel density, routing previews. Optimizations themselves are chosen per request (x-cave-optimize, x-cave-cache), not switched on here. Changing the semantic-cache threshold or TTL is refused server-side unless the caller holds policy:publish_s2_s3, which a scoped agent connection does not.", "x-caveman-operation": "project_setup.set_semantic_cache", "x-caveman-operation-contract": "8a60920050eac61ca12d75f28f8cbe9fe5512f78afefef912937579496271e4d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "mode": { "enum": [ "off", "shadow" ] }, "threshold": { "type": "number", "minimum": 0.85, "maximum": 0.99 }, "threshold_mode": { "enum": [ "auto", "pinned" ] }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 86400 } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:publish_s0_s1" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:publish_s0_s1" ] } }, "/projects/{projectId}/semantic-cache/compare": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/semantic-cache/compare", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdSemanticCacheCompare", "description": "POST /api/v1/projects/{projectId}/semantic-cache/compare on the Caveman Cloud control plane. Requires the policy:publish_s0_s1 scope. Exposed to autonomous agents as the compare_semantic_cache action of the caveman_project_setup tool (write access). Project settings for the bound project: semantic-cache shadowing and its options, pixel density, routing previews. Optimizations themselves are chosen per request (x-cave-optimize, x-cave-cache), not switched on here. Changing the semantic-cache threshold or TTL is refused server-side unless the caller holds policy:publish_s2_s3, which a scoped agent connection does not.", "x-caveman-operation": "project_setup.compare_semantic_cache", "x-caveman-operation-contract": "00db7bb58ca24ff4ac699fd7d98d8d9ff2847ca234da3a12f07840b3b7cbbb2b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "original": { "type": "string", "minLength": 2, "maxLength": 7994 }, "candidate": { "type": "string", "minLength": 2, "maxLength": 7994 } }, "required": [ "original", "candidate" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:publish_s0_s1" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:publish_s0_s1" ] } }, "/projects/{projectId}/setup": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/setup", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdSetup", "description": "GET /api/v1/projects/{projectId}/setup on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_setup action of the caveman_workflows tool (read access). Agents, workflows, and the observed workflow fingerprint registry that traffic is attributed to.", "x-caveman-operation": "setup.show", "x-caveman-operation-contract": "79f340f48d76a54298cfc9bc979ad441073731acef711c8870bc50612f178705", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/setup/changes": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/setup/changes", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdSetupChanges", "description": "POST /api/v1/projects/{projectId}/setup/changes on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the hold_setup_change 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.", "x-caveman-operation": "setup.hold", "x-caveman-operation-contract": "1dc948f32fb77a44f01e2cd69fc2412fb275e62fac1930a4ceee17ed807a7bd6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "purpose": { "type": "string" }, "branch": { "type": "string" }, "revert_variable": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "path": { "type": "string" }, "before_sha256": { "type": "string" }, "edits": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "old": { "type": "string" }, "new": { "type": "string" } } } }, "create": { "type": "string" } } } } }, "required": [ "purpose", "revert_variable", "files" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/projects/{projectId}/setup/inventory": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "PUT /projects/{projectId}/setup/inventory", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdSetupInventory", "description": "PUT /api/v1/projects/{projectId}/setup/inventory on the Caveman Cloud control plane. Requires the setup:write scope. Exposed to autonomous agents as the assert_setup_inventory 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.", "x-caveman-operation": "setup.assert", "x-caveman-operation-contract": "c9a33a3a753539c5aade67b71d0fb58ebe882f726cf34c8a42d12ed94713dff0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "line": { "type": "integer" }, "workload": { "type": "string" }, "vendor": { "type": "string" }, "input": { "type": "string" }, "expected": { "type": "string" } } } } }, "required": [ "items" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "setup:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "setup:write" ] } }, "/projects/{projectId}/spot-checks/{batchId}/labels": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/spot-checks/{batchId}/labels", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdSpotChecksBatchIdLabels", "description": "POST /api/v1/projects/{projectId}/spot-checks/{batchId}/labels on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Spot-check labels are human gold anchors for judge trust (SPEC §4.6). An agent cannot stand in for a human reviewer.", "x-caveman-operation": "spot_checks.submit", "x-caveman-operation-contract": "a8525ea48a47dfd899607e9a3ccdcabbd7f36b70f3f262297467ee9f557e9f95", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "item_id": { "type": "string", "format": "uuid" }, "label": { "enum": [ "pass", "fail", "not_applicable", "skip" ] }, "note": { "type": "string", "maxLength": 280 } }, "required": [ "item_id", "label" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/sql": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/sql", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdSql", "description": "POST /api/v1/projects/{projectId}/sql on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the query action of the caveman_sql tool (read access). One read-only ClickHouse SELECT over the bound project's SQL tables (requests, spans, tool_events, evals, logs, errors, events). The database pins the tenant and the window. Read sql.schema first. Per-person columns need billing:read; payload columns need payload:read and trace:read_payload. Results are bounded, never paged by re-running.", "x-caveman-operation": "sql.query", "x-caveman-operation-contract": "f4034423b801e9b24de9ed924fb83aa9e0a38402664b9a79d6cbacd6b4916902", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sql": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "One ClickHouse SELECT over the SQL tables that sql.schema lists. Bind values as {name:Type} placeholders." }, "params": { "type": "object", "maxProperties": 100, "description": "Values for the {name:Type} placeholders; names may not start with cave_ or param_.", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 4096 }, { "type": "number" }, { "type": "array", "maxItems": 1000, "items": { "type": "string", "maxLength": 4096 } } ] } }, "window": { "type": "string", "pattern": "^[1-9][0-9]{0,3}[hd]$", "description": "Look back from now, 1h to 90d. Send window or from/to; neither reads the last 7 days." }, "from": { "type": "string", "maxLength": 40, "description": "UTC start, RFC3339 or YYYY-MM-DD; at most 90 days before to." }, "to": { "type": "string", "maxLength": 40, "description": "UTC end, RFC3339 or YYYY-MM-DD; defaults to now." } }, "required": [ "sql" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/sql/schema": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/sql/schema", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdSqlSchema", "description": "GET /api/v1/projects/{projectId}/sql/schema on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the schema action of the caveman_sql tool (read access). One read-only ClickHouse SELECT over the bound project's SQL tables (requests, spans, tool_events, evals, logs, errors, events). The database pins the tenant and the window. Read sql.schema first. Per-person columns need billing:read; payload columns need payload:read and trace:read_payload. Results are bounded, never paged by re-running.", "x-caveman-operation": "sql.schema", "x-caveman-operation-contract": "92dfe9cda2a4cd83f6d535cc784b24226f21e89f38745823019368eea5ed494b", "parameters": [ { "name": "table", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "One SQL table's columns; omit for the overview of tables, rules and examples." } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/sql/tag-keys": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/sql/tag-keys", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdSqlTagKeys", "description": "GET /api/v1/projects/{projectId}/sql/tag-keys on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the tag_keys action of the caveman_sql tool (read access). One read-only ClickHouse SELECT over the bound project's SQL tables (requests, spans, tool_events, evals, logs, errors, events). The database pins the tenant and the window. Read sql.schema first. Per-person columns need billing:read; payload columns need payload:read and trace:read_payload. Results are bounded, never paged by re-running.", "x-caveman-operation": "sql.tag_keys", "x-caveman-operation-contract": "22b5664c32be7aeb19903778f0df0908e4e0c69640c3ed43cde11fb51999c81d", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "put": { "summary": "PUT /projects/{projectId}/sql/tag-keys", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "putProjectsProjectIdSqlTagKeys", "description": "PUT /api/v1/projects/{projectId}/sql/tag-keys on the Caveman Cloud control plane. Requires the org:update scope. Not exposed to autonomous agents: Decides which tag values every metadata-only caller, agents included, may read. An access-control change, so a human owner or admin must be the actor.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:update" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "org:update" ] } }, "/projects/{projectId}/tasks/{taskKey}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "taskKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/tasks/{taskKey}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdTasksTaskKey", "description": "GET /api/v1/projects/{projectId}/tasks/{taskKey} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_task action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "tasks.get", "x-caveman-operation-contract": "1078913b46302b54b966504721f2a2d6b2275caa417fff4ad5b5762ffe59cd0e", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/tasks/{taskKey}/content": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "taskKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/tasks/{taskKey}/content", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdTasksTaskKeyContent", "description": "GET /api/v1/projects/{projectId}/tasks/{taskKey}/content on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the task_content action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "tasks.content", "x-caveman-operation-contract": "f9e920588200dd6344f9c1616dc16b7f6e2b70c05326d4289fe4c54458451546", "parameters": [ { "name": "steps", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "part", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/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" } }, "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.", "x-caveman-operation": "fixes.list_themes", "x-caveman-operation-contract": "df1fafbfbd6a9b87876d75d5e533cc13e19411fde9f7512c0d5bc81f032b515e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "fixes.get_theme", "x-caveman-operation-contract": "2177e432f0f009cdd4457f333ad55ffa63f49e9e7437339540923b663f81bd67", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/trace-payload": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/trace-payload", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdTracePayload", "description": "POST /api/v1/projects/{projectId}/trace-payload on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the payload action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.payload", "x-caveman-operation-contract": "66987a8c77dd21545b108201a1f45b3a83ae77369009397c5889c8c064c5f1be", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date-time", "description": "Explicit UTC start of a window spanning at most 90 days." }, "to": { "type": "string", "format": "date-time", "description": "Explicit UTC end, after from and at most 90 days later." }, "trace_id": { "type": "string", "pattern": "^[a-fA-F0-9]{16,64}$" }, "request_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "request", "response", "request_compressed" ] }, "section": { "type": "integer", "minimum": 0, "description": "Read one part of the body by its outline index. A body over 64 KiB answers with status captured_outline: its parts with sizes and tool names, no text." }, "offset": { "type": "integer", "minimum": 0, "description": "Byte offset into the section; pass the previous answer's next_offset to read on." } }, "required": [ "from", "to", "trace_id", "request_id", "kind" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] } }, "/projects/{projectId}/traces/{traceId}/annotations": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List retained human trace review notes", "responses": { "200": { "description": "Trace review note response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnnotation" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "span_id", "in": "query", "schema": { "type": "string" } } ], "operationId": "getProjectsProjectIdTracesTraceIdAnnotations", "description": "GET /api/v1/projects/{projectId}/traces/{traceId}/annotations on the Caveman Cloud control plane. Requires the payload:read scope. Not exposed to autonomous agents: Human trace review notes can contain captured content. Reading them requires content access; agents cannot impersonate a human reviewer.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "payload:read" ] }, "post": { "summary": "Create a human review note with a retry-safe client id", "responses": { "201": { "description": "Trace review note response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceAnnotation" } } } }, "409": { "description": "Review changed; current scoped note permits explicit draft-preserving recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceAnnotationConflict" } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "POST /api/v1/projects/{projectId}/traces/{traceId}/annotations on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Human trace review notes can contain captured content. Reading them requires content access; agents cannot impersonate a human reviewer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "span_id": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "note": { "type": "string", "maxLength": 10000 } }, "required": [ "id", "label", "note" ] } } } }, "operationId": "postProjectsProjectIdTracesTraceIdAnnotations", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/traces/{traceId}/annotations/{annotationId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "annotationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Edit or resolve a review note at its expected revision", "responses": { "200": { "description": "Trace review note response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceAnnotation" } } } }, "409": { "description": "Review changed; current scoped note permits explicit draft-preserving recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceAnnotationConflict" } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "description": "PATCH /api/v1/projects/{projectId}/traces/{traceId}/annotations/{annotationId} on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Human trace review notes can contain captured content. Reading them requires content access; agents cannot impersonate a human reviewer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "note": { "type": "string", "maxLength": 10000 }, "status": { "type": "string", "enum": [ "open", "resolved" ] } }, "required": [ "revision" ] } } } }, "operationId": "patchProjectsProjectIdTracesTraceIdAnnotationsAnnotationId", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "eval:write" ] } }, "/projects/{projectId}/traces/compare": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/traces/compare", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdTracesCompare", "description": "POST /api/v1/projects/{projectId}/traces/compare on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the compare action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.compare", "x-caveman-operation-contract": "bb2b77facdd5d0f488560f6efd2e8151a69cfe285de8d88211fd0d70a81e008c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "baseline": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time", "description": "Earliest UTC start; current.to must be at most 90 days later." }, "to": { "type": "string", "format": "date-time" } } }, "current": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time", "description": "UTC end, after current.from and at most 90 days after baseline.from." } } }, "filters": { "type": "object", "additionalProperties": false, "properties": { "agent": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "workflow": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "model": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "provider": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "session_id": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "trace_id": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } } } } }, "required": [ "baseline", "current" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/usage/compare": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/usage/compare", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdUsageCompare", "description": "POST /api/v1/projects/{projectId}/usage/compare on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the compare_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.", "x-caveman-operation": "usage.compare", "x-caveman-operation-contract": "4e13b050cca844cc656f07b12d7b575b1d5469c533337e909c89302cc9230d19", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "baseline": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time", "description": "Earliest UTC start; current.to must be at most 90 days later." }, "to": { "type": "string", "format": "date-time" } } }, "current": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time", "description": "UTC end, after current.from and at most 90 days after baseline.from." } } }, "filters": { "type": "object", "additionalProperties": false, "properties": { "agent": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "workflow": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "model": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "provider": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "session_id": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } }, "trace_id": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 200 } } } } }, "required": [ "baseline", "current" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/projects/{projectId}/verdicts": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/verdicts", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdVerdicts", "description": "GET /api/v1/projects/{projectId}/verdicts on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list_verdicts action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "verdicts.list", "x-caveman-operation-contract": "9e3ff4f3bfde1111d21e121623b0e372606639824a037ecb04d986664492a8f8", "parameters": [ { "name": "workload_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "executor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "verdict", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "decision", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sha", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pr", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/verdicts/{source}/{runId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/verdicts/{source}/{runId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdVerdictsSourceRunId", "description": "GET /api/v1/projects/{projectId}/verdicts/{source}/{runId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get_verdict action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "verdicts.get", "x-caveman-operation-contract": "140fd675cec77f35c6792ba38da2dd4137e1a880e4e857bb37fb517676c7124b", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/verdicts/{source}/{runId}/cases": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/verdicts/{source}/{runId}/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" } }, "operationId": "getProjectsProjectIdVerdictsSourceRunIdCases", "description": "GET /api/v1/projects/{projectId}/verdicts/{source}/{runId}/cases on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the verdict_cases action of the caveman_quality tool (read access). Quality per workload: pass rates, issues, criteria and how far their judges are trusted, the setup Caveman proposes, judges and their calibration, CI suites, and verdicts with the cases that changed. Plan prices a comparison before anything runs. A criterion's trend reads its failure rate over time and across models from sampled live traffic; its comparisons are observed, not verified. The Review queue lists the units waiting for a person's label.", "x-caveman-operation": "verdicts.cases", "x-caveman-operation-contract": "2163442e343247ba5271c4c1d06ef68179131f978fb217bed75f3675fcc5caf2", "parameters": [ { "name": "order", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "include_same", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/projects/{projectId}/verdicts/{source}/{runId}/decision": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/verdicts/{source}/{runId}/decision", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdVerdictsSourceRunIdDecision", "description": "POST /api/v1/projects/{projectId}/verdicts/{source}/{runId}/decision on the Caveman Cloud control plane. Requires the experiment:approve_s3 scope. Not exposed to autonomous agents: Ship starts a rollout or a pull request, and Don't ship or Accept regression closes a comparison. Each is an audited human decision (ADR 0046).", "x-caveman-operation": "verdicts.decide", "x-caveman-operation-contract": "a9bb9ae042ce0e99e1ab44346e9492fedf18a23e750ad0ff1a7dc33be307bca4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "decision": { "enum": [ "ship", "dont_ship", "accept_regression" ] }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "decision" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } }, "/projects/{projectId}/wizard-sessions": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/wizard-sessions", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postProjectsProjectIdWizardSessions", "description": "POST /api/v1/projects/{projectId}/wizard-sessions on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the start action of the caveman_wizard_write tool (write access). Start, heartbeat and cancel the onboarding wizard session that `caveman onboard` runs. It reports progress only; it grants nothing and changes no setting.", "x-caveman-operation": "wizard.start", "x-caveman-operation-contract": "f9c5c474d035ff028bad0d9c86b2e1c7c8ddb6ebcc1b4b4fd1a8683cec2140b3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "client": { "enum": [ "claude", "codex", "cursor", "vscode", "windsurf", "gemini", "opencode" ] }, "repo_owner": { "type": "string" }, "repo_name": { "type": "string" }, "default_branch": { "type": "string" }, "head_sha": { "type": "string" } }, "required": [ "client" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/projects/{projectId}/wizard-sessions/{sessionId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/wizard-sessions/{sessionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getProjectsProjectIdWizardSessionsSessionId", "description": "GET /api/v1/projects/{projectId}/wizard-sessions/{sessionId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the get action of the caveman_wizard tool (read access). The project's onboarding wizard session: phase, tasks, the question waiting in the terminal, and the server's health reading (ok, not_started, lost_contact).", "x-caveman-operation": "wizard.get", "x-caveman-operation-contract": "cd10d013a3c42ed6257c03279621ffac611b764e622e58b252f9f23350f28848", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /projects/{projectId}/wizard-sessions/{sessionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchProjectsProjectIdWizardSessionsSessionId", "description": "PATCH /api/v1/projects/{projectId}/wizard-sessions/{sessionId} on the Caveman Cloud control plane. Requires the proposal:draft scope. Exposed to autonomous agents as the update action of the caveman_wizard_write tool (write access). Start, heartbeat and cancel the onboarding wizard session that `caveman onboard` runs. It reports progress only; it grants nothing and changes no setting.", "x-caveman-operation": "wizard.update", "x-caveman-operation-contract": "4cedaf4a6853bae83e964dd51a609540fda8d53adf7bd5e787fd93ced4185bef", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "phase": { "enum": [ "connecting", "planning", "awaiting_confirmation", "editing", "testing", "publishing", "completed", "failed", "cancelled" ] }, "tasks": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "label": { "type": "string", "maxLength": 80 }, "status": { "enum": [ "pending", "running", "done", "blocked", "failed" ] }, "detail": { "type": "string", "maxLength": 240 } }, "required": [ "id", "label", "status" ] } }, "pending_input": { "type": "string", "maxLength": 500 }, "branch": { "type": "string" }, "pr_url": { "type": "string", "pattern": "^(https://|$)" }, "error": { "type": "string", "maxLength": 500 } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft" ] } }, "/projects/{projectId}/wizard-sessions/{sessionId}/cancel": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /projects/{projectId}/wizard-sessions/{sessionId}/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" } }, "operationId": "postProjectsProjectIdWizardSessionsSessionIdCancel", "description": "POST /api/v1/projects/{projectId}/wizard-sessions/{sessionId}/cancel on the Caveman Cloud control plane. Requires any one of the scopes proposal:draft, settings:read. Exposed to autonomous agents as the cancel action of the caveman_wizard_write tool (write access). Start, heartbeat and cancel the onboarding wizard session that `caveman onboard` runs. It reports progress only; it grants nothing and changes no setting.", "x-caveman-operation": "wizard.cancel", "x-caveman-operation-contract": "c263a775029426c318c6ed9fa79a2fc3d04eda4853cddaa723d29b8d25468941", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "proposal:draft", "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "proposal:draft", "settings:read" ] } }, "/projects/{projectId}/wizard-sessions/current": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /projects/{projectId}/wizard-sessions/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" } }, "operationId": "getProjectsProjectIdWizardSessionsCurrent", "description": "GET /api/v1/projects/{projectId}/wizard-sessions/current on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the current action of the caveman_wizard tool (read access). The project's onboarding wizard session: phase, tasks, the question waiting in the terminal, and the server's health reading (ok, not_started, lost_contact).", "x-caveman-operation": "wizard.current", "x-caveman-operation-contract": "e4838bf423937853437f05bb543e3eae1cb1f4494e84bf72be3a352d74a60449", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "workflows.get", "x-caveman-operation-contract": "a4e95cdfad6b2245a7de1214c2da6e6f4498707d5a17b6200f6aa7701e71d6ef", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "workflows.update", "x-caveman-operation-contract": "aba819064e4f647b1752017a2bde7428971bff3aef0242d7dcf974ca016abb1f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "risk_level": { "type": "string" } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [] } }, "/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" } }, "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, their verdicts, the actions their rules fired, and an estimate of a monitor draft's volume and judge cost from recorded traffic.", "x-caveman-operation": "monitors.list", "x-caveman-operation-contract": "3ebd250bac1a97bca752e00a25f8154cec2531c83b4052652ad98ea6696ae18a", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "operationId": "postQualityMonitors", "description": "POST /api/v1/quality-monitors on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Quality monitors carry a caller-supplied grader egress URL that receives captured response payloads server-side. Creating or editing that target is human-only (ONBOARDING_V2_SPEC non-goal; caveman-cloud-project skill section 5).", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "operationId": "deleteQualityMonitorsMonitorId", "description": "DELETE /api/v1/quality-monitors/{monitorId} on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Quality monitors carry a caller-supplied grader egress URL that receives captured response payloads server-side. Creating or editing that target is human-only (ONBOARDING_V2_SPEC non-goal; caveman-cloud-project skill section 5).", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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, their verdicts, the actions their rules fired, and an estimate of a monitor draft's volume and judge cost from recorded traffic.", "x-caveman-operation": "monitors.get", "x-caveman-operation-contract": "1339c5e5524c1c3c8d4f57c1117d4d15a4d78d5748a924b1d96ed95ff9d3d59c", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "operationId": "putQualityMonitorsMonitorId", "description": "PUT /api/v1/quality-monitors/{monitorId} on the Caveman Cloud control plane. Requires the eval:write scope. Not exposed to autonomous agents: Quality monitors carry a caller-supplied grader egress URL that receives captured response payloads server-side. Creating or editing that target is human-only (ONBOARDING_V2_SPEC non-goal; caveman-cloud-project skill section 5).", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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, their verdicts, the actions their rules fired, and an estimate of a monitor draft's volume and judge cost from recorded traffic.", "x-caveman-operation": "monitors.results", "x-caveman-operation-contract": "8f5b0d89e138e575a292310f15f34256a75a6f6a07e4466568a1f6663890c56b", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Pause or resume existing quality monitors, and run a monitor of criteria over traces already recorded, inside its daily judge budget. Creating, replacing, and archiving monitors stays human-only because grader endpoints receive captured payloads.", "x-caveman-operation": "monitors.set_status", "x-caveman-operation-contract": "49d09f1fbb25440f348e3e0cb9a909bebe53f82d174f00f8cbe2329c16b85949", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status": { "enum": [ "draft", "active", "paused", "archived" ] } }, "required": [ "status" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "eval:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.agents", "x-caveman-operation-contract": "279b33432647de4f87ad630b995dfddf6123304eae7ff12f88b41a667f4ec2b3", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.cache", "x-caveman-operation-contract": "4ec319a544a98f9d3477fc80b8fffcd3983d76a1d24d1f506a22835fabf9484a", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "plan.score", "x-caveman-operation-contract": "f05c94e29c4aff4288498b47c486bb8aee2652bf99dca739f2d454684c7e6a83", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.compression", "x-caveman-operation-contract": "692f99ad8abf4be2bf2610bb8465e42d06a6544a7162116e9bca4552a8d276a1", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/costs": { "get": { "summary": "GET /reports/costs", "responses": { "200": { "description": "Window-scoped report with separate observed cache and inferred baseline-routing comparisons.", "content": { "application/json": { "schema": { "type": "object", "required": [ "automatic_savings", "verified_savings" ], "properties": { "automatic_savings": { "$ref": "#/components/schemas/AutomaticSavings" }, "verified_savings": { "type": "number", "description": "Existing signed provider-backed ledger total. Never includes inferred router or unattributed cache benefit." } }, "additionalProperties": true } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "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.", "x-caveman-operation": "reports.costs", "x-caveman-operation-contract": "bb1804f7bb5b51b1c21e955e8f7eea82a6d94de3cf8af36260d024db96d5a2ee", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/delivery": { "get": { "summary": "GET /reports/delivery", "responses": { "200": { "description": "Window-scoped delivery evidence. Costs exclude ambiguous joins and incomplete pricing; contribution details disclose truncation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryReport" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "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.", "x-caveman-operation": "people.delivery", "x-caveman-operation-contract": "77138675fe17092f08195684e24a003312d1fe5a664b4d4daf5c061f8debb3db", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "people.developers", "x-caveman-operation-contract": "62a9735be064cd9ca6ede64255b42c342ba4f73bb28e9b6be53d95d9f16e9fbc", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/digest": { "get": { "summary": "GET /reports/digest", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getReportsDigest", "description": "GET /api/v1/reports/digest on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the digest 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.", "x-caveman-operation": "people.digest", "x-caveman-operation-contract": "fbc08bf3239074c1e739d1f6a047550625e8539dbf69d559c9d9710245394609", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/external-spend": { "get": { "summary": "GET /reports/external-spend", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getReportsExternalSpend", "description": "GET /api/v1/reports/external-spend on the Caveman Cloud control plane. Requires the billing:read scope. Not exposed to autonomous agents: Provider-reported dollars behind billing:read. Keeping it human-only until an agent surface needs it; nothing here feeds savings claims.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.fleet", "x-caveman-operation-contract": "87a69a3144ec405da1a4a76c4174c7bdd5e718abaedaae64b8033be737ebd4b6", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "people.member_spend", "x-caveman-operation-contract": "97a0d077802c3ac8e832778515a066e3b3ef06a23621fdbf0f27b936b5ca1ef6", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.models", "x-caveman-operation-contract": "89433be943b77dbfd864914d6ec8e5b2bbd446d685d81a90029734f72ad65e08", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/overview": { "get": { "summary": "Overview metrics", "responses": { "200": { "description": "Window-scoped report with separate observed cache and inferred baseline-routing comparisons.", "content": { "application/json": { "schema": { "type": "object", "required": [ "automatic_savings", "verified_savings" ], "properties": { "automatic_savings": { "$ref": "#/components/schemas/AutomaticSavings" }, "verified_savings": { "type": "number", "description": "Existing signed provider-backed ledger total. Never includes inferred router or unattributed cache benefit." } }, "additionalProperties": true } } } }, "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "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.", "x-caveman-operation": "reports.overview", "x-caveman-operation-contract": "278697007295c3e31b2aa4d2a74481abee0731ccf8a66b3d9c3ec967627c63a0", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.routes", "x-caveman-operation-contract": "0b5860fcc9887b1257ad9de9081054dbd8324b80378b5b4631a24f26943bb992", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/reports/sessions": { "get": { "summary": "GET /reports/sessions", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getReportsSessions", "description": "GET /api/v1/reports/sessions on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the sessions 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.", "x-caveman-operation": "people.sessions", "x-caveman-operation-contract": "a3ae0766e75e384736da01a34022bcf8c8885560c95088908cbc348ce28b18ab", "parameters": [ { "name": "agent", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "member_user_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "snapshot", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "work_type", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /reports/sessions/{sessionId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getReportsSessionsSessionId", "description": "GET /api/v1/reports/sessions/{sessionId} on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the session 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.", "x-caveman-operation": "people.session", "x-caveman-operation-contract": "674de234f8148398c418598ede859cdc5f2858976ae0b95ed6462f03c01cd82e", "parameters": [ { "name": "agent", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "member_user_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "snapshot", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "work_type", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/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" } }, "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.", "x-caveman-operation": "people.spend_breakdown", "x-caveman-operation-contract": "0c7040cc0b0ec0f0ffe51a7239bab4927b0a715678f0a7bc0be73f4b0436c8cc", "parameters": [ { "name": "dimension", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/spend-flow": { "get": { "summary": "GET /reports/spend-flow", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getReportsSpendFlow", "description": "GET /api/v1/reports/spend-flow on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the spend_flow 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.", "x-caveman-operation": "reports.spend_flow", "x-caveman-operation-contract": "e959f939e79617c76fba22b096d86f7fed3616f6f7a5d441b554fc91d699af53", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "billing:read" ] } }, "/reports/statement": { "get": { "summary": "GET /reports/statement", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getReportsStatement", "description": "GET /api/v1/reports/statement on the Caveman Cloud control plane. Requires the billing:read scope. Exposed to autonomous agents as the statement 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.", "x-caveman-operation": "people.statement", "x-caveman-operation-contract": "e806f90135c8053ffb867d13d67547bbe16e2bdd67c5cb211e6f10b4447941e9", "parameters": [ { "name": "month", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^20[2-9][0-9]-(0[1-9]|1[0-2])$", "description": "A month that has ended, YYYY-MM from 2024-01." } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.traffic_shape", "x-caveman-operation-contract": "a7ae4f9530252efc44fd3c36623a764a196badb0305d1039b08827dd56cadc17", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.usage", "x-caveman-operation-contract": "80dd771507838feb0317b02972accc0de4ff4892aafbc6f5c2bc3eadbbf4d2cc", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.verified_savings", "x-caveman-operation-contract": "1bfc7e619225afd4182c5dea1bc1e88460fa0d9b890039102e3a272e204e8416", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "billing:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.why", "x-caveman-operation-contract": "c14ce7ac0769bb1782b32f98c58935313c7d6b775e113c1930cef213ce557d9e", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.workflows", "x-caveman-operation-contract": "098890b63e56bb48a7fb63d06212ee021ef0b278918b02f6fa7d4c813aa4b54c", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.workflow_detail", "x-caveman-operation-contract": "4a0b90fdbaa73822d09f4e07ace384bdb77f0efe274edeb22d19a0d4dac241dc", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "org:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "reports.wrap_savings", "x-caveman-operation-contract": "0b8642e907ff17fb97023b0ede8bd397027621fb6d0ad9d2d42017a737b20b6e", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/router-learning/project-retirements/{requestId}": { "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /router-learning/project-retirements/{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" } }, "operationId": "getRouterLearningProjectRetirementsRequestId", "description": "GET /api/v1/router-learning/project-retirements/{requestId} on the Caveman Cloud control plane. Requires the auditlog:read scope. Not exposed to autonomous agents: Reads the audit receipt of a project retirement from router learning. Audit-log state a human owner reviews, not project telemetry an agent needs.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "auditlog:read" ] } }, "/router-learning/subject-retirements": { "post": { "summary": "POST /router-learning/subject-retirements", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postRouterLearningSubjectRetirements", "description": "POST /api/v1/router-learning/subject-retirements on the Caveman Cloud control plane. Requires the member:manage scope. Not exposed to autonomous agents: Retiring a data subject from router learning is an org-admin privacy action (member:manage). An agent must not be able to erase or alter the learning record on anyone's behalf.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "member:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "member:manage" ] } }, "/router-learning/subject-retirements/{requestId}": { "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /router-learning/subject-retirements/{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" } }, "operationId": "getRouterLearningSubjectRetirementsRequestId", "description": "GET /api/v1/router-learning/subject-retirements/{requestId} on the Caveman Cloud control plane. Requires the auditlog:read scope. Not exposed to autonomous agents: Reads the audit receipt of a subject retirement. It is audit-log state a human owner reviews, not project telemetry an agent needs.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "auditlog:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "auditlog:read" ] } }, "/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" } }, "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). Project settings for the bound project: semantic-cache shadowing and its options, pixel density, routing previews. Optimizations themselves are chosen per request (x-cave-optimize, x-cave-cache), not switched on here. Changing the semantic-cache threshold or TTL is refused server-side unless the caller holds policy:publish_s2_s3, which a scoped agent connection does not.", "x-caveman-operation": "project_setup.preview_routing", "x-caveman-operation-contract": "445cf84674a905d172a987a151ea7dfb115fecd9c7fbf13147966413e27babfe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "endpoint": { "type": "string" }, "model_routing": { "type": "object", "additionalProperties": false, "properties": { "allow_cross_provider": { "type": "boolean" }, "alpha": { "type": "number" }, "baseline_models": { "type": "object", "additionalProperties": { "type": "string" } }, "candidate_allowlist": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "data_residency": { "type": "array", "items": { "type": "string" } }, "disable_cross_provider": { "type": "boolean" }, "max_cost_ratio": { "type": "number" }, "max_error_delta": { "type": "number" }, "max_p95_latency_delta_ms": { "type": "integer" }, "max_quality_delta": { "type": "number" }, "quality_floor": { "type": "number" }, "route_capacity": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "concurrent_requests": { "type": "integer" }, "input_tokens_per_minute": { "type": "integer" }, "output_tokens_per_minute": { "type": "integer" }, "requests_per_minute": { "type": "integer" } } } }, "route_denylist": { "type": "array", "items": { "type": "string" } }, "router_version": { "type": "string" } } }, "provider": { "type": "string" }, "task_profile": { "type": "object", "additionalProperties": false, "properties": { "alpha": { "type": "number" }, "candidate_allowlist": { "type": "array", "items": { "type": "string" } }, "candidate_denylist": { "type": "array", "items": { "type": "string" } }, "cross_provider": { "type": "boolean" }, "data_residency": { "type": "array", "items": { "type": "string" } }, "max_cost_ratio": { "type": "number" }, "max_error_delta": { "type": "number" }, "max_p95_latency_delta_ms": { "type": "integer" }, "quality_floor": { "type": "number" } } }, "workflow_slug": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" } }, "required": [ "project_id" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "policy:draft" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "policy:draft" ] } }, "/runtime/events": { "post": { "summary": "POST /runtime/events", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postRuntimeEvents", "description": "POST /api/v1/runtime/events on the Caveman Cloud control plane. Requires the key:self scope. Not exposed to autonomous agents: Client telemetry transport, not an MCP tool: a signed-in local runtime posts its own member's runtime/v1 events with the device-login session or the personal key it issued. It reads nothing and grants nothing.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "key:self" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "key:self" ] } }, "/scm/instances": { "get": { "summary": "GET /scm/instances", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getScmInstances", "description": "GET /api/v1/scm/instances on the Caveman Cloud control plane. Requires the repo:connect scope. Not exposed to autonomous agents: Lists installation-admitted SCM origins for the human connection ceremony.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "repo:connect" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "repo:connect" ] } }, "/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" } }, "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.", "x-caveman-operation": "findings.list", "x-caveman-operation-contract": "b1f637ed6f9865cc7a653627ec8740eadad9ae2fa83bc670d92119d9cb4090b8", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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). Dismiss or mark opportunities implemented, create an experiment from an opportunity, record outcomes, and submit practice findings. Legacy optimization proposal creation is retired.", "x-caveman-operation": "findings.create", "x-caveman-operation-contract": "f63a0eb0a8e4209e4ef2befe208f133499d5c6e07698a919fe53a7ef0a4a06d0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "caption": { "type": "string" }, "detector_family": { "type": "string" }, "params": { "type": "object", "additionalProperties": {} }, "project_id": { "type": "string", "format": "uuid" } }, "required": [ "detector_family", "caption", "params", "project_id" ] } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "opportunity:write" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "opportunity:write" ] } }, "/system/clickhouse-recovery-points": { "get": { "summary": "GET /system/clickhouse-recovery-points", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getSystemClickhouseRecoveryPoints", "description": "GET /api/v1/system/clickhouse-recovery-points on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] }, "post": { "summary": "POST /system/clickhouse-recovery-points", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postSystemClickhouseRecoveryPoints", "description": "POST /api/v1/system/clickhouse-recovery-points on the Caveman Cloud control plane. Operator plane: requires the platform admin token (Authorization: Bearer or x-cave-admin-token) from the private admin network. No customer credential reaches it. 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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "platform-admin", "security": [ { "platformAdminToken": [] } ] } }, "/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" } }, "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.", "x-caveman-operation": "context.provider_capabilities", "x-caveman-operation-contract": "1a0817382c3cfb39b716d5d6b81a85e85cbb9436eef87f3fcbeca5fc08d1ee7e", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "context.system_status", "x-caveman-operation-contract": "3611ff02f9de6100fadf30d5bdedea3c4bb8eb270e93d66a61fd5cb92abc7dc3", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "public-or-signed", "security": [] } }, "/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" } }, "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 LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.list", "x-caveman-operation-contract": "e597d3879638c3c03cfa1e8ba7d9aff6eded0b881c5f59980ce8261510d8dfa1", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "maxItems": 32 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "member_user_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workflow", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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 LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.get", "x-caveman-operation-contract": "ffab924cccd4888360cd2883fcfc5cc3efae0abf469f558f5b055a54a72443c0", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "operationId": "getTracesTraceIdPayloadsPayloadType", "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" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "payload:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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 LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.spans", "x-caveman-operation-contract": "d1392cef8dd2df5269a959ffdca6856a6076712f8fb8837e62acde5f4eea24a6", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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 LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.timeline", "x-caveman-operation-contract": "a24a6f96040239b1a113bac5869fd0f720d5b047e0fa1f29a612ea5bfb5b8196", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sample_data", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/scores": { "post": { "summary": "POST /traces/scores", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postTracesScores", "description": "POST /api/v1/traces/scores on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the scores action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.scores", "x-caveman-operation-contract": "8bb26c4288ba6efe6245746a16f8aef68ed33f8598c5d7c079ed34a70437524c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "trace_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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 LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.search", "x-caveman-operation-contract": "2381dd12892608efd19b59c954c2e50837c98e8b1d6ff4fb98d66438595cbfd5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date-time", "description": "UTC start of a window spanning at most 90 days. Left out, it is 24 hours before to." }, "to": { "type": "string", "format": "date-time", "description": "UTC end, after from and at most 90 days later. Left out, it is now." }, "filters": { "type": "object", "description": "Closed filter keys; an unknown key is refused with the supported list. `criterion`: {criterion_id, verdict} keeps traces whose latest Judgment on that criterion reads the verdict (passed, failed, not_applicable, inconclusive, error)." }, "group_by": { "type": "string" }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100 }, "sort": { "type": "object" }, "cursor": { "type": "object" }, "filter": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, { "type": "object", "additionalProperties": false, "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "all" ] }, { "type": "object", "additionalProperties": false, "properties": { "any": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "op": { "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "regex", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "rule": { "type": "string", "description": "Older name of op; matches_regex means regex. Send op or rule, never both." }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } ] } }, "required": [ "field" ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "minItems": 1 } }, "required": [ "any" ] } ] }, "maxItems": 32 } } } } } }, "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/views": { "get": { "summary": "GET /traces/views", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getTracesViews", "description": "GET /api/v1/traces/views on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the views action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.views", "x-caveman-operation-contract": "b27df65d7be4671d803c24c6b3a37376d2a1e284b8f9ce1f7676c0460c32c3d4", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "post": { "summary": "POST /traces/views", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postTracesViews", "description": "POST /api/v1/traces/views on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: A human decision on a saved view: created, renamed, shared or deleted with the actor in the audit trail.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/views/{viewId}": { "parameters": [ { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "DELETE /traces/views/{viewId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "deleteTracesViewsViewId", "description": "DELETE /api/v1/traces/views/{viewId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: A human decision on a saved view: created, renamed, shared or deleted with the actor in the audit trail.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] }, "patch": { "summary": "PATCH /traces/views/{viewId}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "patchTracesViewsViewId", "description": "PATCH /api/v1/traces/views/{viewId} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: A human decision on a saved view: created, renamed, shared or deleted with the actor in the audit trail.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/views/{viewId}/evaluate": { "parameters": [ { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /traces/views/{viewId}/evaluate", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postTracesViewsViewIdEvaluate", "description": "POST /api/v1/traces/views/{viewId}/evaluate on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Checks the view's alert and fires its webhook, if it has one, when the threshold is met; an outbound side effect a human triggers or the scheduler owns.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/views/{viewId}/share": { "parameters": [ { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "POST /traces/views/{viewId}/share", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postTracesViewsViewIdShare", "description": "POST /api/v1/traces/views/{viewId}/share on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Mints a read-only share link: data egress that needs a human actor in the audit trail.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "trace:read_metadata" ] } }, "/traces/views/shared/{shareToken}": { "parameters": [ { "name": "shareToken", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "GET /traces/views/shared/{shareToken}", "responses": { "2XX": { "description": "Successful response. Exact status depends on synchronous or durable delivery outcome." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getTracesViewsSharedShareToken", "description": "GET /api/v1/traces/views/shared/{shareToken} on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the shared_view action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.", "x-caveman-operation": "traces.shared_view", "x-caveman-operation-contract": "98ccd60257075b5e996ed6f74a7fbcb04eeeb4a00f7b5b41ab557a4fc5013f60", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "settings:read" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "provider:manage" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-operation": "workflows.list_fingerprints", "x-caveman-operation-contract": "bcce89b67d42100bfa3011fcf46d0f8184e99d3c8d0656de834d9942047412bc", "parameters": [], "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "trace:read_metadata" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "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" } }, "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.", "x-caveman-router-source": "cloud/control-api/internal/httpapi/server.go", "x-caveman-handler-guard": "rbac", "security": [ { "oauth2": [ "experiment:approve_s3" ] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-required-scopes": [ "experiment:approve_s3" ] } }, "/v1/route": { "post": { "servers": [ { "url": "https://gateway.caveman.so", "description": "Caveman hosted router" }, { "url": "/", "description": "Same-origin or self-hosted gateway" } ], "security": [ { "projectKey": [] } ], "x-caveman-router-source": "cloud/gateway-managed/internal/httpapi/proxy.go", "x-caveman-handler-guard": "project-api-key-scope", "x-caveman-required-project-scopes": [ "router:write" ], "responses": { "200": { "description": "Router decision or baseline-first fallback", "headers": { "x-ratelimit-limit-requests": { "description": "Requests per minute this call counted against: the key's own limit when tighter than the project's.", "schema": { "type": "integer" } }, "x-ratelimit-reset-requests": { "description": "Time until the minute window resets, as a duration (17s).", "schema": { "type": "string" } }, "x-ratelimit-limit-tokens": { "description": "The key's tokens per minute; only on a key with a token limit.", "schema": { "type": "integer" } }, "x-ratelimit-remaining-tokens": { "description": "Tokens left in the key's rolling minute before this call; only on a key with a token limit.", "schema": { "type": "integer" } }, "x-ratelimit-reset-tokens": { "description": "Time until the key's rolling minute is whole again, as a duration; only on a key with a token limit.", "schema": { "type": "string" } }, "x-cave-request-id": { "description": "This call's id, as its usage row and any error carry it.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandaloneRouteResponse" } } } }, "204": { "description": "Warm call (x-cave-warm: 1, route-warm-v1) answered, with no body. x-cave-edge-engine says whether the key's engine would answer its next ask now (warm), would send it to the core (cold), was still warming when the edge stopped waiting (timeout) or could not be reached (error); off where no edge is in front of the gateway, or while the edge is switched off.", "headers": { "x-cave-edge": { "description": "The Cloudflare location that answered; absent where no edge is in front.", "schema": { "type": "string" } }, "x-cave-edge-engine": { "required": true, "schema": { "type": "string", "enum": [ "warm", "cold", "timeout", "error", "off" ] } }, "server-timing": { "description": "The edge's time in ms: edge-engine (the engine call) and edge-front (the edge's own); on every /v1/route answer the edge makes, a forwarded one with the forward reason as desc. Never key or ask data.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Error", "description": "No valid project key. A warm call (route-warm-v1) without a key-shaped value gets this from the edge with no body; a gateway with no edge in front answers a warm call 204 off before reading the key." }, "429": { "$ref": "#/components/responses/Error", "description": "cave_rate_limit_exceeded (project), cave_key_rate_limit_exceeded or cave_key_tpm_exceeded (the key's own limits). Retry-After says when to retry." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postStandaloneRoute", "summary": "Choose one model from a caller-owned pool", "description": "Advisory one-call routing, decided in the gateway. Send exactly one of text, messages, signals or task; ask, request, last, state and parent_state go only beside signals, and task goes with models and pool alone. With request the route table decides model and effort for the request's class (main ask, continuation, compaction, auxiliary, subagent) and answers a state token for the session's next request; only a main ask the ask model or the work model read and a spawned subagent's first request are billed decisions. An ask with only the harness's own text (a task notification, a reminder, a continued session's summary) continues the current ask. Signals alone are decided by the signals rules and kept only as a count; text, messages and ask by the ask model, except that with routing.workType on (route-work-v1) an ask declaring no shell or edit tool is routed by its work type (reason ask_work). Valid requests return HTTP 200. When the ask model cannot answer, an ask beside signals is decided by the signals rules, which can still move it to a cheaper model on the same provider; text or messages keep the first caller model. Learning is separately gated to sampled, explicitly-consented Free-plan projects and a non-empty canonical x-cave-user-hash; routing works without that header but collects nothing. Optional session lineage is immediately converted to a tenant-bound HMAC and never stored raw.", "parameters": [ { "name": "x-cave-user-hash", "in": "header", "required": false, "description": "Opaque controller-supplied subject identifier used for data-subject access. Omit it to route without learning collection. Learning requires 1-128 valid UTF-8 bytes with no surrounding whitespace.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "x-cave-session", "in": "header", "required": false, "description": "Optional caller session identity for within-session learning joins. Accepted values use 1-128 ASCII letters, digits, dot, underscore, colon, or hyphen. Missing or invalid values never block routing and are never stored raw.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" } }, { "name": "x-cave-turn-index", "in": "header", "required": false, "description": "Optional zero-based turn paired with x-cave-session. Must be canonical unsigned 32-bit decimal with no whitespace or leading zeroes. Missing or invalid values never block routing; invalid lineage is omitted.", "schema": { "type": "integer", "minimum": 0, "maximum": 4294967295 } }, { "name": "x-cave-warm", "in": "header", "required": false, "description": "1 makes this a warm call (route-warm-v1), sent before a key's first ask and as a keep-alive: it readies the routing engine near the caller that this key's asks go to. Nothing is decided or billed and no body is read (send none). Answered 204 with x-cave-edge-engine; any other value is an ordinary request.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandaloneRouteRequest" } } } } } }, "/v1/route/outcomes": { "post": { "servers": [ { "url": "https://gateway.caveman.so", "description": "Caveman hosted router" }, { "url": "/", "description": "Same-origin or self-hosted gateway" } ], "security": [ { "projectKey": [] } ], "x-caveman-router-source": "cloud/gateway-managed/internal/httpapi/proxy.go", "x-caveman-handler-guard": "project-api-key-scope", "x-caveman-required-project-scopes": [ "router:write" ], "responses": { "202": { "description": "Outcome accepted; collected states whether a durable learning row was admitted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "accepted", "collected" ], "properties": { "accepted": { "const": true }, "collected": { "type": "boolean" }, "event_id": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postStandaloneRouteOutcome", "summary": "Submit a bounded outcome for one routed decision", "description": "Accepts only canonical low-trust outcome kinds under a signed tenant-bound token. Stale, revoked, paid-plan, sampled-out, or operator-disabled learning produces collected=false and no training row.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "outcome_token", "outcome_kind" ], "properties": { "outcome_token": { "type": "string", "minLength": 1, "maxLength": 2048 }, "outcome_kind": { "type": "string", "enum": [ "retry", "test_pass", "test_fail", "abandoned", "completed", "failed", "interrupted", "accepted", "rejected" ], "description": "A delegated task's outcome is completed, failed or interrupted, and a reviewer agent's verdict on it accepted or rejected." } } } } } } } }, "/v1/catalog": { "get": { "servers": [ { "url": "https://gateway.caveman.so", "description": "Caveman hosted gateway" }, { "url": "/", "description": "Same-origin or self-hosted gateway" } ], "security": [ { "projectKey": [] } ], "x-caveman-router-source": "cloud/gateway-managed/internal/httpapi/proxy.go", "x-caveman-handler-guard": "project-api-key-scope", "x-caveman-required-project-scopes": [ "router:write" ], "operationId": "getModelCatalog", "summary": "The live model catalog", "description": "Every model the installation knows, under one canonical id, with the hosts that serve it, the wires each host serves it on, capabilities, effort levels, limits, cache facts, prices per tier, review state and deprecation, each field with its source. Wire facts only: no routing scores or decision data. Updated automatically from models.dev, the LiteLLM map, provider model lists and the AWS price list under Caveman's reviewed facts. A host offering only Caveman's own provider accounts list is left out. A newly seen model is unreviewed: usable when a request names it, never substituted to until approved. Send the ETag back as If-None-Match to get 304 while the catalog is unchanged.", "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The catalog; the weak ETag is its revision", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCatalog" } } } }, "304": { "description": "Unchanged since the If-None-Match revision" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/trim": { "post": { "servers": [ { "url": "https://gateway.caveman.so", "description": "Caveman hosted gateway" }, { "url": "/", "description": "Same-origin or self-hosted gateway" } ], "security": [ { "projectKey": [] } ], "x-caveman-router-source": "cloud/gateway-managed/internal/httpapi/proxy.go", "x-caveman-handler-guard": "project-api-key-scope", "x-caveman-required-project-scopes": [ "sdk:write" ], "operationId": "postModelTrim", "summary": "Trim one payload to what a query needs (trim-1)", "description": "Compression of one payload: trim-1 keeps the lines of input the query needs, verbatim, and leaves out the rest under markers. Not compaction: it never reads a conversation. The answer is the output and token counts only. Metered per call and per token against the organization's monthly trim allowance.", "parameters": [ { "name": "x-cave-retention", "in": "header", "required": false, "description": "metadata or zdr narrows the project's retention for this call: the model runs in memory, nothing is stored and no recovery handle is returned. A call never widens the project's retention.", "schema": { "type": "string", "enum": [ "metadata", "zdr" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrimRequest" } } } }, "responses": { "200": { "description": "The trimmed payload", "headers": { "x-ratelimit-limit-requests": { "description": "Requests per minute this call counted against: the key's own limit when tighter than the project's.", "schema": { "type": "integer" } }, "x-ratelimit-reset-requests": { "description": "Time until the minute window resets, as a duration (17s).", "schema": { "type": "string" } }, "x-ratelimit-limit-tokens": { "description": "The key's tokens per minute; only on a key with a token limit.", "schema": { "type": "integer" } }, "x-ratelimit-remaining-tokens": { "description": "Tokens left in the key's rolling minute before this call; only on a key with a token limit.", "schema": { "type": "integer" } }, "x-ratelimit-reset-tokens": { "description": "Time until the key's rolling minute is whole again, as a duration; only on a key with a token limit.", "schema": { "type": "string" } }, "x-cave-request-id": { "description": "This call's id, as its usage row and any error carry it.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrimResponse" } } } }, "400": { "$ref": "#/components/responses/Error", "description": "cave_request_invalid: the body does not match the schema." }, "402": { "$ref": "#/components/responses/Error", "description": "cave_model_allowance_exhausted: the organization has used this product's monthly allowance; it renews when the next billing period starts." }, "413": { "$ref": "#/components/responses/Error", "description": "cave_request_too_large: the body is over the route's bound, or a history is over compact-1's size caps." }, "429": { "$ref": "#/components/responses/Error", "description": "cave_rate_limit_exceeded (project), cave_key_rate_limit_exceeded or cave_key_tpm_exceeded (the key's own limits). Retry-After says when to retry." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/compact": { "post": { "servers": [ { "url": "https://gateway.caveman.so", "description": "Caveman hosted gateway" }, { "url": "/", "description": "Same-origin or self-hosted gateway" } ], "security": [ { "projectKey": [] } ], "x-caveman-router-source": "cloud/gateway-managed/internal/httpapi/proxy.go", "x-caveman-handler-guard": "project-api-key-scope", "x-caveman-required-project-scopes": [ "sdk:write" ], "operationId": "postModelCompact", "summary": "Compact a whole agent history to a token budget (compact-1)", "description": "Compaction of a whole history: compact-1 returns the history to continue from within budget_tokens. Not compression of one payload: use /v1/trim for that. The answer is the history and token counts only. A history that already fits comes back as sent. Metered per call and per token against the organization's monthly compact allowance.", "parameters": [ { "name": "x-cave-retention", "in": "header", "required": false, "description": "metadata or zdr narrows the project's retention for this call: the model runs in memory, nothing is stored and no recovery handle is returned. A call never widens the project's retention.", "schema": { "type": "string", "enum": [ "metadata", "zdr" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompactRequest" } } } }, "responses": { "200": { "description": "The compacted history", "headers": { "x-ratelimit-limit-requests": { "description": "Requests per minute this call counted against: the key's own limit when tighter than the project's.", "schema": { "type": "integer" } }, "x-ratelimit-reset-requests": { "description": "Time until the minute window resets, as a duration (17s).", "schema": { "type": "string" } }, "x-ratelimit-limit-tokens": { "description": "The key's tokens per minute; only on a key with a token limit.", "schema": { "type": "integer" } }, "x-ratelimit-remaining-tokens": { "description": "Tokens left in the key's rolling minute before this call; only on a key with a token limit.", "schema": { "type": "integer" } }, "x-ratelimit-reset-tokens": { "description": "Time until the key's rolling minute is whole again, as a duration; only on a key with a token limit.", "schema": { "type": "string" } }, "x-cave-request-id": { "description": "This call's id, as its usage row and any error carry it.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompactResponse" } } } }, "400": { "$ref": "#/components/responses/Error", "description": "cave_request_invalid: the body does not match the schema." }, "402": { "$ref": "#/components/responses/Error", "description": "cave_model_allowance_exhausted: the organization has used this product's monthly allowance; it renews when the next billing period starts." }, "413": { "$ref": "#/components/responses/Error", "description": "cave_request_too_large: the body is over the route's bound, or a history is over compact-1's size caps." }, "422": { "$ref": "#/components/responses/Error", "description": "cave_compact_failed: compact-1 could not compact this history within budget_tokens." }, "429": { "$ref": "#/components/responses/Error", "description": "cave_rate_limit_exceeded (project), cave_key_rate_limit_exceeded or cave_key_tpm_exceeded (the key's own limits). Retry-After says when to retry." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/code/search": { "post": { "servers": [ { "url": "https://gateway.caveman.so", "description": "Caveman hosted gateway" }, { "url": "/", "description": "Same-origin or self-hosted gateway" } ], "security": [ { "projectKey": [] } ], "x-caveman-router-source": "cloud/gateway-managed/internal/httpapi/proxy.go", "x-caveman-handler-guard": "project-api-key-scope", "x-caveman-required-project-scopes": [ "proxy:write" ], "operationId": "postCodeSearch", "summary": "Search the web for the Caveman engine on Caveman Code credits", "description": "Web search for Caveman Code, paid from the organization's Caveman Code credits on the same meter as model tokens, at the provider's list price with no margin. Needs a Caveman Code credits key (POST /api/v1/code/credits/keys) and, for plan usage, x-caveman-client: caveman-code/. Brave LLM Context answers first; Perplexity Search answers when Brave fails and is configured. Each provider attempt reserves its price before the call, settles when the provider answers and is released at zero when it does not. The project's request guardrails screen the query and the domains first (a block refuses them; a mask may rewrite the query but never a domain) and its hard budgets hold each attempt's price. There is no idempotency key: every call is a new search with its own x-cave-request-id, so a retried request runs and is charged again; retry only after an answer says nothing ran (cave_code_search_unavailable, a credits or rate refusal, a 4xx). Nothing is cached or stored. Hosted Cloud only: a customer install has no credits keys.", "parameters": [ { "name": "x-caveman-client", "in": "header", "required": false, "description": "caveman-code/. Required in practice: web search is sold to the Caveman Code client only, so without it the credits ledger refuses with 403 cave_code_client_required.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "x-caveman-session", "in": "header", "required": false, "description": "Labels the ledger row with the caller's session; optional.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeSearchRequest" } } } }, "responses": { "200": { "description": "The search results, normalised across providers. Cache-Control: no-store.", "headers": { "x-cave-request-id": { "description": "This call's id, as its usage row and any error carry it.", "schema": { "type": "string" } }, "x-ratelimit-limit-requests": { "description": "Requests per minute this call counted against: the key's own limit when tighter than the project's.", "schema": { "type": "integer" } }, "x-ratelimit-reset-requests": { "description": "Time until the minute window resets, as a duration (17s).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeSearchResponse" } } } }, "400": { "$ref": "#/components/responses/Error", "description": "cave_request_invalid (the body breaks the schema; the message names the rule) or cave_guardrail_blocked (a project request guardrail refused the query or a domain, or a mask would have changed a domain; details name the rule)." }, "401": { "$ref": "#/components/responses/Error", "description": "cave_invalid_api_key, cave_api_key_blocked or cave_api_key_expired." }, "402": { "$ref": "#/components/responses/Error", "description": "cave_code_credits_exhausted: plan usage and credits cannot pay; details.reason (window_5h, window_week, month, platform, no_credits) and details.resets_at as on every credits request." }, "403": { "$ref": "#/components/responses/Error", "description": "cave_code_credits_key_required (not a credits key), cave_api_key_scope_required (no proxy:write), cave_code_client_required (no Caveman Code client header) or cave_license_admission_blocked." }, "413": { "$ref": "#/components/responses/Error", "description": "cave_request_too_large: the body is over 16 KiB." }, "429": { "$ref": "#/components/responses/Error", "description": "cave_code_rate_limited (the key's or organization's searches a minute, or the plan's rate or concurrency; details.reason rate_limited), cave_rate_limit_exceeded or cave_key_rate_limit_exceeded (project or key requests a minute), or cave_budget_exceeded (the project's or key's hard budget; x-cave-budget-scope names it). Retry-After says when to retry." }, "503": { "$ref": "#/components/responses/Error", "description": "cave_code_search_unavailable (no provider answered; nothing was charged; Retry-After), cave_code_search_not_configured (no provider key on this installation), cave_code_credits_unavailable (credits accounting did not answer; no provider was called) or cave_budget_unavailable (the hard budget counter did not answer)." }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } } }, "components": { "schemas": { "CodeFile": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "media_type", "size_bytes", "sha256", "purpose", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "One path segment; an input mounts at /mnt/session/uploads/." }, "media_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 0, "maximum": 104857600 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "purpose": { "enum": [ "input", "output" ], "description": "input: uploaded for sessions to read; output: a session wrote it under /mnt/session/outputs/." }, "session_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "path": { "type": "string", "description": "An output's path under /mnt/session/outputs/." }, "created_by_user_id": { "type": "string", "format": "uuid" }, "created_by_service_account_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "CodeFilePage": { "type": "object", "additionalProperties": false, "required": [ "files", "next_cursor" ], "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/CodeFile" } }, "next_cursor": { "type": [ "string", "null" ], "description": "The before= of the next page; null on the last." } } }, "CodeMemoryStore": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "description", "project_id", "memories", "size_bytes", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "memories": { "type": "integer", "minimum": 0 }, "size_bytes": { "type": "integer", "minimum": 0 }, "created_by_user_id": { "type": "string", "format": "uuid" }, "created_by_service_account_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CodeMemory": { "type": "object", "additionalProperties": false, "required": [ "path", "sha256", "size_bytes", "created_at", "updated_at" ], "properties": { "path": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "size_bytes": { "type": "integer", "minimum": 0, "maximum": 102400 }, "content": { "type": "string", "description": "The memory's text; on a single read or include_content=true." }, "updated_by_user_id": { "type": "string", "format": "uuid" }, "updated_by_service_account_id": { "type": "string", "format": "uuid" }, "updated_by_workspace_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CodeMemoryPage": { "type": "object", "additionalProperties": false, "required": [ "memories", "next_cursor" ], "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/CodeMemory" } }, "next_cursor": { "type": [ "string", "null" ], "description": "The after= of the next page; null on the last." } } }, "CodeMemoryVersion": { "type": "object", "additionalProperties": false, "required": [ "id", "path", "operation", "sha256", "size_bytes", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "operation": { "enum": [ "put", "delete" ] }, "sha256": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "size_bytes": { "type": "integer", "minimum": 0 }, "content": { "type": "string", "description": "The version's text; on a single version read of a put." }, "updated_by_user_id": { "type": "string", "format": "uuid" }, "updated_by_service_account_id": { "type": "string", "format": "uuid" }, "updated_by_workspace_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "OrganizationMembership": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "name", "slug", "role", "accepted" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "accepted": { "type": "boolean", "description": "False while the membership is an invitation the user has not accepted; switching to the organization accepts it." }, "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." } } }, "TraceAnnotation": { "type": "object", "required": [ "id", "organization_id", "project_id", "trace_id", "label", "note", "status", "revision", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "updated_by": { "type": "string", "format": "uuid" }, "trace_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "span_id": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "note": { "type": "string", "maxLength": 10000 }, "status": { "type": "string", "enum": [ "open", "resolved" ] }, "revision": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TraceAnnotationConflict": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "string", "const": "cave_trace_annotation_conflict" }, "message": { "type": "string" }, "details": { "type": "object", "required": [ "current" ], "properties": { "current": { "$ref": "#/components/schemas/TraceAnnotation" } } } } } } }, "CodeAutomationRevision": { "type": "object", "required": [ "id", "automation_id", "sha256", "commit_sha", "state", "source", "authority", "authority_diff", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "automation_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "commit_sha": { "type": "string" }, "state": { "enum": [ "active", "pending_approval", "superseded" ] }, "source": { "enum": [ "api", "push" ] }, "authority": { "type": "object", "additionalProperties": true, "description": "The authority-bearing keys Cloud read: host, on, triggers, outputs, output_config (where and how each output posts), engines, agents, secrets, mcp, budget." }, "authority_diff": { "type": "object", "description": "What a revision adds over the active one. widens: it waits for approval.", "additionalProperties": true, "required": [ "widens", "changes" ], "properties": { "widens": { "type": "boolean" }, "new": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "key", "change", "widens" ], "properties": { "key": { "type": "string" }, "change": { "enum": [ "added", "removed", "changed" ] }, "before": {}, "after": {}, "widens": { "type": "boolean" } } } } } }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by_service_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "approved_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "files": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The revision's files by path; on a single revision read." } } }, "CodeAutomation": { "type": "object", "required": [ "id", "repo", "path", "name", "host", "enabled", "trigger_kinds", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "repo": { "type": "string" }, "path": { "type": "string" }, "name": { "type": "string" }, "host": { "const": "cloud" }, "enabled": { "type": "boolean" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "service_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "active_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "trigger_kinds": { "type": "array", "items": { "enum": [ "github", "schedule", "webhook", "slack", "linear", "jira" ] } }, "hook_id": { "type": [ "string", "null" ] }, "removed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "active_revision": { "$ref": "#/components/schemas/CodeAutomationRevision" }, "pending_revision": { "$ref": "#/components/schemas/CodeAutomationRevision" }, "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/CodeAutomationRevision" } } } }, "CodeAutomationRun": { "type": "object", "required": [ "id", "automation_id", "revision_id", "trigger", "fire_slot", "subject", "status", "outcome", "cost_usd", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "automation_id": { "type": "string", "format": "uuid" }, "revision_id": { "type": "string", "format": "uuid" }, "trigger": { "type": "string", "description": "github., schedule, webhook, slack.app_mention, linear., jira. or manual." }, "event_id": { "type": "string" }, "fire_slot": { "type": "string" }, "subject": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": { "type": "string" } }, "triggered_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "enum": [ "queued", "running", "waiting", "succeeded", "failed", "cancelled", "skipped" ] }, "outcome": { "type": "string", "description": "The reason a terminal status carries: superseded, skipped_overlap, policy_denied, admission_refused, dispatch_failed, deadline, session_failed (the session failed and no run record came)." }, "cost_usd": { "type": "number", "minimum": 0 }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "requires_action": { "type": [ "object", "null" ], "description": "What a waiting run waits for: its session's last ask since it last ran. Null while running, or before the ask arrives.", "required": [ "ask_id", "kind", "step", "by" ], "properties": { "ask_id": { "type": "string" }, "kind": { "type": "string", "description": "approval for an approve: gate." }, "step": { "type": "string" }, "by": { "enum": [ "owner", "members" ] } } }, "recorded_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the run's record arrived (ADR 0134). An ended run that started a session and has none: cost_usd is unknown, not 0." }, "automation": { "type": "string", "description": "The automation's name; on the organization-wide list." }, "repo": { "type": "string" }, "pull_requests": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "state": { "enum": [ "open", "merged", "closed" ] } } } } } }, "CodeAutomationApplied": { "type": "object", "required": [ "id", "name", "state", "authority_diff" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "path": { "type": "string" }, "revision_id": { "type": "string" }, "state": { "enum": [ "active", "pending_approval", "unchanged", "removed" ] }, "authority_diff": { "type": "object", "description": "What a revision adds over the active one. widens: it waits for approval.", "additionalProperties": true, "required": [ "widens", "changes" ], "properties": { "widens": { "type": "boolean" }, "new": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "key", "change", "widens" ], "properties": { "key": { "type": "string" }, "change": { "enum": [ "added", "removed", "changed" ] }, "before": {}, "after": {}, "widens": { "type": "boolean" } } } } } }, "reason": { "type": "string", "description": "not_owner: the change widens nothing but waits, the applier does not answer for this automation." }, "hook": { "type": "object", "description": "The automation's signed hook, once, when its first webhook revision becomes active. Sign each request with X-Caveman-Signature: sha256= and name each event in X-Caveman-Delivery; without it, identical bodies that arrive in the same minute are one run.", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "secret": { "type": "string" } } } } }, "CodeAgentRef": { "type": "object", "additionalProperties": false, "required": [ "id", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } } }, "CodeSession": { "type": "object", "description": "A Caveman Code session: the session, the workspace it runs in and what started it.", "required": [ "id", "workspace_id", "origin", "status", "usage", "pull_requests", "created_at", "updated_at", "metadata" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "computer_id": { "type": [ "string", "null" ], "format": "uuid" }, "origin": { "enum": [ "person", "api", "automation" ] }, "service_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } } }, "repo": { "type": "string" }, "branch": { "type": "string" }, "engine": { "type": "string" }, "model": { "type": "string" }, "title": { "type": "string" }, "status": { "enum": [ "starting", "running", "requires_action", "idle", "terminated" ] }, "stop_reason": { "type": [ "string", "null" ], "enum": [ "end_turn", "requires_action", "budget_reached", "error", "interrupted", null ] }, "usage": { "type": "object", "additionalProperties": false, "required": [ "input_tokens", "output_tokens", "cache_read_tokens", "cost_usd", "cost_priced" ], "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_read_tokens": { "type": "integer" }, "cost_usd": { "type": "number", "description": "Measured: the sum of the calls that carried a cost." }, "cost_priced": { "type": "boolean", "description": "False once a call with tokens carried no cost (a subscription login, or a model with no price): cost_usd is then only the priced part." } } }, "pull_requests": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "url", "state" ], "properties": { "url": { "type": "string" }, "state": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "CodeSessionEvent": { "type": "object", "additionalProperties": false, "required": [ "seq", "type", "created_at", "data" ], "properties": { "seq": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true } } }, "CodeAgent": { "type": "object", "required": [ "id", "name", "version", "file_sha256", "summary", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "summary": { "type": "object", "additionalProperties": false, "required": [], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "engine": { "type": "string" }, "model": { "type": "string" } } }, "file_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "file": { "type": "string", "description": "The agent file's text; on a single read." }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by_service_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CodeAgentVersion": { "type": "object", "required": [ "agent_id", "version", "file_sha256", "summary", "created_at" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "summary": { "type": "object", "additionalProperties": false, "required": [], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "engine": { "type": "string" }, "model": { "type": "string" } } }, "file_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "file": { "type": "string", "description": "The agent file's text; on a single version read." }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by_service_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "CodeMail": { "type": "object", "description": "The mailbox message an event to a session became, delivered to the session's computer.", "required": [ "id", "verb", "authority", "channel", "wakes", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "verb": { "enum": [ "task", "interrupt", "answer" ] }, "authority": { "enum": [ "human", "api", "automation" ] }, "channel": { "type": "string" }, "to_workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "body": { "type": "string" }, "wakes": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "additionalProperties": true } } }, "CodeServiceAccount": { "type": "object", "required": [ "id", "project_id", "name", "active", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "active": { "type": "boolean", "description": "Enabled, and its owner is still a member who may run Caveman Code." } } }, "CodeBoardRow": { "type": "object", "required": [ "automation_id", "enabled", "removed", "runs", "succeeded", "failed", "cancelled", "skipped", "live", "last_run_at", "cost_usd", "unpriced_attempts", "unrecorded_runs", "cost_complete", "cost_per_merged_pull_request_floor_usd", "pull_requests_opened", "merged_pull_requests", "open_pull_requests", "closed_pull_requests", "cost_per_merged_pull_request_usd", "cycle_time_p50_seconds", "cycle_time_p90_seconds", "autonomous_merges", "autonomy_rate" ], "properties": { "automation_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "name": { "type": "string" }, "repo": { "type": "string" }, "enabled": { "type": "boolean" }, "removed": { "type": "boolean" }, "runs": { "type": "integer", "minimum": 0 }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "live": { "type": "integer", "minimum": 0 }, "last_run_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cost_usd": { "type": "number", "minimum": 0 }, "unpriced_attempts": { "type": "integer", "minimum": 0, "description": "Attempts on a subscription login: tokens, no per-token price, left out of cost_usd." }, "unrecorded_runs": { "type": "integer", "minimum": 0, "description": "Runs that ended after starting a session with no run record: their cost is unknown, so cost_usd is a floor." }, "cost_complete": { "type": "boolean", "description": "False while any run's cost is unknown (unrecorded_runs > 0)." }, "pull_requests_opened": { "type": "integer", "minimum": 0 }, "merged_pull_requests": { "type": "integer", "minimum": 0 }, "open_pull_requests": { "type": "integer", "minimum": 0 }, "closed_pull_requests": { "type": "integer", "minimum": 0 }, "cost_per_merged_pull_request_usd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Null with no merge, and null while cost_complete is false." }, "cost_per_merged_pull_request_floor_usd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "While cost_complete is false: the known cost per merge, a lower bound." }, "cycle_time_p50_seconds": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "cycle_time_p90_seconds": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "autonomous_merges": { "type": "integer", "minimum": 0, "description": "Merged with no push to the branch by a person." }, "autonomy_rate": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] } } }, "CodeAutomationsBoard": { "type": "object", "required": [ "from", "to", "days", "cost_label", "totals", "automations", "series", "failure_reasons" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "days": { "type": "integer", "minimum": 1, "maximum": 400 }, "cost_label": { "const": "measured" }, "totals": { "$ref": "#/components/schemas/CodeBoardRow" }, "automations": { "type": "array", "items": { "$ref": "#/components/schemas/CodeBoardRow" } }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "day", "runs", "succeeded", "failed", "cost_usd", "merged_pull_requests", "unrecorded_runs" ], "properties": { "day": { "type": "string", "format": "date" }, "runs": { "type": "integer", "minimum": 0 }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "cost_usd": { "type": "number", "minimum": 0 }, "merged_pull_requests": { "type": "integer", "minimum": 0 }, "unrecorded_runs": { "type": "integer", "minimum": 0 } } } }, "failure_reasons": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "status", "reason", "step", "runs" ], "properties": { "status": { "enum": [ "failed", "cancelled" ] }, "reason": { "type": "string" }, "step": { "type": "string" }, "runs": { "type": "integer", "minimum": 0 } } } } } }, "CodeStepModel": { "type": "object", "additionalProperties": false, "required": [ "step", "engine", "model_class", "model", "attempts", "succeeded", "failed", "checks_failed", "input_tokens", "output_tokens", "cost_usd", "duration_p50_ms" ], "properties": { "step": { "type": "string" }, "engine": { "type": "string" }, "model_class": { "type": "string" }, "model": { "type": "string" }, "attempts": { "type": "integer", "minimum": 0 }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "checks_failed": { "type": "integer", "minimum": 0 }, "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "cost_usd": { "type": "number", "minimum": 0 }, "duration_p50_ms": { "type": "integer", "minimum": 0 } } }, "CodePolicy": { "type": "object", "properties": { "allowed_engines": { "type": "array", "items": { "enum": [ "caveman", "claude-agent", "codex" ] }, "maxItems": 16 }, "allowed_models": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 64 }, "max_budget_usd": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "maximum": 1000000 }, "paused": { "type": "boolean", "description": "The kill switch: no session starts while it is on." }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_reason": { "type": "string", "maxLength": 500 }, "egress_default": { "enum": [ "install", "environment_only" ] }, "event_retention_days": { "type": "integer", "minimum": 1, "maximum": 400 }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ScenarioDocument": { "type": "object", "properties": { "schema_version": { "const": 1 }, "cases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "situation": { "type": "string" }, "persona": { "type": "string" }, "source": { "enum": [ "operator", "trace", "synthetic", "regression" ] }, "source_id": { "type": "string" }, "split": { "enum": [ "optimization", "holdout" ] }, "script": { "type": "array", "items": { "type": "string" } }, "fixtures": {}, "fixture_version": { "type": "string" }, "criteria": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "kind": { "enum": [ "tool_result", "fixture_state", "llm" ] }, "tool": { "type": "string" }, "path": { "type": "string" }, "equals": {} }, "required": [ "id", "description", "kind" ] } } }, "required": [ "id", "name", "situation", "source", "split", "script", "fixtures", "fixture_version", "criteria" ] }, "minItems": 1, "maxItems": 400 }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "connection_id": { "type": "string", "format": "uuid" }, "agent_version": { "type": "string" }, "policy_version": { "type": "string" }, "parameters": { "type": "object" } }, "required": [ "id", "name", "connection_id", "agent_version", "policy_version" ] }, "minItems": 1, "maxItems": 8 }, "mode": { "enum": [ "frozen", "adaptive" ] }, "trials": { "type": "integer", "minimum": 1, "maximum": 100 }, "max_turns": { "type": "integer", "minimum": 1, "maximum": 50 }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 600 }, "budget_micros": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "call_budget_micros": { "type": "integer", "minimum": 1 }, "simulator": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "version": { "type": "string" } }, "required": [ "provider", "model", "version" ] }, "judge": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "version": { "type": "string" } }, "required": [ "provider", "model", "version" ] }, "seed": { "type": "integer" } }, "required": [ "schema_version", "cases", "variants", "mode", "trials", "max_turns", "timeout_seconds", "budget_micros", "call_budget_micros" ] }, "ScenarioSuite": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "revision": { "type": "integer" }, "document": { "$ref": "#/components/schemas/ScenarioDocument" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "revision", "document", "updated_at" ] }, "ScenarioConnection": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "endpoint": { "type": "string", "format": "uri" }, "reset_endpoint": { "type": "string", "format": "uri" }, "environment": { "const": "sandbox" }, "revision": { "type": "integer" } }, "required": [ "id", "name", "endpoint", "reset_endpoint", "environment", "revision" ] }, "ScenarioTrial": { "type": "object", "properties": { "id": { "type": "string" }, "case_id": { "type": "string" }, "variant_id": { "type": "string" }, "repeat": { "type": "integer" }, "status": { "enum": [ "running", "passed", "failed", "inconclusive" ] }, "verdicts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "enum": [ "passed", "failed", "inconclusive" ] }, "reason": { "type": "string" } }, "required": [ "id", "status", "reason" ] } }, "reason": { "type": "string" }, "target_micros": { "type": "integer" }, "simulator_micros": { "type": "integer" }, "judge_micros": { "type": "integer" }, "cost_complete": { "type": "boolean" }, "attempts": { "type": "integer" }, "calls": { "type": "integer" }, "latency_ms": { "type": "integer" } }, "required": [ "id", "case_id", "variant_id", "repeat", "status", "verdicts", "reason", "target_micros", "simulator_micros", "judge_micros", "cost_complete", "attempts", "calls", "latency_ms" ] }, "ScenarioRun": { "type": "object", "properties": { "id": { "type": "string" }, "suite_id": { "type": "string" }, "suite_revision": { "type": "integer" }, "document": { "$ref": "#/components/schemas/ScenarioDocument" }, "document_sha256": { "type": "string" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "endpoint": { "type": "string", "format": "uri" }, "reset_endpoint": { "type": "string", "format": "uri" }, "environment": { "const": "sandbox" }, "revision": { "type": "integer" } }, "required": [ "id", "name", "endpoint", "reset_endpoint", "environment", "revision" ] } }, "engine_version": { "type": "string" }, "split": { "enum": [ "optimization", "holdout" ] }, "status": { "enum": [ "queued", "running", "completed", "cancelled", "interrupted", "error" ] }, "trials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "case_id": { "type": "string" }, "variant_id": { "type": "string" }, "repeat": { "type": "integer" }, "status": { "enum": [ "running", "passed", "failed", "inconclusive" ] }, "verdicts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "enum": [ "passed", "failed", "inconclusive" ] }, "reason": { "type": "string" } }, "required": [ "id", "status", "reason" ] } }, "reason": { "type": "string" }, "target_micros": { "type": "integer" }, "simulator_micros": { "type": "integer" }, "judge_micros": { "type": "integer" }, "cost_complete": { "type": "boolean" }, "attempts": { "type": "integer" }, "calls": { "type": "integer" }, "latency_ms": { "type": "integer" } }, "required": [ "id", "case_id", "variant_id", "repeat", "status", "verdicts", "reason", "target_micros", "simulator_micros", "judge_micros", "cost_complete", "attempts", "calls", "latency_ms" ] } }, "summary": { "type": "object", "additionalProperties": { "type": "object", "properties": { "trials": { "type": "integer" }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "inconclusive": { "type": "integer" }, "target_micros": { "type": "integer" }, "simulator_micros": { "type": "integer" }, "judge_micros": { "type": "integer" }, "cost_complete": { "type": "boolean" }, "cost_per_success_micros": { "type": [ "number", "null" ] }, "retries": { "type": "integer" }, "mean_latency_ms": { "type": "number" } }, "required": [ "trials", "passed", "failed", "inconclusive", "target_micros", "simulator_micros", "judge_micros", "cost_complete", "cost_per_success_micros", "retries", "mean_latency_ms" ] } }, "gate": {}, "created_at": { "type": "string", "format": "date-time" }, "evidence_basis": { "const": "simulation" } }, "required": [ "id", "suite_id", "suite_revision", "document", "document_sha256", "connections", "engine_version", "split", "status", "trials", "summary", "gate", "created_at", "evidence_basis" ] }, "ScenarioGate": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "evidence_basis": { "const": "simulation" }, "outcome": { "enum": [ "ship", "pass", "worse", "not_cheaper", "need_more_data", "underpowered" ] }, "needs_cases": { "type": "integer", "minimum": 0 }, "needs_more_cases": { "type": "integer", "minimum": 0 } }, "required": [ "eligible", "reasons", "evidence_basis" ] }, "ScenarioEvent": { "type": "object", "properties": { "id": { "type": "integer" }, "trial_id": { "type": "string" }, "kind": { "type": "string" }, "role": { "type": "string" }, "body": {}, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "trial_id", "kind", "role", "body", "created_at" ] }, "ScenarioSandboxObservation": { "type": "object", "properties": { "message": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "call_id": { "type": "string" }, "success": { "type": "boolean" }, "result": {} }, "required": [ "name", "call_id", "success", "result" ] } }, "state": {}, "cost_micros": { "type": "integer", "minimum": 0 }, "attempts": { "type": "integer", "minimum": 1 }, "agent_version": { "type": "string" }, "policy_version": { "type": "string" }, "trace_id": { "type": "string" } }, "required": [ "message", "cost_micros", "attempts", "agent_version", "policy_version" ] }, "WorkClassification": { "type": "object", "required": [ "key", "source", "version", "branch_type", "title_type" ], "properties": { "key": { "type": "string", "enum": [ "feat", "fix", "refactor", "perf", "test", "docs", "chore", "build", "other" ] }, "source": { "type": "string", "enum": [ "unknown", "conflict", "branch", "title", "branch_and_title" ] }, "version": { "type": "string", "const": "work-v2" }, "branch_type": { "type": "string" }, "title_type": { "type": "string" } } }, "DeliveryContribution": { "type": "object", "required": [ "member_user_id", "name", "email", "agent_slug", "model", "requests", "priced_requests", "cost_usd" ], "properties": { "member_user_id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "agent_slug": { "type": "string" }, "model": { "type": "string" }, "requests": { "type": "integer", "minimum": 0 }, "priced_requests": { "type": "integer", "minimum": 0 }, "cost_usd": { "type": "number", "minimum": 0 } } }, "DeliveryPR": { "type": "object", "required": [ "project_id", "repo", "title", "branch", "author_login", "work_type", "merged_at", "number", "additions", "deletions", "changed_files", "sessions", "requests", "attributed", "cost_usd", "optimizers", "classification", "attribution_status", "evidence", "evidence_truncated" ], "properties": { "project_id": { "type": "string" }, "repo": { "type": "string" }, "title": { "type": "string" }, "branch": { "type": "string" }, "base_branch": { "type": "string" }, "author_login": { "type": "string" }, "work_type": { "type": "string" }, "merged_at": { "type": "string" }, "opened_at": { "type": "string" }, "number": { "type": "integer", "minimum": 0 }, "additions": { "type": "integer", "minimum": 0 }, "deletions": { "type": "integer", "minimum": 0 }, "changed_files": { "type": "integer", "minimum": 0 }, "sessions": { "type": "integer", "minimum": 0 }, "requests": { "type": "integer", "minimum": 0 }, "head_sha": { "type": "string", "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$" }, "base_sha": { "type": "string", "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$" }, "merge_commit_sha": { "type": "string", "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$" }, "commit_count": { "type": "integer", "minimum": 0 }, "attributed": { "type": "boolean" }, "cost_usd": { "type": "number", "minimum": 0 }, "optimizers": { "type": "array", "items": { "type": "string" } }, "classification": { "$ref": "#/components/schemas/WorkClassification" }, "attribution_status": { "type": "string", "enum": [ "linked", "missing_context", "reused_branch", "traffic_after_merge", "incomplete_pricing", "report_truncated" ] }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryContribution" } }, "evidence_truncated": { "type": "boolean" } } }, "DeliveryTotals": { "type": "object", "required": [ "merged_prs", "attributed_prs", "unlanded_branches", "unlanded_sessions", "in_flight_branches", "in_flight_sessions", "session_linked_requests", "branch_tagged_requests", "cost_to_merge_usd", "unlanded_cost_usd", "in_flight_cost_usd", "branch_tagged_cost_usd", "untagged_cost_usd", "unresolved_cost_usd", "coverage", "median_cost_usd", "p90_cost_usd", "median_sessions" ], "properties": { "merged_prs": { "type": "integer", "minimum": 0 }, "attributed_prs": { "type": "integer", "minimum": 0 }, "unlanded_branches": { "type": "integer", "minimum": 0 }, "unlanded_sessions": { "type": "integer", "minimum": 0 }, "in_flight_branches": { "type": "integer", "minimum": 0 }, "in_flight_sessions": { "type": "integer", "minimum": 0 }, "session_linked_requests": { "type": "integer", "minimum": 0 }, "branch_tagged_requests": { "type": "integer", "minimum": 0 }, "cost_to_merge_usd": { "type": "number", "minimum": 0 }, "unlanded_cost_usd": { "type": "number", "minimum": 0 }, "in_flight_cost_usd": { "type": "number", "minimum": 0 }, "branch_tagged_cost_usd": { "type": "number", "minimum": 0 }, "untagged_cost_usd": { "type": "number", "minimum": 0 }, "unresolved_cost_usd": { "type": "number", "minimum": 0 }, "coverage": { "type": "number", "minimum": 0 }, "median_cost_usd": { "type": [ "number", "null" ], "minimum": 0 }, "p90_cost_usd": { "type": [ "number", "null" ], "minimum": 0 }, "median_sessions": { "type": [ "number", "null" ], "minimum": 0 } } }, "DeliveryWorkType": { "type": "object", "required": [ "key", "label", "merged_prs", "attributed_prs", "total_cost_usd", "median_cost_usd", "median_changed_files" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "merged_prs": { "type": "integer", "minimum": 0 }, "attributed_prs": { "type": "integer", "minimum": 0 }, "total_cost_usd": { "type": "number", "minimum": 0 }, "median_cost_usd": { "type": [ "number", "null" ], "minimum": 0 }, "median_changed_files": { "type": [ "number", "null" ], "minimum": 0 } } }, "DeliveryRepo": { "type": "object", "required": [ "repo", "merged_prs", "attributed_prs", "total_cost_usd", "median_cost_usd" ], "properties": { "repo": { "type": "string" }, "merged_prs": { "type": "integer", "minimum": 0 }, "attributed_prs": { "type": "integer", "minimum": 0 }, "total_cost_usd": { "type": "number", "minimum": 0 }, "median_cost_usd": { "type": [ "number", "null" ], "minimum": 0 } } }, "DeliveryUnlanded": { "type": "object", "required": [ "project_id", "repo", "branch", "last_seen", "sessions", "requests", "cost_usd" ], "properties": { "project_id": { "type": "string" }, "repo": { "type": "string" }, "branch": { "type": "string" }, "last_seen": { "type": "string" }, "sessions": { "type": "integer", "minimum": 0 }, "requests": { "type": "integer", "minimum": 0 }, "cost_usd": { "type": "number", "minimum": 0 } } }, "DeliveryOptimizerEffect": { "type": "object", "required": [ "optimizer_id", "with_prs", "without_prs", "mixed_prs", "with_median_usd", "without_median_usd", "comparable" ], "properties": { "optimizer_id": { "type": "string" }, "with_prs": { "type": "integer", "minimum": 0 }, "without_prs": { "type": "integer", "minimum": 0 }, "mixed_prs": { "type": "integer", "minimum": 0 }, "with_median_usd": { "type": [ "number", "null" ], "minimum": 0 }, "without_median_usd": { "type": [ "number", "null" ], "minimum": 0 }, "comparable": { "type": "boolean" } } }, "DeliveryReport": { "type": "object", "required": [ "window", "scope", "connected", "repos", "basis", "totals", "by_work_type", "by_repo", "prs", "unlanded", "optimizer_effects", "truncated", "basis_notes" ], "properties": { "window": { "type": "string" }, "scope": { "type": "string", "enum": [ "organization", "self" ] }, "connected": { "type": "boolean" }, "repos": { "type": "array", "items": { "type": "string" } }, "basis": { "type": "string", "const": "branch_tag" }, "totals": { "$ref": "#/components/schemas/DeliveryTotals" }, "by_work_type": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryWorkType" } }, "by_repo": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryRepo" } }, "prs": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryPR" } }, "unlanded": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryUnlanded" } }, "optimizer_effects": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryOptimizerEffect" } }, "truncated": { "type": "boolean" }, "basis_notes": { "type": "object", "required": [ "join", "cost", "optimizer", "attribution" ], "properties": { "join": { "type": "string" }, "cost": { "type": "string" }, "optimizer": { "type": "string" }, "attribution": { "type": "string" } } } } }, "FactoryAllowance": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "policy_revision": { "type": "integer", "minimum": 1 }, "limit_micros": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact integer micro amount." }, "spent_micros": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact integer micro amount." }, "reserved_micros": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact integer micro amount." }, "held_micros": { "type": "string", "pattern": "^[0-9]+$", "description": "Unknown paid outcomes included in reserved_micros, never added twice." }, "remaining_micros": { "type": "string", "pattern": "^[0-9]+$", "description": "Shared allowance remaining after spend and reservations; organization, project, repository and case ceilings still apply independently." }, "approved_by": { "type": "string", "format": "uuid" }, "approved_at": { "type": "string", "format": "date-time" }, "basis": { "enum": [ "attempt_budget_rows_and_gateway_case_keys", "attempt_budget_rows" ], "description": "attempt_budget_rows_and_gateway_case_keys: the attempt budget row plus the gateway's spend on the factory keys of every case of the attempt. attempt_budget_rows: the row alone, when the gateway could not be read." } }, "required": [ "id", "policy_revision", "limit_micros", "spent_micros", "reserved_micros", "held_micros", "remaining_micros", "approved_by", "approved_at", "basis" ] }, "FactoryPolicy": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "goal": { "type": "string", "minLength": 1, "maxLength": 2000 }, "change_class": { "const": "application-source" }, "case_budget_micros": { "type": "string", "pattern": "^([1-9][0-9]{0,11}|1000000000000)$", "description": "Per-case cap. Initial approval also sets the shared allowance. Later edits retain its original amount; new_attempt explicitly approves an additional allowance." }, "publication_policy": { "enum": [ "evaluated-draft-only", "none" ] }, "test_connections": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "model_connection_ref": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "paused": { "type": "boolean", "description": "Stops new case admissions. Already-admitted cases retain their original authority until cancelled or otherwise fenced." }, "approved_by": { "type": "string", "format": "uuid" }, "approved_at": { "type": "string", "format": "date-time" }, "scope_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "allowance": { "oneOf": [ { "$ref": "#/components/schemas/FactoryAllowance" }, { "type": "null" } ] } }, "required": [ "revision", "goal", "change_class", "case_budget_micros", "publication_policy", "test_connections", "model_connection_ref", "paused", "approved_by", "approved_at", "scope_digest", "allowance" ] }, "FactoryPolicyConfiguration": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "goal": { "type": "string", "minLength": 1, "maxLength": 2000 }, "change_class": { "const": "application-source" }, "case_budget_micros": { "type": "string", "pattern": "^([1-9][0-9]{0,11}|1000000000000)$", "description": "Per-case cap. Initial approval also sets the shared allowance. Later edits retain its original amount; new_attempt explicitly approves an additional allowance." }, "publication_policy": { "enum": [ "evaluated-draft-only", "none" ] }, "test_connections": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "model_connection_ref": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "paused": { "type": "boolean", "description": "Stops new case admissions. Already-admitted cases retain their original authority until cancelled or otherwise fenced." }, "new_attempt": { "type": "boolean", "default": false, "description": "Explicitly approves a new additional allowance. Identical retries using the original expected_revision return the same new approval; changed content conflicts. Ordinary edits reuse the existing allowance." } }, "required": [ "expected_revision", "goal", "change_class", "case_budget_micros", "publication_policy" ] }, "FactoryPolicyResponse": { "type": "object", "additionalProperties": false, "properties": { "policy": { "oneOf": [ { "$ref": "#/components/schemas/FactoryPolicy" }, { "type": "null" } ] }, "latest_revision": { "type": "integer", "minimum": 0 } }, "required": [ "policy", "latest_revision" ] }, "FactoryCaseSpend": { "type": "object", "additionalProperties": false, "properties": { "spent_micros": { "type": "integer", "minimum": 0 }, "reserved_micros": { "type": "integer", "minimum": 0 }, "held_micros": { "type": "integer", "minimum": 0 }, "limit_micros": { "type": [ "integer", "null" ], "minimum": 0 }, "basis": { "enum": [ "case_budget_rows_and_gateway_case_keys", "case_budget_rows" ], "description": "case_budget_rows_and_gateway_case_keys: the case budget row plus the gateway's spend on the case's factory keys. case_budget_rows: the row alone (no role run or case key, or the gateway could not be read)." } }, "required": [ "spent_micros", "reserved_micros", "held_micros", "limit_micros", "basis" ] }, "FactoryCaseAuthorization": { "type": "object", "additionalProperties": false, "properties": { "remaining_micros": { "type": [ "integer", "null" ], "minimum": 0 }, "revoked": { "type": "boolean", "description": "Case closure/cancellation fence, separate from a pause on new admissions." }, "stale_policy": { "type": "boolean" }, "new_admissions_paused": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "remaining_micros", "revoked", "stale_policy", "new_admissions_paused", "expires_at" ] }, "FactoryCaseAllowanceProjection": { "type": "object", "additionalProperties": true, "description": "Shared-allowance and case-spend fields of the full factory case. Additional setup, execution, evidence and publication fields retain their existing contracts. A null allowance means historical per-case authorization, not a fresh zero-spend allowance.", "required": [ "id", "agent_id", "work_kind", "allowance", "spend", "authorization" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "work_kind": { "enum": [ "setup", "improvement" ] }, "allowance": { "oneOf": [ { "$ref": "#/components/schemas/FactoryAllowance" }, { "type": "null" } ] }, "spend": { "$ref": "#/components/schemas/FactoryCaseSpend" }, "authorization": { "$ref": "#/components/schemas/FactoryCaseAuthorization" } } }, "AgentDeploymentRegistration": { "type": "object", "additionalProperties": false, "properties": { "deployment_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "binding_id": { "type": "string", "format": "uuid" }, "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "image_sha256": { "type": "string", "pattern": "^([a-f0-9]{64})?$" }, "config_sha256": { "type": "string", "pattern": "^([a-f0-9]{64})?$" } }, "required": [ "deployment_id", "binding_id", "commit_sha" ] }, "AgentDeployment": { "type": "object", "additionalProperties": false, "properties": { "deployment_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "binding_id": { "type": "string", "format": "uuid" }, "repository_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "image_sha256": { "type": "string", "pattern": "^([a-f0-9]{64})?$" }, "config_sha256": { "type": "string", "pattern": "^([a-f0-9]{64})?$" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "deployment_id", "binding_id", "repository_id", "commit_sha", "image_sha256", "config_sha256", "created_at" ] }, "AgentTaskScenario": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "const": 1 }, "adapter": { "enum": [ "python-module-task-v1", "node-module-task-v1" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "invariant": { "type": "string", "minLength": 1, "maxLength": 4000 }, "entrypoint": { "type": "string", "maxLength": 200, "pattern": "^([A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*:[A-Za-z_][A-Za-z0-9_]*|(\\.caveman/adapters/)?[A-Za-z0-9_][A-Za-z0-9_./-]*\\.(js|mjs|ts):[A-Za-z_$][A-Za-z0-9_$]*)$" }, "input": {}, "initial_state": { "type": "object" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "arguments": {}, "result": {}, "error": { "type": "string", "maxLength": 500 } }, "required": [ "name", "arguments", "result" ] }, "minItems": 0, "maxItems": 100 }, "read_only_tools": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 0, "maxItems": 100, "uniqueItems": true, "description": "Declared tool names whose calls change nothing: a trial may make them in another order between two other calls, and skip one whose answer did not change since the same call was last made." }, "assertions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "subject": { "enum": [ "output", "state" ] }, "pointer": { "type": "string", "maxLength": 1000 }, "operator": { "enum": [ "equals", "contains", "not_contains" ] }, "value": {} }, "required": [ "subject", "pointer", "operator", "value" ], "allOf": [ { "if": { "properties": { "operator": { "enum": [ "contains", "not_contains" ] } } }, "then": { "properties": { "value": { "type": "string", "minLength": 1 } } } } ] }, "minItems": 1, "maxItems": 100 }, "expected_failure": { "type": "object", "additionalProperties": false, "properties": { "exception_type": { "type": "string", "minLength": 1, "maxLength": 200 }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "function": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "exception_type", "path", "function" ] }, "historical": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "expected": { "enum": [ "passed", "failed" ] } }, "required": [ "commit_sha", "expected" ] }, "minItems": 0, "maxItems": 20 }, "provenance": { "type": "object", "additionalProperties": false, "properties": { "evidence_digests": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "fixture_basis": { "const": "synthetic" }, "fixture_rationale": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "evidence_digests", "fixture_basis", "fixture_rationale" ] } }, "required": [ "schema_version", "adapter", "name", "invariant", "entrypoint", "input", "initial_state", "tools", "assertions", "historical", "provenance" ] }, "AgentTaskScenarioVersion": { "type": "object", "additionalProperties": false, "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "definition": { "$ref": "#/components/schemas/AgentTaskScenario" }, "scenario_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "source_run_id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "execution_status": { "enum": [ "not_executed", "queued", "running", "completed", "failed", "cancelled" ] }, "executions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "run_id": { "type": "string", "format": "uuid" }, "workbench_id": { "type": "string", "format": "uuid" }, "native_run_id": { "type": "string", "format": "uuid" }, "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "status": { "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "assessment": {}, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "run_id", "workbench_id", "native_run_id", "commit_sha", "status", "assessment", "created_at" ] }, "minItems": 0, "maxItems": 20 } }, "required": [ "dataset_id", "version_id", "version", "definition", "scenario_sha256", "execution_status", "executions" ] }, "EvaluatorQualificationSetConfiguration": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "invariant": { "type": "string", "minLength": 1, "maxLength": 4000 }, "grader_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "subject_column": { "type": "string", "minLength": 1, "maxLength": 96 }, "label_column": { "type": "string", "minLength": 1, "maxLength": 96 }, "identity_column": { "type": "string", "minLength": 1, "maxLength": 96 }, "challenge_version_id": { "type": "string", "format": "uuid" }, "population_version_id": { "type": "string", "format": "uuid" }, "sampling_method": { "enum": [ "random", "systematic", "complete_population" ] }, "population_definition": { "type": "string", "minLength": 1, "maxLength": 4000 }, "label_provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "agent_id": { "type": [ "string", "null" ], "format": "uuid" }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "name", "invariant", "grader_type", "subject_column", "label_column", "identity_column", "challenge_version_id", "population_version_id", "sampling_method", "population_definition", "label_provenance" ] }, "EvaluatorQualificationRequest": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 }, "set_id": { "type": "string", "format": "uuid" } }, "required": [ "version", "set_id" ] }, "EvaluatorQualification": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "evaluator_version_id": { "type": "string", "format": "uuid" }, "set_id": { "type": "string", "format": "uuid" }, "challenge_run_id": { "type": "string", "format": "uuid" }, "population_run_id": { "type": "string", "format": "uuid" }, "config_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "status": { "enum": [ "pending", "qualified", "failed", "unavailable" ] }, "activation_status": { "enum": [ "not_requested", "pending", "active", "unavailable" ] }, "result": { "type": "object", "description": "Measured independent challenge and representative-population outcomes. No invented labels or synthetic deployment precision." }, "source_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "evaluator_version_id", "set_id", "challenge_run_id", "population_run_id", "config_sha256", "status", "activation_status", "result", "source_run_id", "created_at", "completed_at" ] }, "AgentRunSummary": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "definition_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "definition_version": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "enum": [ "queued", "running", "completed", "incomplete", "cancelled", "stale" ] }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time" }, "model": { "type": "string", "description": "The model the run was admitted on (provider/model); absent when the run stamped none (Factory and Sentinel stages)." } }, "required": [ "id", "case_id", "definition_id", "definition_version", "status", "reason", "created_at", "deadline" ] }, "AgentCase": { "type": "object", "additionalProperties": false, "properties": { "case_id": { "type": "string", "format": "uuid" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "definition_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "definition_version": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "enum": [ "queued", "running", "completed", "incomplete", "cancelled", "stale" ] }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time" }, "chat_turn": { "type": "boolean", "description": "True only for a chat turn owned by the current user." }, "spent_micros": { "type": "integer", "minimum": 0 }, "reserved_micros": { "type": "integer", "minimum": 0 } }, "required": [ "id", "case_id", "definition_id", "definition_version", "status", "reason", "created_at", "deadline", "chat_turn", "spent_micros", "reserved_micros" ] }, "minItems": 0, "maxItems": 100 } }, "required": [ "case_id", "data" ] }, "AgentSentinelPage": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "definition_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "definition_version": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "enum": [ "queued", "running", "completed", "incomplete", "cancelled", "stale" ] }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time" }, "origin": { "type": "string" }, "findings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "qualification_state": { "enum": [ "qualified", "refuted", "unproven" ] }, "evidence_class": { "const": "static_review" }, "qualification_reason": { "type": "string" }, "repair_state": { "type": "string" }, "publication_state": { "type": "string" } }, "required": [ "id", "qualification_state", "evidence_class", "qualification_reason", "repair_state", "publication_state" ] }, "minItems": 0, "maxItems": 5 }, "publication_state": { "type": "string" }, "publication_reason": { "type": "string" }, "publication_lifecycle": { "type": "string", "description": "What the customer did with the draft pull request, as last observed on the repository: draft, open, merged or closed. Empty before the first observation." }, "chat_turn": { "const": false }, "spent_micros": { "type": "integer", "minimum": 0 }, "reserved_micros": { "type": "integer", "minimum": 0 } }, "required": [ "id", "case_id", "definition_id", "definition_version", "status", "reason", "created_at", "deadline", "origin", "findings", "publication_state", "publication_reason", "publication_lifecycle", "chat_turn", "spent_micros", "reserved_micros" ] }, "minItems": 0, "maxItems": 50 }, "next_cursor": { "type": "string" }, "merged_fixes": { "type": "integer", "minimum": 0, "description": "Repair draft pull requests of this project observed merged." }, "closed_fixes": { "type": "integer", "minimum": 0, "description": "Repair draft pull requests of this project observed closed without merging." } }, "required": [ "data", "next_cursor", "merged_fixes", "closed_fixes" ] }, "AgentRunPage": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRunSummary" }, "minItems": 0, "maxItems": 50 }, "next_cursor": { "type": "string", "description": "Run UUID cursor, or empty when no next page." } }, "required": [ "data", "next_cursor" ] }, "AgentPublicationReceipt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "enum": [ "pending", "publishing", "uncertain", "published", "stale", "unavailable" ] }, "reason": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" }, "pull_request_url": { "type": "string", "description": "Recorded GitHub PR URL or empty. Does not assert current PR/CI state." }, "target_branch": { "type": "string", "minLength": 1, "maxLength": 200 }, "parent_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "execution_verified": { "type": "boolean", "description": "Broker-verified frozen synthetic task: baseline failed, fresh candidate and verifier passed. Does not assert full test-suite or remote CI success." } }, "required": [ "id", "state", "reason", "recorded_at", "pull_request_url", "target_branch", "parent_sha", "execution_verified" ] }, "AgentRunResult": { "type": "object", "additionalProperties": false, "properties": { "operations": { "type": "array", "items": { "type": "object", "required": [ "schema_version", "operation", "ok", "status", "data", "receipt_id" ], "properties": { "schema_version": { "const": 1 }, "operation": { "type": "string", "minLength": 1, "maxLength": 100 }, "ok": { "const": true }, "status": { "enum": [ "completed", "accepted" ] }, "data": { "type": "object", "description": "Recorded resource identities only. Resource pages hydrate content under current access." }, "receipt_id": { "type": "string", "format": "uuid" } } }, "minItems": 0, "maxItems": 128 }, "evaluators": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "evaluator_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "config_sha256": { "type": "string", "minLength": 1, "maxLength": 64 }, "resource_status": { "enum": [ "draft", "active", "archived" ] } }, "required": [ "evaluator_id", "version", "config_sha256", "resource_status" ] }, "minItems": 0, "maxItems": 1 }, "scenarios": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "scenario_sha256": { "type": "string", "minLength": 1, "maxLength": 64 }, "resource_status": { "type": "string" } }, "required": [ "dataset_id", "version", "scenario_sha256", "resource_status" ] }, "minItems": 0, "maxItems": 1 }, "run_id": { "type": "string", "format": "uuid" }, "result_ref": { "type": "string", "format": "uuid" }, "result": { "description": "Output validated against the pinned agent definition." }, "delivery": { "oneOf": [ { "$ref": "#/components/schemas/AgentPublicationReceipt" }, { "type": "null" } ], "description": "Service-owned publication receipt, separate from model output. Null means no recorded intent yet." } }, "required": [ "operations", "evaluators", "scenarios", "run_id", "result_ref", "result", "delivery" ] }, "AgentRepositoryPublicationScope": { "type": "object", "additionalProperties": false, "properties": { "target_branch": { "type": "string", "minLength": 1, "maxLength": 200 }, "source_pull_requests": { "type": "boolean" }, "write_prefixes": { "type": "array", "items": { "type": "string", "maxLength": 2048 }, "minItems": 1, "maxItems": 100, "uniqueItems": true, "description": "Literal prefixes within repository read scope; protected paths remain denied." }, "allow_static_drafts": { "type": "boolean", "description": "Explicit permission for drafts disclosing static-only assessment. Does not imply execution, passing checks or merge readiness." } }, "required": [ "source_pull_requests", "write_prefixes", "allow_static_drafts" ] }, "AgentRepositoryReadScope": { "type": "object", "additionalProperties": false, "properties": { "binding_id": { "type": "string", "format": "uuid" }, "read_prefixes": { "type": "array", "items": { "type": "string", "maxLength": 2048 }, "minItems": 1, "maxItems": 100, "uniqueItems": true, "description": "Literal path prefixes. An explicit empty string grants the whole repository; an empty list grants nothing. No glob expansion." }, "publication": { "$ref": "#/components/schemas/AgentRepositoryPublicationScope" } }, "required": [ "binding_id", "read_prefixes" ] }, "AgentAutomationConfiguration": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 0, "description": "Zero creates. An edit needs the current revision, makes the caller the owner, resumes a paused automation and fences its older runs." }, "origins": { "type": "array", "items": { "enum": [ "pull_request", "scan", "trace", "monitor", "deployment" ] }, "minItems": 1, "maxItems": 5, "uniqueItems": true }, "max_run_seconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "repository": { "$ref": "#/components/schemas/AgentRepositoryReadScope" }, "production_every_seconds": { "oneOf": [ { "const": 0 }, { "type": "integer", "minimum": 900, "maximum": 86400 } ], "description": "Production telemetry check cadence. Requires a trace, monitor or deployment origin. Zero disables checks." }, "scan_every_seconds": { "oneOf": [ { "const": 0 }, { "type": "integer", "minimum": 3600, "maximum": 2592000 } ], "description": "Repository scan cadence. Omitted or zero disables scans. Requires the scan origin and a repository." } }, "required": [ "expected_revision", "origins", "max_run_seconds" ], "allOf": [ { "if": { "properties": { "origins": { "contains": { "enum": [ "pull_request", "scan" ] } } } }, "then": { "required": [ "repository" ] } }, { "if": { "required": [ "scan_every_seconds" ], "properties": { "scan_every_seconds": { "type": "integer", "minimum": 1 } } }, "then": { "required": [ "repository" ], "properties": { "origins": { "contains": { "const": "scan" } } } } } ] }, "AgentAutomationPause": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "expected_revision" ] }, "AgentAutomationReceipt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "owner_user_id": { "type": "string", "format": "uuid" } }, "required": [ "id", "revision", "owner_user_id" ] }, "AgentBudgetConfiguration": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "organization", "project", "repository" ] }, "binding_id": { "type": "string" }, "limit_micros": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "kind", "limit_micros" ], "allOf": [ { "if": { "properties": { "kind": { "const": "repository" } } }, "then": { "required": [ "binding_id" ], "properties": { "binding_id": { "type": "string", "format": "uuid" } } }, "else": { "properties": { "binding_id": { "const": "" } } } } ] }, "AgentChatIntake": { "type": "object", "additionalProperties": false, "properties": { "parent_run_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "deadline": { "type": "string", "format": "date-time" }, "fix": { "type": "boolean", "description": "Ask for a repair case instead of an answer." }, "model": { "type": "string", "maxLength": 200, "description": "provider/model from GET ask/models. Omitted: the parent turn's model on a follow-up, else the default." }, "input": { "type": "object", "additionalProperties": false, "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 16000 }, "window": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ] }, "context": { "type": "object", "description": "The console page the question was asked from." } }, "required": [ "question", "window" ] } }, "required": [ "request_id", "input" ] }, "AgentRun": { "type": "object", "additionalProperties": false, "properties": { "principal_id": { "type": "string", "maxLength": 200 }, "result_ref": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "generation": { "type": "integer", "minimum": 1 }, "grant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Null: runs admit without a grant (ADR 0069). Set only on runs of the retired executor." }, "grant_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "definition_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "definition_version": { "type": "string", "minLength": 1, "maxLength": 100 }, "definition_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "origin": { "enum": [ "chat", "pull_request", "trace", "monitor", "deployment", "scan", "optimization" ] }, "input_ref": { "type": "string", "format": "uuid" }, "budget_keys": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 2, "maxItems": 8 }, "status": { "enum": [ "queued", "running", "completed", "incomplete", "cancelled", "stale" ] }, "reason": { "type": "string" }, "deadline": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "model_id": { "type": [ "string", "null" ] }, "model_version": { "type": [ "string", "null" ] }, "model": { "type": "string", "description": "The model the run was admitted on, the same as model_id; absent when the run stamped none." } }, "required": [ "principal_id", "result_ref", "id", "organization_id", "project_id", "case_id", "generation", "definition_id", "definition_version", "definition_digest", "origin", "input_ref", "budget_keys", "status", "reason", "deadline", "created_at" ] }, "AskModels": { "type": "object", "additionalProperties": false, "properties": { "default": { "type": "string", "description": "The model a turn that names none runs on; empty when none resolves." }, "models": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "provider": { "type": "string", "minLength": 1, "maxLength": 100 }, "available": { "type": "boolean", "description": "A turn on this model would be admitted for the caller now." }, "source": { "enum": [ "team_key", "included", "chatgpt", "" ], "description": "What pays when available: a saved team key, the included allowance, or the caller's linked ChatGPT plan." }, "context_window_tokens": { "type": "integer", "minimum": 0 } }, "required": [ "id", "provider", "available", "source", "context_window_tokens" ] }, "minItems": 0, "maxItems": 100 } }, "required": [ "default", "models" ] }, "AutomaticSavings": { "type": "object", "additionalProperties": false, "description": "Separate live-traffic comparisons. Cache benefit includes native provider caching; routing reprices completed usage at the configured baseline. Never sum these comparisons together or add verified savings. Neither enters receipts or billing. Missing historical evidence is not backfilled or extrapolated.", "required": [ "cache_observed_usd", "cache_requests", "cache_basis", "router_inferred_usd", "router_baseline_usd", "router_actual_usd", "router_requests", "router_basis", "baseline_models" ], "properties": { "cache_observed_usd": { "type": "number", "description": "Signed USD at catalog list prices. Negative values are costs, not zero savings." }, "cache_requests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cache_basis": { "type": "string", "enum": [ "observed_provider_cache" ] }, "router_inferred_usd": { "type": "number", "description": "Signed USD at catalog list prices. Negative values are costs, not zero savings." }, "router_baseline_usd": { "type": "number", "description": "Signed USD at catalog list prices. Negative values are costs, not zero savings." }, "router_actual_usd": { "type": "number", "description": "Signed USD at catalog list prices. Negative values are costs, not zero savings." }, "router_requests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "router_basis": { "type": "string", "enum": [ "inferred_same_usage_baseline" ] }, "baseline_models": { "type": "array", "uniqueItems": true, "items": { "type": "string" } } } }, "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" } } } } }, "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 } } }, "StandaloneRouteRequest": { "type": "object", "additionalProperties": false, "required": [ "models" ], "oneOf": [ { "required": [ "text" ], "not": { "anyOf": [ { "required": [ "messages" ] }, { "required": [ "signals" ] }, { "required": [ "task" ] }, { "required": [ "ask" ] }, { "required": [ "request" ] }, { "required": [ "last" ] }, { "required": [ "state" ] }, { "required": [ "parent_state" ] } ] } }, { "required": [ "messages" ], "not": { "anyOf": [ { "required": [ "text" ] }, { "required": [ "signals" ] }, { "required": [ "task" ] }, { "required": [ "ask" ] }, { "required": [ "request" ] }, { "required": [ "last" ] }, { "required": [ "state" ] }, { "required": [ "parent_state" ] } ] } }, { "required": [ "signals" ], "not": { "anyOf": [ { "required": [ "text" ] }, { "required": [ "messages" ] }, { "required": [ "task" ] } ] } }, { "required": [ "task", "pool" ], "properties": { "pool": { "minItems": 1 } }, "not": { "anyOf": [ { "required": [ "text" ] }, { "required": [ "messages" ] }, { "required": [ "signals" ] }, { "required": [ "tools" ] }, { "required": [ "ask" ] }, { "required": [ "request" ] }, { "required": [ "last" ] }, { "required": [ "state" ] }, { "required": [ "parent_state" ] } ] } } ], "properties": { "text": { "type": "string", "minLength": 1, "description": "Prompt text, not blank, at most 128 KiB as UTF-8 bytes. The encoded request body is limited to 256 KiB. The ask model reads it in process; the stored prompt digest covers its first 32 KiB." }, "task": { "type": "object", "additionalProperties": false, "required": [ "kind" ], "description": "A delegated coding task (ADR 0123), with models and a non-empty pool only: which pool entry, model and effort a subagent runs on. route-table-v2 picks the model on the class board for kind (implementation, test: general_coding; research: explore_readonly at its dedicated read-only delegation floor; review: explore_readonly at high, effort at least high; design: frontend_ui at high, or plan_design when the brief reads as planning; general: the brief's class), at the ask model's level for brief where kind leaves it open, else medium. Among the entries carrying that model the answer takes the one whose billing comes first (subscription, credits, api_key, then none), then the lowest id. A pool with nothing the catalog prices and scores answers models[0] with no pool_id (reason no_alternative). The answer carries pool_id, model, effort and effort_mode; no state. A decided task is a billed decision.", "properties": { "kind": { "type": "string", "enum": [ "implementation", "research", "review", "design", "test", "general" ], "description": "The task's role." }, "agent": { "type": "string", "maxLength": 128, "description": "The agent type's name (reviewer, ...), at most 128 UTF-8 bytes. Not read by the decision." }, "brief": { "type": "string", "maxLength": 131072, "description": "The task's brief, at most 128 KiB (131,072 UTF-8 bytes). The ask model reads it in memory; it is kept only as ask words are, when the learning gates admit the request (a sampled, consented Free project with a subject, and the legal switch on). A task without words in its brief is never kept." } } }, "signals": { "type": "object", "additionalProperties": false, "required": [ "agent", "context_tokens", "tools_declared", "tool_errors", "images" ], "description": "A local runtime's counts of the ask. Alone they are decided in process by the signals rules and kept only as a count. Replaces text and messages.", "properties": { "agent": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "Harness slug. App-owned caveman-code-claude and caveman-code-codex lock routing to Anthropic and OpenAI respectively. With request, caveman-code-engine always uses route-table-v2 across its pool, regardless of the installation table setting; it has no vendor lock." }, "context_tokens": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "tools_declared": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "tool_errors": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "images": { "type": "boolean" } } }, "ask": { "type": "object", "additionalProperties": false, "required": [ "text" ], "description": "The ask's words, beside signals (required with it). The gateway strips the harness's own text (system reminders, command tags, injected context), cuts each field to what the ask model reads, and decides in process. A text or prev_text within 3 bytes of its limit is read as cut from the front (its tail kept): text before its first closing harness tag, with no opening one before it, is dropped. Field limits are UTF-8 bytes; the encoded request body is limited to 256 KiB. A request the learning gates admit (a sampled, consented Free project with a subject, and the legal switch on) is stored as sent, ask.text, prev_text and reply_tail included; any other ask is read in memory and dropped.", "properties": { "text": { "type": "string", "pattern": "\\S", "description": "The latest human text as the agent sent it: not blank, at most 128 KiB (131,072 UTF-8 bytes)." }, "prev_text": { "type": "string", "description": "The previous human ask as sent, at most 16 KiB (16,384 UTF-8 bytes); the model reads its first 1,500 characters." }, "reply_tail": { "type": "string", "description": "The agent's last text reply before the ask, at most 16 KiB (16,384 UTF-8 bytes); the model reads its last 2,000 characters." }, "turn": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Human asks in the session before this one. Omitted: 1 with prev_text, else 0." } } }, "request": { "type": "object", "additionalProperties": false, "required": [ "endpoint" ], "description": "The request a local runtime is routing, of any class (hub route-ask-v2). With it the route table decides model and effort: the class comes from the harness headers in labels (main, compaction, auxiliary, subagent), and the answer carries effort, effort_mode and state. Needs signals.", "properties": { "endpoint": { "type": "string", "enum": [ "messages", "chat", "responses" ], "description": "The provider API the request uses: Anthropic Messages, OpenAI Chat Completions or OpenAI Responses." }, "labels": { "type": "object", "maxProperties": 16, "propertyNames": { "enum": [ "x-claude-code-request-class", "x-claude-code-compaction", "x-claude-code-agent-id", "x-claude-code-parent-agent-id", "x-claude-code-context-compacted", "x-openai-subagent", "x-codex-turn-metadata", "x-codex-parent-thread-id", "thread-id", "x-caveman-agent", "x-parent-session-id" ] }, "additionalProperties": { "type": "string" }, "description": "Raw values of the request's harness headers, names lower-cased, from this list only. x-caveman-agent is OpenCode's agent, or on a Claude Code child the spawn's raw subagent_type (Plan, Explore, general-purpose; any case): plan takes the parent's model and effort, explore is read-only. An unlabelled child with no edit tool whose first ask reads as plan_design or large_refactor takes the Plan rule too. Values are at most 256 UTF-8 bytes; x-codex-turn-metadata, Codex's turn metadata JSON, at most 16 KiB. Another name or a longer value is a 400." }, "tool_names": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "The request's declared tool names. A subagent's tools say whether it can edit." }, "effort": { "type": "string", "enum": [ "", "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "The effort the request itself carries, in its provider's vocabulary; empty when none." }, "thinking": { "type": "string", "enum": [ "", "adaptive", "enabled", "disabled", "between_tools" ], "description": "The request's thinking mode; empty when unset." }, "per_message_off": { "type": "boolean", "description": "The runtime stopped per-message effort for this session (a refusal or heal latch): effort is applied at top level." }, "cache_ttl": { "type": "string", "enum": [ "", "5m", "30m", "1h", "24h" ], "description": "The prompt-cache TTL the request writes on its own provider, when the runtime sees one: Anthropic cache_control ttl (5m, 1h), OpenAI prompt_cache_options ttl (30m) or prompt_cache_retention (24h). Empty: Claude Code on Anthropic reads as 1h, anything else as the model's catalog TTL. A model of another provider keeps its own catalog TTL." } } }, "last": { "type": "object", "additionalProperties": false, "description": "What the session's previous upstream request ran, from the provider's answer; absent on a session's first request. Read when model is 1-256 bytes, effort one of the request efforts, age_s present and every count 0 to 10^9; any other value or type reads as no last request, never a 400. An unknown field is a 400.", "properties": { "model": { "type": "string" }, "effort": { "type": "string", "description": "One of the request efforts." }, "age_s": { "type": "integer", "description": "Seconds since that request." }, "input_tokens": { "type": "integer" }, "cache_read_tokens": { "type": "integer" }, "cache_write_tokens": { "type": "integer" }, "compacted": { "type": "boolean" } } }, "state": { "type": "string", "description": "The opaque state token of this session's previous answer. A token that does not verify (tampered, another project's, expired after a day idle, longer than 4 KiB, not a string) reads as a fresh session, never a 400." }, "parent_state": { "type": "string", "description": "The parent session's state token, on a subagent's requests; read like state." }, "pool": { "type": "array", "minItems": 0, "maxItems": 64, "description": "The models the caller has set up, beside request (route-ask v2, additive). With it the answer chooses among these entries and the models the project holds stored provider credentials for, which Cloud adds as via cloud (id cloud::); a model reachable both ways answers its local entry. An empty pool means the harness's own models (models, each its own id) plus what Cloud adds. Without pool, models is the pool. ids are unique; any other field is a 400. With task, only these entries: Cloud adds none.", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "model", "host", "via" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The caller's id for the entry, unique in the ask." }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The catalog model name." }, "host": { "type": "string", "pattern": "^[a-z0-9._-]{1,64}$", "description": "The provider or host the model runs on (anthropic, openai, chatgpt, opencode-go, fireworks, openrouter, moonshot, zai, deepseek, gemini, ...); used for price lookup." }, "via": { "type": "string", "enum": [ "local" ], "description": "How the caller reaches it. Only Cloud adds cloud entries." }, "harness": { "type": "string", "enum": [ "claude-agent", "codex", "caveman", "cursor", "opencode", "grok", "pi", "antigravity", "muse", "acp" ], "description": "The harness that runs the model. The same model under two harnesses is two entries. Optional; read only with task." }, "billing": { "type": "string", "enum": [ "subscription", "credits", "api_key" ], "description": "How the entry's use is paid. Optional; with task it orders the entries of the chosen model." } } } }, "messages": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "type": "object", "additionalProperties": false, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 32 }, "content": { "oneOf": [ { "type": "string", "maxLength": 65536 }, { "type": "array", "minItems": 1, "maxItems": 256, "items": { "type": "object", "additionalProperties": false, "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text", "input_text" ] }, "text": { "type": "string", "minLength": 1 } } } } ] } } } }, "models": { "type": "array", "minItems": 1, "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Caller-owned model pool. First entry is always the fallback." } } }, "StandaloneRouteResponse": { "type": "object", "additionalProperties": false, "required": [ "decision_id", "request_id", "trace_id", "span_id", "model", "reason", "router_version", "window_version", "model_pool_sha256", "evidence", "learning_collected", "effort", "effort_mode" ], "properties": { "decision_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "trace_id": { "type": "string" }, "span_id": { "type": "string" }, "model": { "type": "string", "description": "Exact string from models. Without request, ask_xlow and easy_turn move off models[0] to the nearest cheaper model on its provider, and ask_work (route-work-v1) to its work type's cell, up or down from models[0]. With request, the route table's cell wins, up or down from models[0]." }, "reason": { "type": "string", "pattern": "^(ask_xlow|ask_low|ask_medium|ask_high|ask_work|easy_turn|hard_turn|no_cheaper_model|no_features|no_alternative|allowance|billing_limit|continuation|compaction_current|safe_default|auxiliary_cheapest|subagent_read_only|subagent_edit|subagent_plan_parent|subagent_parent|subagent_pinned|task_implementation|task_research|task_review|task_design|task_test|task_general)(\\+(nearest|no_level|plan_floor|hold_warm|raise_warm|switch_pays|effort_free|effort_drop_pays|parent_high|cap_parent|llm_pick|user_effort))*$", "description": "A base, then +markers. ask_work is route-work-v1's decision, with or without request: an ask that declares no shell or edit tool (and, with signals, names every tool it counts), on an installation with routing.workType on, routed by its work type to a matrix cell: build to claude-sonnet-5-5 at medium effort, fix to claude-haiku-5-5 at low, any other work type to claude-opus-5-5 at medium, when models (with request, the models that fit) has the cell's model; otherwise the ask is decided as below. Without request: ask_xlow, ask_low, ask_medium and ask_high are the ask model's decisions (the level it routed the ask at; an xlow ask keeps models[0] when nothing on its provider is cheaper); easy_turn, hard_turn and no_cheaper_model are decisions of the signals rules, which also answer when the ask model is unavailable, hard_turn also keeping an ask whose context exceeds 32,000 tokens or carries images. No decision was made for no_features (no signals and no words of the person's), no_alternative (no other known model on the asked model's provider), allowance (the free routing allowance is used this month) or billing_limit (the pay-as-you-go routing billing limit is reached this month). With request (route table): ask_ is a main ask, or a subagent with no parent state, at its level's cell; continuation keeps the current ask's cell; compaction_current stays on the session's cell, safe_default takes the cheapest model that holds the context; auxiliary_cheapest is the cheapest of the asked model and the pool; subagent_read_only (the lane's xlow cell), subagent_edit (its first prompt's cell, capped at the parent), subagent_plan_parent and subagent_parent (the parent's model) answer a subagent's first request and subagent_pinned its later ones. Markers: nearest (the cell's model was not in models; the lane's strongest stood in), no_level (no level from the ask model: read as general_coding, medium), plan_floor (a plan_design ask's effort raised to high), hold_warm (a warm session kept its config; on a forked child, the parent's model, which holds its inherited context), raise_warm, switch_pays, effort_free and effort_drop_pays (a warm session moved), parent_high (an editing child floored at medium under a high parent ask), cap_parent (an editing child held to its parent's cell), user_effort (the effort the user set mid-session). With task: task_ (implementation, research, review, design, test, general), with no_level when no level came from the brief and plan_floor as above." }, "router_version": { "type": "string", "description": "The decider: route-table-v1 or route-table-v2 (a body carrying request, by the installation's routing.table), route-work-v1 (the work model and its matrix, reason ask_work), ask-model-r4 (the ask model), features-rules-v1 (the signals rules) or gateway-fallback (no decision)." }, "window_version": { "type": "integer", "minimum": 0, "description": "Classifier window cut the decision was made from. The same body classified under a different window version is a different question." }, "profile_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the deciding classifier's artifact, present when one decided: the ask model's, or the work model's on route-work-v1." }, "model_pool_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "evidence": { "type": "string", "enum": [ "baseline_fallback", "ask_model", "features_rules", "route_table", "work_model" ] }, "learning_collected": { "type": "boolean", "description": "True only when a subject-attributed, sampled, explicitly-consented Free-plan decision reached durable admission." }, "outcome_token": { "type": "string", "description": "Short-lived signed token. Present only when learning_collected is true." }, "notice": { "type": "string", "description": "One plain line to show the person. Present only with reason allowance." }, "effort": { "type": "string", "enum": [ "", "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "The effort to apply, in the chosen model's provider vocabulary and among its catalog effort levels; empty leaves the request's own effort as it is. Without request, empty except on ask_work (the cell's effort, effort_mode top)." }, "default_effort": { "type": "string", "enum": [ "", "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "On every answer to a body carrying request: the asked model's (models[0]) reviewed default effort, in its provider's vocabulary, for requests running on models[0]: the catalog's, else Anthropic's documented default for a Claude model (medium on Opus 5.5, high on every other Claude model that takes effort; a dated id or a [1m] suffix reads as its model); empty when neither states one. A runtime that applied per-message effort marks this effort when routing later stops answering one (off, failing, or effort empty with no effort of the agent's own), instead of removing its marks, which would change the history thinking is bound to." }, "effort_mode": { "type": "string", "enum": [ "message", "top", "" ], "description": "How to apply effort (message only on route-ask-v2 request bodies; Helm routing.perMessageEffortAnthropic defaults on, routing.perMessageEffortOpenAI defaults off pending a live check; deprecated routing.perMessageEffort sets both defaults): message as a cache-keeping effort change: on Anthropic Messages a per-message effort (a role system message with output_config.effort, beta mid-conversation-output-config-2026-07-01), on an OpenAI GPT-6 Responses request a configuration_update input item before the next user message; top as the request's top-level effort field; empty with an empty effort. A runtime that has already applied per-message marks in a session applies a later top answer as another per-message mark while the session's model and request still take per-message effort and per_message_off is unset, so the history thinking is bound to never changes; otherwise top is applied at top level." }, "pool_id": { "type": "string", "description": "On an answer to a body carrying pool: the chosen entry's id (a caller entry, or cloud::). model is the model id to send." }, "via": { "type": "string", "enum": [ "local", "cloud", "credits" ], "description": "On an answer to a body carrying pool: how the chosen entry is reached. credits is reached as cloud is (pool_id in x-caveman-route) on a Caveman Code credits key, paid from its plan usage or credits." }, "placement": { "type": "string", "enum": [ "sponsored" ], "description": "On an answer to a body carrying pool, sponsored when a live sponsored deal on the credits key chose the entry among options that all clear the quality floor, at no more than 10% above the cheapest of them; absent otherwise. A warm session's cache rule decides first." }, "state": { "type": "string", "maxLength": 4096, "description": "The session's next state token, to store and send back as state on its next request (and as parent_state on its subagents' requests). A subagent's answer carries the child's own token: store it under the child's session, never the parent's. Absent on compaction and auxiliary answers, paused answers and panic fallbacks: keep the token you have. Always absent without request." } } }, "TrimRequest": { "type": "object", "additionalProperties": false, "required": [ "input", "query" ], "properties": { "input": { "type": "string", "description": "One payload: a tool output, file, log or document. The body is at most 2 MB." }, "query": { "type": "string", "minLength": 1, "description": "What the payload is read for: the ask, the agent's intent, the call that produced it. Must not be blank." }, "level": { "type": "string", "enum": [ "conservative", "balanced", "aggressive" ], "default": "balanced", "description": "How much trim-1 keeps: conservative keeps most." } } }, "TrimResponse": { "type": "object", "additionalProperties": false, "required": [ "output", "tokens_before", "tokens_after", "model" ], "properties": { "output": { "type": "string", "description": "The lines of input the query needs, verbatim and in order, with a marker for each run left out; the input itself when trimming would not cut enough." }, "tokens_before": { "type": "integer", "minimum": 0 }, "tokens_after": { "type": "integer", "minimum": 0 }, "recovery_handle": { "type": "string", "description": "Present when something was left out and it was stored: GET /sdk/v1/ccr/{handle} returns the input byte for byte. Absent under metadata or zdr retention, and when the installation has no recovery store or it failed; the output is the same either way." }, "model": { "const": "trim-1" } } }, "CompactRequest": { "type": "object", "additionalProperties": false, "required": [ "messages", "budget_tokens" ], "properties": { "messages": { "type": "array", "minItems": 1, "description": "The agent's whole history: OpenAI chat messages (tool_calls, role tool) or Anthropic Messages (tool_use and tool_result blocks), not mixed. The body is at most 8 MB.", "items": { "type": "object", "required": [ "role" ], "additionalProperties": true } }, "budget_tokens": { "type": "integer", "minimum": 1, "description": "The most tokens the history may take after its leading system messages, which are kept as sent and not counted." } } }, "CompactResponse": { "type": "object", "additionalProperties": false, "required": [ "messages", "tokens_before", "tokens_after", "model" ], "properties": { "messages": { "type": "array", "description": "The history to continue from, in the request's shape: the system prompt, the user's messages, one compact-1 block (a ledger of the work and the older lines most likely needed, with markers for what was left out), then the newest turns. Every message kept whole is returned as sent, byte for byte, and a history that already holds a compact-1 block keeps everything up to it byte-identical, so the provider's prompt cache survives.", "items": { "type": "object", "additionalProperties": true } }, "tokens_before": { "type": "integer", "minimum": 0, "description": "The request's text tokens after its leading system messages (cl100k_base estimate of compact-1's serialization; images and thinking blocks are not counted)." }, "tokens_after": { "type": "integer", "minimum": 0, "description": "The answer's text tokens, counted the same way; at most budget_tokens. Images and thinking blocks kept in whole messages come on top." }, "recovery_handles": { "type": "array", "items": { "type": "string" }, "description": "Present when text was left out and it was stored: GET /sdk/v1/ccr/{handle} returns the left-out spans, each under the reference its marker shows. Absent under metadata or zdr retention, and when the installation has no recovery store or it failed: the markers then point at nothing." }, "model": { "const": "compact-1" } } }, "CodeSearchRequest": { "type": "object", "additionalProperties": false, "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 400, "description": "What to search for: 1 to 400 characters once whitespace runs are folded to single spaces; no control characters. Never logged or stored." }, "count": { "type": "integer", "minimum": 1, "maximum": 10, "default": 8, "description": "The most results to return." }, "freshness": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "Only pages from the last day, week, month or year." }, "domains": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 253 }, "description": "Only results from these host names or their subdomains (docs.python.org: no scheme, path, port or address; punycode for international names). Case and a trailing dot are ignored; repeats are dropped." } } }, "CodeSearchResponse": { "type": "object", "additionalProperties": false, "required": [ "results", "provider", "cost_usd" ], "properties": { "results": { "type": "array", "maxItems": 10, "description": "Pages in the provider's relevance order, each once, at most count; empty when nothing relevant was found (still charged: the provider ran).", "items": { "type": "object", "additionalProperties": false, "required": [ "url", "title", "excerpts" ], "properties": { "url": { "type": "string", "format": "uri", "description": "An absolute http or https URL." }, "title": { "type": "string", "description": "The page title, or its host name when the provider gave none; at most 512 bytes." }, "date": { "type": "string", "format": "date", "description": "Publication date (YYYY-MM-DD) when the provider knows it." }, "excerpts": { "type": "array", "maxItems": 16, "items": { "type": "string", "minLength": 1 }, "description": "Text the provider extracted for the query, at most 4 KiB each; structured data (tables, code) arrives as compact JSON text. May be empty." } } } }, "provider": { "type": "string", "enum": [ "brave", "perplexity" ], "description": "Who answered: Brave LLM Context, or Perplexity Search when Brave failed." }, "cost_usd": { "type": "number", "minimum": 0, "description": "What this search cost on the organization's credits: the answering provider's list price per request (0.005), at cost. A search no provider answered costs nothing." } } }, "ModelCatalog": { "type": "object", "required": [ "schema", "revision", "generated_at", "sources", "models" ], "properties": { "schema": { "const": "caveman.catalog.v1" }, "revision": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Opaque revision of this body: it changes when a fact it publishes changes, never for generated_at or fetched_at alone. The weak ETag is W/\"\"." }, "generated_at": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "required": [ "id", "license", "models" ], "properties": { "id": { "type": "string", "enum": [ "models.dev", "litellm", "aws-pricing", "reviewed-catalog", "facts" ] }, "license": { "type": "string" }, "fetched_at": { "type": "string" }, "models": { "type": "integer", "minimum": 0, "description": "Observations the source's last good fetch carried." } } } }, "models": { "type": "array", "items": { "type": "object", "required": [ "id", "maker", "review", "lifecycle", "limits", "capabilities", "effort", "hosts", "provenance" ], "properties": { "id": { "type": "string", "description": "Canonical model id: the maker's first-party id. Host-specific ids (Bedrock profiles, Vertex snapshots, aggregator slugs) fold onto it." }, "maker": { "type": "string" }, "name": { "type": "string" }, "review": { "type": "string", "enum": [ "reviewed", "unreviewed" ], "description": "unreviewed: newly seen and not yet approved. Usable when a request names it; never a routing substitution target." }, "released_at": { "type": "string" }, "lifecycle": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "legacy", "deprecated", "retired" ] }, "deprecated_at": { "type": "string" }, "retires_at": { "type": "string" }, "replacement": { "type": "string" } } }, "limits": { "type": "object", "properties": { "context_tokens": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } }, "capabilities": { "type": "object", "description": "Tri-state: an absent key is unknown.", "properties": { "tools": { "type": "boolean" }, "vision": { "type": "boolean" }, "pdf": { "type": "boolean" }, "structured_output": { "type": "boolean" }, "reasoning": { "type": "boolean" }, "streaming": { "type": "boolean" }, "prompt_cache": { "type": "boolean" } } }, "effort": { "type": "object", "properties": { "levels": { "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "default": { "type": "string" }, "thinking_off": { "type": "string", "enum": [ "effort_none", "thinking_disabled", "between_tools", "unsupported" ] } } }, "hosts": { "type": "array", "items": { "type": "object", "required": [ "host", "model_id", "region", "surfaces", "sources" ], "properties": { "host": { "type": "string", "description": "anthropic, openai, gemini, vertex, bedrock, deepseek, moonshot, xai, mistral, groq, qwen, z-ai, minimax." }, "model_id": { "type": "string", "description": "The id this host takes on the wire." }, "region": { "type": "string", "description": "global for single-endpoint hosts; an AWS region for Bedrock; any when no source says which regions serve the id." }, "scope": { "type": "string", "description": "Bedrock inference-profile scope (global, us, eu, apac, jp, au, us-gov, ca); absent for a base id." }, "surfaces": { "type": "array", "items": { "type": "object", "required": [ "wire" ], "properties": { "wire": { "type": "string", "enum": [ "messages", "responses", "chat_completions", "generate_content", "converse", "invoke" ] }, "tools": { "type": "boolean", "description": "false: this wire refuses tools for this model." }, "per_message_effort": { "type": "boolean", "description": "true: effort can change per message on this wire without breaking the prompt cache." } } } }, "prices": { "type": "array", "items": { "type": "object", "required": [ "tier", "source" ], "properties": { "tier": { "type": "string", "enum": [ "standard", "flex", "priority", "batch" ] }, "input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "output_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "cache_read_input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "cache_write_input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens written to a 5-minute (default TTL) cache." }, "cache_write_1h_input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens written to a 1-hour cache." }, "long_context": { "type": "object", "required": [ "above_tokens" ], "properties": { "above_tokens": { "type": "integer", "minimum": 1 }, "input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "output_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." } } }, "schedule": { "type": "object", "required": [ "effective_from", "default" ], "description": "The reviewed daily UTC schedule this price follows, the one billing charges by. The price's own rates are the ones in effect at generated_at; the revision moves when a window opens or closes. From effective_from the rates are default, except inside a window's half-open [start, end) of each UTC day.", "properties": { "effective_from": { "type": "string", "description": "RFC 3339." }, "default": { "type": "object", "properties": { "input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "output_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "cache_read_input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "cache_write_input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens written to a 5-minute (default TTL) cache." }, "cache_write_1h_input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens written to a 1-hour cache." } } }, "windows": { "type": "array", "items": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "string", "pattern": "^[0-9]{2}:[0-9]{2}:[0-9]{2}$", "description": "UTC time of day, HH:MM:SS." }, "end": { "type": "string", "pattern": "^[0-9]{2}:[0-9]{2}:[0-9]{2}$", "description": "UTC time of day, HH:MM:SS." }, "input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "output_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "cache_read_input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens." }, "cache_write_input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens written to a 5-minute (default TTL) cache." }, "cache_write_1h_input_per_million": { "type": "number", "minimum": 0, "description": "USD per million tokens written to a 1-hour cache." } } } } } }, "source": { "type": "string", "description": "The ingest source the rates come from." }, "fetched_at": { "type": "string", "description": "The fetch the rates came from as of the catalog's last change (RFC 3339), or the reviewed catalog's verified_at. Not part of the revision: a refetch that changes nothing does not move it." } } } }, "cache": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit", "implicit", "automatic" ] }, "ttl_seconds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "min_tokens": { "type": "integer", "minimum": 0 }, "max_breakpoints": { "type": "integer", "minimum": 0 }, "source": { "type": "string" } } }, "sources": { "type": "array", "items": { "type": "string" } } } } }, "provenance": { "type": "object", "description": "Field path (limits.context_tokens, capabilities.tools, effort.levels, ...) to the source that supplied the published value.", "additionalProperties": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string" }, "fetched_at": { "type": "string" } } } }, "conflicts": { "type": "array", "description": "Fields the sources disagree on. The published value is chosen's; every source's value is listed.", "items": { "type": "object", "required": [ "field", "values", "chosen" ], "properties": { "field": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "required": [ "source", "value" ], "properties": { "source": { "type": "string" }, "value": { "type": "string" } } } }, "chosen": { "type": "string" } } } } } } } } } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "Native CLI sessions use the device grant. Remote MCP uses authorization code with S256 PKCE and resource=/mcp; those opaque tokens are accepted only at the generated Cloud operation ingress. All grants remain project/permission scoped and revocable.", "flows": { "authorizationCode": { "authorizationUrl": "/api/v1/oauth/authorize", "tokenUrl": "/api/v1/oauth/token", "refreshUrl": "/api/v1/oauth/token", "scopes": { "org:read": "Read the organization, its projects, and the caller's own membership.", "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.", "trace:read_payload": "Read captured trace payloads through the trace disclosure gate.", "experiment:run": "Start, stop, and read optimization experiments.", "setup:write": "Assert what the repository contains (agents, models, prompts, tools, eval fixtures) so Caveman can set the project up. Changes no file, policy or traffic.", "settings:read": "Read project and organization settings.", "opportunity:write": "Create, rank, and dismiss efficiency opportunities; edit and comment on briefs; take a brief's fix with your own agent.", "scenario:read": "Read frozen agent task scenario definitions and execution evidence.", "scenario:write": "Create and update agent task scenarios.", "eval:write": "Create eval suites, replace their cases, and ingest eval evidence.", "prompt:read": "Read prompts.", "artifact:read_metadata": "List artifacts and read their metadata.", "inbox:read": "Read the organization inbox: what Caveman noticed, did, and needs decided.", "dashboard:write": "Create and change project dashboards, their charts, metric alerts and saved-view alerts (they notify owners and admins; posting to a webhook also needs provider:manage)." } }, "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.", "trace:read_payload": "Read captured trace payloads through the trace disclosure gate.", "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.", "setup:write": "Assert what the repository contains (agents, models, prompts, tools, eval fixtures) so Caveman can set the project up. Changes no file, policy or traffic.", "repo:read": "Read source from an authorized project repository within an explicit repository grant.", "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; edit and comment on briefs; take a brief's fix with your own agent.", "outcome:write": "Ingest Outcome Contract evidence about what happened after a run.", "evaluator:qualify": "Run independent evaluator qualification against authorized evaluation sets.", "evaluator:activate": "Activate qualified evaluators within their authorized population.", "scenario:read": "Read frozen agent task scenario definitions and execution evidence.", "scenario:write": "Create and update agent task scenarios.", "agent:execute": "Execute authorized agent operations within configured grants and budgets.", "eval:write": "Create eval suites, replace their cases, and ingest eval evidence.", "prompt:read": "Read prompts.", "prompt:write": "Create and change prompts.", "auditlog:read": "Read the tenant audit trail.", "artifact:read_metadata": "List artifacts and read their metadata.", "artifact:delete": "Delete artifacts.", "inbox:read": "Read the organization inbox: what Caveman noticed, did, and needs decided.", "inbox:write": "Emit inbox items and act on them: archive, resolve, or run a declared action.", "dashboard:write": "Create and change project dashboards, their charts, metric alerts and saved-view alerts (they notify owners and admins; posting to a webhook also needs provider:manage).", "code:read": "Read Caveman Code workspaces, sessions, journal positions, computers and runtimes, and the names of your own repository secrets. Never transcripts or secret values.", "code:write": "Start and archive Caveman Code workspaces, set a tree's budget, enroll or revoke the runtimes that run them, store or delete your own repository secrets, and list or remove your own MCP server connections." } } }, "x-authorization-server-metadata": "/.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." }, "identityCookieAuth": { "type": "apiKey", "in": "cookie", "name": "__Secure-cave_identity.session_token", "description": "Better Auth browser session when /auth/config returns better-auth. Loopback HTTP uses cave_identity.session_token. Cookie mutations require x-cave-csrf: ui. Credentials and factors are managed under /api/auth on the API origin." }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "cave_access", "description": "HttpOnly cave_access cookie. Cookie-authenticated mutations also require the x-cave-csrf: ui header." }, "projectKey": { "type": "apiKey", "in": "header", "name": "x-cave-api-key", "description": "Project-bound gateway key carrying the scope each operation names (router:write, sdk:write; proxy:write on a Caveman Code credits key for /v1/code/search). This is not a control-plane bearer token or an upstream provider key." }, "platformAdminToken": { "type": "http", "scheme": "bearer", "description": "Operator plane only: the installation's platform admin token, also accepted as the x-cave-admin-token header, and only from the private admin network (CAVE_PLATFORM_ADMIN_CIDRS in production). Unset, the operator plane is off." }, "githubActionsOIDC": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A GitHub Actions OIDC token whose audience is this API, from a workflow in a repository connected to the project with CI checks on. Nothing is stored: the token is the credential for one run." }, "runtimeTokenAuth": { "type": "http", "scheme": "bearer", "description": "A Caveman Code runtime token, ccrt__: 15 minutes, minted by POST /code/runtimes/{runtimeId}/token from an assertion signed with the runtime's enrolled Ed25519 key. It authorizes one runtime on one computer, never a person." } }, "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" } } } } } }, "openapi": "3.1.0", "info": { "title": "Caveman Cloud API", "version": "1.0.0", "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** — /auth/config identifies the browser authentication mode. Better Auth deployments use an HttpOnly __Secure-cave_identity.session_token cookie and /api/auth browser endpoints. Legacy deployments and device grants carry an 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.\n\n**Operator plane** — `/admin/*` and `/system/clickhouse-recovery-points` answer only Caveman's operators, with the platform admin token from the private admin network (`platformAdminToken`). They are listed for completeness; no customer credential reaches them.", "contact": { "name": "Caveman", "email": "contact@caveman.so", "url": "https://caveman.so/contact" }, "license": { "name": "Proprietary", "url": "https://caveman.so/terms" }, "x-caveman-generated-operation-count": 828, "x-caveman-generated-gateway-operation-count": 2 }, "externalDocs": { "description": "Agent-facing index", "url": "https://caveman.so/llms.txt" }, "servers": [ { "url": "https://api.caveman.so/api/v1", "description": "Caveman Cloud (managed)" }, { "url": "/api/v1", "description": "Same-origin or self-hosted control plane" } ], "security": [ { "oauth2": [] }, { "bearerAuth": [] }, { "cookieAuth": [] }, { "identityCookieAuth": [] } ], "x-caveman-excluded-runtime-routes": [] }