@1claw/openapi-spec 0.61.39 → 0.61.41

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.39",
+    "version": "0.61.41",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging. Automations (workflow_spec,\nwebhook tokens, event triggers, Assist), cloud runtimes with\ninteractive shell sessions, agent memory, and discovery.\n\n## Domains\n\n`api.1claw.co` is canonical: it is the OIDC issuer, the `aud` the API\nmints, and the first entry in `servers` — a generated client takes its\nbase URL from there, and the previous ordering pointed every SDK at the\ndomain the issuer had already left. `api.1claw.xyz` still answers and is\nstill accepted on token validation, because tokens minted before the\nmove carry it; it is never minted now.\n\nOne deliberate exception: the Shroud attestation identity token is\nrequested from GCP with `audience: https://api.1claw.xyz`, so\n`/v1/shroud/attestation` reports that as its `expected_audience`. That\nis accurate rather than stale — the audience is a verification contract\nwith anyone already checking the token, and moving it is a breaking\nchange for them, not a rename.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.co"
@@ -79,6 +79,10 @@
       "name": "Organization",
       "description": "Org membership and roles"
     },
+    {
+      "name": "Spend",
+      "description": "AI spend — inference cost per agent, provider and model, against budgets and caps"
+    },
     {
       "name": "Billing",
       "description": "Subscriptions, credits, and usage"
@@ -218,6 +222,10 @@
     {
       "name": "Shamir KEK",
       "description": "Shamir secret-sharing for org-level Key Encryption Keys"
+    },
+    {
+      "name": "Agent Tools",
+      "description": "Utility tools an agent calls directly on its own token (web search, etc.)"
     }
   ],
   "paths": {
@@ -2907,7 +2915,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.0075"
+          "price": "0.0225"
         },
         "parameters": [
           {
@@ -2960,7 +2968,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.0015"
+          "price": "0.0045"
         },
         "parameters": [
           {
@@ -4112,7 +4120,8 @@
           "protocols": [
             "x402"
           ],
-          "pricingMode": "quote"
+          "pricingMode": "fixed",
+          "price": "0.225"
         },
         "description": "Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).\nDuplicate requests with the same key within 24 hours return the cached transaction response\n(no second sign/broadcast). Omit the header for non-idempotent submissions.\n",
         "operationId": "submitTransaction",
@@ -4283,7 +4292,8 @@
           "protocols": [
             "x402"
           ],
-          "pricingMode": "quote"
+          "pricingMode": "fixed",
+          "price": "0.225"
         },
         "parameters": [
           {
@@ -4338,7 +4348,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.075"
+          "price": "0.225"
         },
         "parameters": [
           {
@@ -4393,7 +4403,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.075"
+          "price": "0.225"
         },
         "parameters": [
           {
@@ -6403,7 +6413,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.003"
+          "price": "0.009"
         },
         "parameters": [
           {
@@ -6462,7 +6472,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.0015"
+          "price": "0.0045"
         },
         "parameters": [
           {
@@ -6610,6 +6620,301 @@
         }
       }
     },
+    "/v1/spend/ai": {
+      "get": {
+        "tags": [
+          "Spend"
+        ],
+        "summary": "AI spend",
+        "operationId": "getAiSpend",
+        "description": "Inference spend for the org over a window (default the last 30 days):\ntotals with the previous equal-length window for comparison, a time series\nby provider, and breakdowns by provider, by model and by agent — each agent\nwith its `shroud_config` daily budget, today's spend against it and the\nrequests Shroud blocked for budget. `limits` carries router-key spend caps,\nthe credit balance and 1Claw's inspection fees for the window (a separate\nnumber from provider cost). Every request is priced at ingest from the\nprice card (`GET /v1/spend/ai/prices`); a request whose provider has no\ncard is counted as unpriced, not free. Human and platform callers only.\nBacks the dashboard's Spend tab; the same numbers reach an org's own\ncollector as OTEL metrics `ai.cost_usd`, `ai.tokens.input`, `ai.tokens.output`.\n",
+        "parameters": [
+          {
+            "name": "from",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          {
+            "name": "to",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          {
+            "name": "interval",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "day",
+                "week",
+                "month"
+              ],
+              "default": "day"
+            }
+          },
+          {
+            "name": "agent_id",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "provider",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Spend",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AiSpend"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/spend/ai/export.csv": {
+      "get": {
+        "tags": [
+          "Spend"
+        ],
+        "summary": "AI spend as CSV",
+        "operationId": "exportAiSpendCsv",
+        "description": "One row per agent × provider × model in the window (same filters as `GET /v1/spend/ai`).",
+        "parameters": [
+          {
+            "name": "from",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          {
+            "name": "to",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          {
+            "name": "agent_id",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "provider",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "CSV",
+            "content": {
+              "text/csv": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/spend/ai/prices": {
+      "get": {
+        "tags": [
+          "Spend"
+        ],
+        "summary": "LLM price card",
+        "operationId": "listLlmPrices",
+        "description": "The global price card (public list prices per million tokens) plus this\norg's overrides. Matching: an org row beats a global row; among those the\nlongest `model_pattern` wins; a pattern ending in `%` is a prefix match.\n",
+        "responses": {
+          "200": {
+            "description": "Prices",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "prices"
+                  ],
+                  "properties": {
+                    "prices": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/LlmModelPrice"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      },
+      "put": {
+        "tags": [
+          "Spend"
+        ],
+        "summary": "Set an org price override",
+        "operationId": "upsertLlmPrice",
+        "description": "Owner/admin. Upserts one override for this org; future requests are priced with it (history is not rewritten).",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "provider",
+                  "model_pattern",
+                  "input_usd_per_mtok",
+                  "output_usd_per_mtok"
+                ],
+                "properties": {
+                  "provider": {
+                    "type": "string",
+                    "example": "anthropic"
+                  },
+                  "model_pattern": {
+                    "type": "string",
+                    "example": "claude-sonnet-5%"
+                  },
+                  "input_usd_per_mtok": {
+                    "type": "number",
+                    "example": 3
+                  },
+                  "output_usd_per_mtok": {
+                    "type": "number",
+                    "example": 15
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The override",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/LlmModelPrice"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/spend/ai/prices/{id}": {
+      "delete": {
+        "tags": [
+          "Spend"
+        ],
+        "summary": "Remove an org price override",
+        "operationId": "deleteLlmPrice",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Removed"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/spend/ai/reprice": {
+      "post": {
+        "tags": [
+          "Spend"
+        ],
+        "summary": "Price the org's unpriced requests",
+        "operationId": "repriceAiSpend",
+        "description": "Owner/admin. Re-runs the price card over rows that had no price when they arrived (after adding a card for that provider). Already-priced rows are untouched.",
+        "responses": {
+          "200": {
+            "description": "Count",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "repriced": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
     "/v1/org/overview": {
       "get": {
         "tags": [
@@ -6750,6 +7055,114 @@
         }
       }
     },
+    "/v1/onboarding/guided/status": {
+      "get": {
+        "tags": [
+          "Organization"
+        ],
+        "summary": "Guided onboarding eligibility + status",
+        "description": "Whether this org is in the guided-onboarding rollout cohort, plus the\nsame welcome-bundle progress fields `GET /v1/org/onboarding/status`\nreports. `eligible` decides whether the dashboard's redirect sends a\nnew, still-unprovisioned user to the guided flow or the existing\nMCP-connect flow.\n",
+        "operationId": "getGuidedOnboardingStatus",
+        "responses": {
+          "200": {
+            "description": "Guided onboarding status",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GuidedOnboardingStatus"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/onboarding/guided/ask": {
+      "post": {
+        "tags": [
+          "Organization"
+        ],
+        "summary": "Ask the guided onboarding assistant a question",
+        "description": "Scoped, one-shot Q&A for the guided wizard's \"have a question?\" panel.\nNot tied to an agent (many questions arrive before one exists yet) and\nnot persisted as a conversation. The system prompt is fixed server-side\nand refuses anything outside vaults/policies/runtimes/billing/channels —\nnever client-suppliable. Billed like any other Shroud LLM call: the\ncaller's own bearer token is forwarded so usage attributes to their org.\n",
+        "operationId": "guidedOnboardingAsk",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GuidedAskRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Assistant's answer",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GuidedAskResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/onboarding/guided/trial/setup-intent": {
+      "post": {
+        "tags": [
+          "Organization"
+        ],
+        "summary": "Start a card-on-file trial runtime setup",
+        "description": "Creates a Stripe SetupIntent for the org's customer so the guided\nonboarding wizard can collect a card with Stripe.js — no charge unless\nthe trial runtime is kept past its trial window.\n",
+        "operationId": "createTrialSetupIntent",
+        "responses": {
+          "200": {
+            "description": "SetupIntent client secret",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TrialSetupIntentResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/onboarding/guided/trial/runtime": {
+      "post": {
+        "tags": [
+          "Organization"
+        ],
+        "summary": "Create a card-gated trial runtime",
+        "description": "Verifies the given SetupIntent succeeded, then delegates to the same\nruntime-creation logic `POST /v1/runtimes` uses. Only reachable once\nthe guided onboarding wizard has a confirmed SetupIntent for the org.\n",
+        "operationId": "createTrialRuntime",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateTrialRuntimeRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created runtime",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RuntimeResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/org/status": {
       "get": {
         "tags": [
@@ -7607,7 +8020,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.0008"
+          "price": "0.0024"
         },
         "parameters": [
           {
@@ -11999,6 +12412,72 @@
         }
       }
     },
+    "/v1/shroud/activity/today": {
+      "get": {
+        "tags": [
+          "Shroud"
+        ],
+        "summary": "An agent's inference spend since 00:00 UTC",
+        "operationId": "getAgentSpendToday",
+        "description": "What the agent has spent today per the vault's priced activity rows, plus\nrequests and tokens and how many requests Shroud blocked for budget. Shroud\nsyncs its daily-budget counter from this so `daily_budget_usd` holds across\nShroud instances and restarts. Callable by the agent itself (its own id) or the\nplatform service key — the same gate as activity ingest.\n",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "agent_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Today's spend",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "agent_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "day": {
+                      "type": "string",
+                      "example": "2026-09-21"
+                    },
+                    "cost_usd": {
+                      "type": "number"
+                    },
+                    "requests": {
+                      "type": "integer",
+                      "format": "int64"
+                    },
+                    "tokens": {
+                      "type": "integer",
+                      "format": "int64"
+                    },
+                    "blocked_by_budget": {
+                      "type": "integer",
+                      "format": "int64"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
     "/v1/shroud/threat-summary": {
       "get": {
         "tags": [
@@ -17935,6 +18414,149 @@
         }
       }
     },
+    "/v1/admin/stats/growth-timeseries": {
+      "get": {
+        "tags": [
+          "Admin"
+        ],
+        "summary": "Time-bucketed usage series for one adoption/usage vertical (admin only)",
+        "description": "Gap-filled counts (24h → hourly, 7d/30d/90d → daily, 365d → weekly) for one of 15 adoption/usage verticals, plus a period-over-period delta. Backs both the live admin analytics dashboard and the weekly investor report — same source, two surfaces.\n",
+        "operationId": "adminGrowthTimeseries",
+        "parameters": [
+          {
+            "name": "vertical",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "signups_orgs",
+                "signups_users",
+                "subscriptions_new",
+                "subscriptions_churned",
+                "shroud_usage",
+                "shroud_security",
+                "intents_execution",
+                "intents_transactions",
+                "vault_usage",
+                "runtime_usage",
+                "memory_usage",
+                "automations",
+                "embedded_wallets_created",
+                "embedded_wallets_used",
+                "platform_api"
+              ]
+            }
+          },
+          {
+            "name": "period",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "24h",
+                "7d",
+                "30d",
+                "90d",
+                "365d"
+              ],
+              "default": "30d"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Time-bucketed series for the requested vertical",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GrowthTimeseriesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/admin/stats/retention": {
+      "get": {
+        "tags": [
+          "Admin"
+        ],
+        "summary": "Logo retention over a trailing window (admin only)",
+        "description": "Percentage of organizations older than `window_days` that showed any platform activity (usage_events) in the trailing `window_days` — a simple, defensible retention proxy, not a full cohort matrix.\n",
+        "operationId": "adminRetention",
+        "parameters": [
+          {
+            "name": "window_days",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 30,
+              "minimum": 1,
+              "maximum": 365
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Retention over the requested window",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RetentionResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/admin/llm-prices": {
+      "get": {
+        "tags": [
+          "Admin"
+        ],
+        "summary": "Global LLM price card (admin only)",
+        "description": "The platform-wide price card with no org-level overrides applied — see `/v1/spend/ai/prices` for the org-resolved view.",
+        "operationId": "adminListLlmPrices",
+        "responses": {
+          "200": {
+            "description": "Prices",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "prices"
+                  ],
+                  "properties": {
+                    "prices": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/LlmModelPrice"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/pay/settings": {
       "patch": {
         "tags": [
@@ -27628,6 +28250,64 @@
         }
       }
     },
+    "/v1/tools/web-search": {
+      "post": {
+        "tags": [
+          "Agent Tools"
+        ],
+        "summary": "Platform-default web search fallback",
+        "description": "Called on the agent's own token (not a Shroud-internal callback). Used by the runtime `web_search` tool when an agent has no BRAVE_API_KEY/TAVILY_API_KEY/SERP_API_KEY/ONECLAW_WEB_SEARCH_BINDING of its own — proxies to a shared, platform-provided Brave Search key under a hard monthly platform-wide cap.\n",
+        "operationId": "agentWebSearch",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "query"
+                ],
+                "properties": {
+                  "query": {
+                    "type": "string",
+                    "maxLength": 500
+                  },
+                  "num_results": {
+                    "type": "integer",
+                    "default": 5
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Search results",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WebSearchResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "description": "Called on a non-agent token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/memory/shared-namespaces": {
       "get": {
         "tags": [
@@ -36671,6 +37351,11 @@
             "type": "string",
             "format": "uuid",
             "description": "Approval satisfying an `agent.create` control-plane consensus policy,\nif the org has one. Same field and meaning as on `POST /v1/agents`:\nthe first call returns 202 with the approval to collect, and the\nretry passes its id here.\n"
+          },
+          "guided": {
+            "type": "boolean",
+            "default": false,
+            "description": "Seeds `getting-started/**` instead of `examples/**` in the shared\n`default` vault — the guided onboarding wizard's own sample content,\nkept distinguishable from the MCP-connect developer flow's.\n"
           }
         }
       },
@@ -36703,6 +37388,104 @@
           }
         }
       },
+      "GuidedOnboardingStatus": {
+        "allOf": [
+          {
+            "type": "object",
+            "required": [
+              "eligible"
+            ],
+            "properties": {
+              "eligible": {
+                "type": "boolean",
+                "description": "Whether this org is in the guided-onboarding rollout cohort —\ndecides whether the dashboard redirects a new user here or to\nthe MCP-connect flow.\n"
+              }
+            }
+          },
+          {
+            "$ref": "#/components/schemas/OnboardingStatus"
+          }
+        ]
+      },
+      "GuidedAskRequest": {
+        "type": "object",
+        "required": [
+          "question"
+        ],
+        "properties": {
+          "question": {
+            "type": "string",
+            "maxLength": 500
+          },
+          "step": {
+            "type": "integer",
+            "description": "Accepted but not yet used to tailor the answer; reserved for later."
+          }
+        }
+      },
+      "GuidedAskResponse": {
+        "type": "object",
+        "required": [
+          "answer"
+        ],
+        "properties": {
+          "answer": {
+            "type": "string"
+          }
+        }
+      },
+      "TrialSetupIntentResponse": {
+        "type": "object",
+        "required": [
+          "client_secret",
+          "publishable_key"
+        ],
+        "properties": {
+          "client_secret": {
+            "type": "string"
+          },
+          "publishable_key": {
+            "type": "string"
+          }
+        }
+      },
+      "CreateTrialRuntimeRequest": {
+        "type": "object",
+        "required": [
+          "setup_intent_id",
+          "agent_id",
+          "template",
+          "name"
+        ],
+        "properties": {
+          "setup_intent_id": {
+            "type": "string"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "template": {
+            "type": "string"
+          },
+          "preset": {
+            "type": "string",
+            "description": "Defaults to CreateRuntimeRequest's own default (\"small\") when omitted."
+          },
+          "name": {
+            "type": "string"
+          },
+          "always_on": {
+            "type": "boolean",
+            "default": false,
+            "description": "Keeps the runtime running indefinitely instead of auto-stopping after the\ndefault idle window (maps to `idle_timeout_secs: 0`).\n"
+          },
+          "env_public": {
+            "type": "object",
+            "description": "Non-secret runtime config — in practice just `LLM_PROVIDER`/`LLM_MODEL`\nfrom the guided flow's model-choice step. Rejected if any key looks\nsecret-shaped (same `validate_env_public` the canonical runtime API uses).\n"
+          }
+        }
+      },
       "AgentKeysVaultResponse": {
         "type": "object",
         "properties": {
@@ -43641,6 +44424,398 @@
           }
         }
       },
+      "LlmModelPrice": {
+        "type": "object",
+        "required": [
+          "id",
+          "provider",
+          "model_pattern",
+          "input_micro_usd_per_mtok",
+          "output_micro_usd_per_mtok",
+          "source",
+          "updated_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true,
+            "description": "Null for a global row."
+          },
+          "provider": {
+            "type": "string"
+          },
+          "model_pattern": {
+            "type": "string"
+          },
+          "input_micro_usd_per_mtok": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "output_micro_usd_per_mtok": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "source": {
+            "type": "string"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "AiSpendTotals": {
+        "type": "object",
+        "properties": {
+          "cost_usd": {
+            "type": "number"
+          },
+          "tokens_input": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "tokens_output": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "tokens": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "requests": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "blocked": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "unpriced_requests": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "agents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "models": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "avg_cost_per_day": {
+            "type": "number"
+          },
+          "cost_per_request": {
+            "type": "number"
+          },
+          "cost_per_mtok": {
+            "type": "number"
+          }
+        }
+      },
+      "AiSpend": {
+        "type": "object",
+        "required": [
+          "window",
+          "totals",
+          "previous",
+          "series",
+          "by_provider",
+          "by_model",
+          "by_agent",
+          "limits",
+          "generated_at"
+        ],
+        "properties": {
+          "generated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "window": {
+            "type": "object",
+            "properties": {
+              "from": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "to": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "interval": {
+                "type": "string"
+              },
+              "previous_from": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "previous_to": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "days": {
+                "type": "number"
+              }
+            }
+          },
+          "totals": {
+            "$ref": "#/components/schemas/AiSpendTotals"
+          },
+          "previous": {
+            "$ref": "#/components/schemas/AiSpendTotals"
+          },
+          "series": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "bucket": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "provider": {
+                  "type": "string"
+                },
+                "cost_usd": {
+                  "type": "number"
+                },
+                "tokens": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "requests": {
+                  "type": "integer",
+                  "format": "int64"
+                }
+              }
+            }
+          },
+          "by_provider": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "provider": {
+                  "type": "string"
+                },
+                "cost_usd": {
+                  "type": "number"
+                },
+                "tokens": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "requests": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "previous_cost_usd": {
+                  "type": "number"
+                },
+                "share_pct": {
+                  "type": "number"
+                },
+                "trend_pct": {
+                  "type": "number",
+                  "nullable": true
+                }
+              }
+            }
+          },
+          "by_model": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "provider": {
+                  "type": "string"
+                },
+                "model": {
+                  "type": "string"
+                },
+                "cost_usd": {
+                  "type": "number"
+                },
+                "tokens_input": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "tokens_output": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "requests": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "previous_cost_usd": {
+                  "type": "number"
+                },
+                "priced": {
+                  "type": "boolean"
+                },
+                "share_pct": {
+                  "type": "number"
+                },
+                "trend_pct": {
+                  "type": "number",
+                  "nullable": true
+                }
+              }
+            }
+          },
+          "by_agent": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "agent_id": {
+                  "type": "string",
+                  "format": "uuid"
+                },
+                "agent_name": {
+                  "type": "string"
+                },
+                "is_active": {
+                  "type": "boolean"
+                },
+                "cost_usd": {
+                  "type": "number"
+                },
+                "tokens": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "requests": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "blocked": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "top_model": {
+                  "type": "string",
+                  "nullable": true
+                },
+                "top_provider": {
+                  "type": "string",
+                  "nullable": true
+                },
+                "previous_cost_usd": {
+                  "type": "number"
+                },
+                "last_request_at": {
+                  "type": "string",
+                  "format": "date-time",
+                  "nullable": true
+                },
+                "daily_budget_usd": {
+                  "type": "number",
+                  "nullable": true
+                },
+                "today_cost_usd": {
+                  "type": "number"
+                },
+                "blocked_by_budget": {
+                  "type": "integer",
+                  "format": "int64"
+                },
+                "max_tokens_per_request": {
+                  "type": "integer",
+                  "format": "int64",
+                  "nullable": true
+                },
+                "max_requests_per_day": {
+                  "type": "integer",
+                  "format": "int64",
+                  "nullable": true
+                },
+                "share_pct": {
+                  "type": "number"
+                },
+                "trend_pct": {
+                  "type": "number",
+                  "nullable": true
+                },
+                "budget_used_pct": {
+                  "type": "number",
+                  "nullable": true
+                }
+              }
+            }
+          },
+          "limits": {
+            "type": "object",
+            "properties": {
+              "agents_with_daily_budget": {
+                "type": "integer",
+                "format": "int64"
+              },
+              "agents_over_80pct": {
+                "type": "integer",
+                "format": "int64"
+              },
+              "agents_at_cap": {
+                "type": "integer",
+                "format": "int64"
+              },
+              "blocked_by_budget": {
+                "type": "integer",
+                "format": "int64"
+              },
+              "router_keys": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "key_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "agent_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "agent_name": {
+                      "type": "string"
+                    },
+                    "name": {
+                      "type": "string"
+                    },
+                    "spent_usd": {
+                      "type": "number"
+                    },
+                    "cap_usd": {
+                      "type": "number",
+                      "nullable": true
+                    },
+                    "last_used_at": {
+                      "type": "string",
+                      "format": "date-time",
+                      "nullable": true
+                    }
+                  }
+                }
+              },
+              "credit_balance_usd": {
+                "type": "number"
+              },
+              "inspection_fees_usd": {
+                "type": "number"
+              },
+              "billing_tier": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
       "OrgOverview": {
         "type": "object",
         "required": [
@@ -48498,6 +49673,132 @@
             "type": "boolean"
           }
         }
+      },
+      "GrowthCountBucket": {
+        "type": "object",
+        "required": [
+          "bucket",
+          "count"
+        ],
+        "properties": {
+          "bucket": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "count": {
+            "type": "integer"
+          }
+        }
+      },
+      "GrowthTimeseriesResponse": {
+        "type": "object",
+        "required": [
+          "vertical",
+          "period",
+          "bucket_unit",
+          "points",
+          "total",
+          "prior_total"
+        ],
+        "properties": {
+          "vertical": {
+            "type": "string"
+          },
+          "period": {
+            "type": "string"
+          },
+          "bucket_unit": {
+            "type": "string",
+            "enum": [
+              "hour",
+              "day",
+              "week"
+            ]
+          },
+          "points": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/GrowthCountBucket"
+            }
+          },
+          "total": {
+            "type": "integer"
+          },
+          "prior_total": {
+            "type": "integer"
+          },
+          "delta_pct": {
+            "type": "number",
+            "nullable": true,
+            "description": "Null when both the current and prior totals are 0."
+          },
+          "notes": {
+            "type": "string",
+            "nullable": true,
+            "description": "A known limitation worth surfacing for this vertical (e.g. a source table with no org_id to exclude test-fixture activity from). Null for the clean verticals.\n"
+          }
+        }
+      },
+      "RetentionResponse": {
+        "type": "object",
+        "required": [
+          "window_days",
+          "cohort_orgs",
+          "retained_orgs"
+        ],
+        "properties": {
+          "window_days": {
+            "type": "integer"
+          },
+          "cohort_orgs": {
+            "type": "integer"
+          },
+          "retained_orgs": {
+            "type": "integer"
+          },
+          "retention_pct": {
+            "type": "number",
+            "nullable": true,
+            "description": "Null when there is no cohort yet (platform younger than the window)."
+          }
+        }
+      },
+      "WebSearchResult": {
+        "type": "object",
+        "required": [
+          "title",
+          "url",
+          "snippet"
+        ],
+        "properties": {
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "snippet": {
+            "type": "string"
+          }
+        }
+      },
+      "WebSearchResponse": {
+        "type": "object",
+        "required": [
+          "results",
+          "provider"
+        ],
+        "properties": {
+          "results": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/WebSearchResult"
+            }
+          },
+          "provider": {
+            "type": "string"
+          }
+        }
       }
     }
   }