@1claw/openapi-spec 0.61.40 → 0.61.41

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.40",
+    "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"
@@ -222,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": {
@@ -2911,7 +2915,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.0075"
+          "price": "0.0225"
         },
         "parameters": [
           {
@@ -2964,7 +2968,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.0015"
+          "price": "0.0045"
         },
         "parameters": [
           {
@@ -4116,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",
@@ -4287,7 +4292,8 @@
           "protocols": [
             "x402"
           ],
-          "pricingMode": "quote"
+          "pricingMode": "fixed",
+          "price": "0.225"
         },
         "parameters": [
           {
@@ -4342,7 +4348,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.075"
+          "price": "0.225"
         },
         "parameters": [
           {
@@ -4397,7 +4403,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.075"
+          "price": "0.225"
         },
         "parameters": [
           {
@@ -6407,7 +6413,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.003"
+          "price": "0.009"
         },
         "parameters": [
           {
@@ -6466,7 +6472,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.0015"
+          "price": "0.0045"
         },
         "parameters": [
           {
@@ -7049,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": [
@@ -7906,7 +8020,7 @@
             "x402"
           ],
           "pricingMode": "fixed",
-          "price": "0.0008"
+          "price": "0.0024"
         },
         "parameters": [
           {
@@ -12298,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": [
@@ -18234,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": [
@@ -27927,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": [
@@ -36970,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"
           }
         }
       },
@@ -37002,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": {
@@ -49189,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"
+          }
+        }
       }
     }
   }

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.40"
+    version: "0.61.41"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -142,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
@@ -1979,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"
@@ -2009,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"
@@ -2734,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
@@ -2845,7 +2848,8 @@ paths:
                 mode: paid
             x-payment-info:
                 protocols: [x402]
-                pricingMode: quote
+                pricingMode: fixed
+                price: "0.225"
             parameters:
                 - $ref: "#/components/parameters/AgentId"
             requestBody:
@@ -2878,7 +2882,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.075"
+                price: "0.225"
             parameters:
                 - $ref: "#/components/parameters/AgentId"
             requestBody:
@@ -2911,7 +2915,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.075"
+                price: "0.225"
             parameters:
                 - $ref: "#/components/parameters/AgentId"
             requestBody:
@@ -4151,7 +4155,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.003"
+                price: "0.009"
             parameters:
                 - name: secret_id
                   in: path
@@ -4188,7 +4192,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.0015"
+                price: "0.0045"
             parameters:
                 - name: share_id
                   in: path
@@ -4556,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]
@@ -5115,7 +5204,7 @@ paths:
             x-payment-info:
                 protocols: [x402]
                 pricingMode: fixed
-                price: "0.0008"
+                price: "0.0024"
             parameters:
                 - name: resource_id
                   in: query
@@ -7797,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]
@@ -11595,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]
@@ -17864,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]
@@ -24016,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
@@ -24034,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:
@@ -31869,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1claw/openapi-spec",
-  "version": "0.61.40",
+  "version": "0.61.41",
   "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
   "license": "MIT",
   "repository": {