@1claw/openapi-spec 0.61.39 → 0.61.41

package/openapi.yaml

@@ -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,
         policy-based access control, agent identity, Intents API,
@@ -70,6 +70,8 @@ tags:
       description: Secret sharing links
     - 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
     - name: Audit
@@ -140,6 +142,8 @@ tags:
       description: MFA/passkey/password recovery escape hatch with admin approval
     - 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
@@ -1977,7 +1981,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.0075"
+                price: "0.0225"
             parameters:
                 - $ref: "#/components/parameters/VaultId"
                 - $ref: "#/components/parameters/SecretPath"
@@ -2007,7 +2011,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.0015"
+                price: "0.0045"
             parameters:
                 - $ref: "#/components/parameters/VaultId"
                 - $ref: "#/components/parameters/SecretPath"
@@ -2732,7 +2736,8 @@ paths:
                 mode: paid
             x-payment-info:
                 protocols: [x402]
-                pricingMode: quote
+                pricingMode: fixed
+                price: "0.225"
             description: |
                 Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).
                 Duplicate requests with the same key within 24 hours return the cached transaction response
@@ -2843,7 +2848,8 @@ paths:
                 mode: paid
             x-payment-info:
                 protocols: [x402]
-                pricingMode: quote
+                pricingMode: fixed
+                price: "0.225"
             parameters:
                 - $ref: "#/components/parameters/AgentId"
             requestBody:
@@ -2876,7 +2882,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.075"
+                price: "0.225"
             parameters:
                 - $ref: "#/components/parameters/AgentId"
             requestBody:
@@ -2909,7 +2915,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.075"
+                price: "0.225"
             parameters:
                 - $ref: "#/components/parameters/AgentId"
             requestBody:
@@ -4149,7 +4155,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.003"
+                price: "0.009"
             parameters:
                 - name: secret_id
                   in: path
@@ -4186,7 +4192,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.0015"
+                price: "0.0045"
             parameters:
                 - name: share_id
                   in: path
@@ -4282,6 +4288,172 @@ paths:
     # Organization
     # ---------------------------------------------------------------------------
 
+    /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):
+                totals with the previous equal-length window for comparison, a time series
+                by provider, and breakdowns by provider, by model and by agent — each agent
+                with its `shroud_config` daily budget, today's spend against it and the
+                requests Shroud blocked for budget. `limits` carries router-key spend caps,
+                the credit balance and 1Claw's inspection fees for the window (a separate
+                number from provider cost). Every request is priced at ingest from the
+                price card (`GET /v1/spend/ai/prices`); a request whose provider has no
+                card is counted as unpriced, not free. Human and platform callers only.
+                Backs the dashboard's Spend tab; the same numbers reach an org's own
+                collector as OTEL metrics `ai.cost_usd`, `ai.tokens.input`, `ai.tokens.output`.
+            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
+                org's overrides. Matching: an org row beats a global row; among those the
+                longest `model_pattern` wins; a pattern ending in `%` is a prefix match.
+            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: [Organization]
@@ -4388,6 +4560,91 @@ paths:
                             schema:
                                 $ref: "#/components/schemas/OnboardingProvisionResponse"
 
+    /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
+                same welcome-bundle progress fields `GET /v1/org/onboarding/status`
+                reports. `eligible` decides whether the dashboard's redirect sends a
+                new, still-unprovisioned user to the guided flow or the existing
+                MCP-connect flow.
+            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.
+                Not tied to an agent (many questions arrive before one exists yet) and
+                not persisted as a conversation. The system prompt is fixed server-side
+                and refuses anything outside vaults/policies/runtimes/billing/channels —
+                never client-suppliable. Billed like any other Shroud LLM call: the
+                caller's own bearer token is forwarded so usage attributes to their org.
+            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
+                onboarding wizard can collect a card with Stripe.js — no charge unless
+                the trial runtime is kept past its trial window.
+            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
+                runtime-creation logic `POST /v1/runtimes` uses. Only reachable once
+                the guided onboarding wizard has a confirmed SetupIntent for the org.
+            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: [Organization]
@@ -4947,7 +5204,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.0008"
+                price: "0.0024"
             parameters:
                 - name: resource_id
                   in: query
@@ -7629,6 +7886,41 @@ paths:
                 "401":
                     description: Unauthorized
 
+    /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
+                requests and tokens and how many requests Shroud blocked for budget. Shroud
+                syncs its daily-budget counter from this so `daily_budget_usd` holds across
+                Shroud instances and restarts. Callable by the agent itself (its own id) or the
+                platform service key — the same gate as activity ingest.
+            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: [Shroud]
@@ -11427,6 +11719,106 @@ paths:
                 "403":
                     $ref: "#/components/responses/Forbidden"
 
+    /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.
+            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.
+            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: [Pay]
@@ -17696,6 +18088,47 @@ paths:
                     description: Forbidden, or the plan does not include this
                 '404':
                     description: Not found
+    /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.
+            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: [Memory]
@@ -23848,6 +24281,13 @@ components:
                         if the org has one. Same field and meaning as on `POST /v1/agents`:
                         the first call returns 202 with the approval to collect, and the
                         retry passes its id here.
+                guided:
+                    type: boolean
+                    default: false
+                    description: |
+                        Seeds `getting-started/**` instead of `examples/**` in the shared
+                        `default` vault — the guided onboarding wizard's own sample content,
+                        kept distinguishable from the MCP-connect developer flow's.
 
         OnboardingProvisionResponse:
             type: object
@@ -23866,6 +24306,75 @@ components:
                 verify_prompt:
                     type: string
 
+        GuidedOnboardingStatus:
+            allOf:
+                - type: object
+                  required: [eligible]
+                  properties:
+                      eligible:
+                          type: boolean
+                          description: |
+                              Whether this org is in the guided-onboarding rollout cohort —
+                              decides whether the dashboard redirects a new user here or to
+                              the MCP-connect flow.
+                - $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
+                        default idle window (maps to `idle_timeout_secs: 0`).
+                env_public:
+                    type: object
+                    description: |
+                        Non-secret runtime config — in practice just `LLM_PROVIDER`/`LLM_MODEL`
+                        from the guided flow's model-choice step. Rejected if any key looks
+                        secret-shaped (same `validate_env_public` the canonical runtime API uses).
+
         AgentKeysVaultResponse:
             type: object
             properties:
@@ -28262,6 +28771,138 @@ components:
                     format: uuid
                     description: Control-plane approval when rolling back to a wider spec.
 
+        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: [generated_at, window_hours, inventory, activity, spend, health, trend]
@@ -31569,3 +32210,81 @@ components:
             properties:
                 valid:
                     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.
+
+        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