@1claw/openapi-spec 0.61.42 → 0.61.44

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.42",
+    "version": "0.61.44",
     "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"
@@ -28151,6 +28151,121 @@
         }
       }
     },
+    "/v1/billing/promo/preview": {
+      "get": {
+        "tags": [
+          "Billing"
+        ],
+        "summary": "What a promotion code does to a plan",
+        "description": "Public, and deliberately so: a promo advertised on social media is read by people who have no account yet, and the price they were promised has to be on the pricing page before they make one. It resolves a Stripe promotion code and one configured plan price; no tenant data is reachable through it.\n\nDistinct from `/v1/billing/promo/validate`, which answers for the `promo_codes` grants an authenticated org can redeem in place. This one describes a checkout discount, which needs a card and therefore has to go through `POST /v1/billing/subscribe` with `promo_code`.\n",
+        "operationId": "preview_promo",
+        "security": [],
+        "parameters": [
+          {
+            "name": "code",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "description": "The promotion code, as advertised."
+          },
+          {
+            "name": "tier",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "pro",
+                "team",
+                "business"
+              ],
+              "default": "pro"
+            }
+          },
+          {
+            "name": "interval",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "monthly",
+                "annual"
+              ],
+              "default": "monthly"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The offer, or why the code cannot be used. A code that does not apply answers 200 with `valid: false` and a message, not an error status — \"this code is not for annual billing\" is an answer, not a failure.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "valid",
+                    "tier",
+                    "interval"
+                  ],
+                  "properties": {
+                    "valid": {
+                      "type": "boolean"
+                    },
+                    "code": {
+                      "type": "string",
+                      "nullable": true,
+                      "description": "The code as Stripe stores it, not the caller's casing."
+                    },
+                    "headline": {
+                      "type": "string",
+                      "nullable": true,
+                      "description": "The offer in one sentence, derived from the coupon — e.g. \"$5/mo for your first 6 months, then $29/mo\". Rendered rather than composed by the client, so a page cannot advertise terms different from the ones charged.\n"
+                    },
+                    "tier": {
+                      "type": "string"
+                    },
+                    "interval": {
+                      "type": "string"
+                    },
+                    "list_cents": {
+                      "type": "integer",
+                      "nullable": true
+                    },
+                    "first_cents": {
+                      "type": "integer",
+                      "nullable": true,
+                      "description": "What the first invoice comes to, after the discount."
+                    },
+                    "duration_months": {
+                      "type": "integer",
+                      "nullable": true,
+                      "description": "How many invoices the discount covers."
+                    },
+                    "expires_at": {
+                      "type": "string",
+                      "format": "date-time",
+                      "nullable": true,
+                      "description": "Last moment the code can be redeemed. Someone who subscribes before this keeps the discount for its full length.\n"
+                    },
+                    "message": {
+                      "type": "string",
+                      "nullable": true
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Unknown tier or interval"
+          }
+        }
+      }
+    },
     "/v1/billing/promo/validate": {
       "get": {
         "tags": [
@@ -29544,6 +29659,62 @@
         }
       }
     },
+    "/v1/runtimes/{runtime_id}/agent-token/renew": {
+      "parameters": [
+        {
+          "name": "runtime_id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "post": {
+        "tags": [
+          "Runtimes"
+        ],
+        "summary": "Renew this runtime's own agent JWT before it expires",
+        "description": "Called by the runtime container itself, not by a human or an external client.\nA runtime's `ONECLAW_AGENT_TOKEN` is a short-lived JWT that Cloud Run resolves from Secret Manager when the instance starts and never again, so a container that outlives the TTL loses its credential — and with it every 1claw tool — until it is restarted. This lets it replace the token in place instead.\nAuthenticated by the credential being renewed: the caller must present a still-valid runtime-bound agent JWT together with a matching `X-1Claw-Runtime-Id` header, and must be the agent that runtime is bound to. It grants nothing new — the same claims with a later expiry — and stops working the moment the token lapses, the token is revoked, the agent is suspended, or the runtime is no longer deployed. Exempt from the monthly request quota: upkeep of an already-paid-for runtime is not itself a billable request.",
+        "operationId": "renew_runtime_agent_token",
+        "responses": {
+          "200": {
+            "description": "A fresh access token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "access_token": {
+                      "type": "string"
+                    },
+                    "expires_in": {
+                      "type": "integer"
+                    },
+                    "token_type": {
+                      "type": "string",
+                      "example": "Bearer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The runtime is not deployed, so it has nothing to renew"
+          },
+          "401": {
+            "description": "Unauthenticated, or the token presented has already expired"
+          },
+          "403": {
+            "description": "Not an agent caller"
+          },
+          "404": {
+            "description": "No such runtime, or it is not bound to this agent"
+          }
+        }
+      }
+    },
     "/v1/otel/stream": {
       "get": {
         "tags": [
@@ -30668,6 +30839,39 @@
         }
       }
     },
+    "/v1/runtimes/{runtime_id}/enable-recommended-tools": {
+      "parameters": [
+        {
+          "name": "runtime_id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "post": {
+        "tags": [
+          "Runtimes"
+        ],
+        "summary": "Enable the recommended tool set (image generation, web search, memory, Shroud, intents) on the runtime's agent. Human-only.",
+        "operationId": "enable_recommended_tools",
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "403": {
+            "description": "Forbidden, or the plan does not include this"
+          },
+          "404": {
+            "description": "Not found"
+          }
+        }
+      }
+    },
     "/v1/vaults/{vault_id}/secret-version-disable/{*path_and_version}": {
       "parameters": [
         {

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.42"
+    version: "0.61.44"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -18000,6 +18000,87 @@ paths:
                     description: Forbidden, or the plan does not include this
                 '404':
                     description: Not found
+    /v1/billing/promo/preview:
+        get:
+            tags: [Billing]
+            summary: "What a promotion code does to a plan"
+            description: >
+                Public, and deliberately so: a promo advertised on social media
+                is read by people who have no account yet, and the price they
+                were promised has to be on the pricing page before they make
+                one. It resolves a Stripe promotion code and one configured
+                plan price; no tenant data is reachable through it.
+
+
+                Distinct from `/v1/billing/promo/validate`, which answers for
+                the `promo_codes` grants an authenticated org can redeem in
+                place. This one describes a checkout discount, which needs a
+                card and therefore has to go through
+                `POST /v1/billing/subscribe` with `promo_code`.
+            operationId: preview_promo
+            security: []
+            parameters:
+                - name: code
+                  in: query
+                  required: true
+                  schema: { type: string, maxLength: 64 }
+                  description: The promotion code, as advertised.
+                - name: tier
+                  in: query
+                  required: false
+                  schema: { type: string, enum: [pro, team, business], default: pro }
+                - name: interval
+                  in: query
+                  required: false
+                  schema: { type: string, enum: [monthly, annual], default: monthly }
+            responses:
+                '200':
+                    description: >
+                        The offer, or why the code cannot be used. A code that
+                        does not apply answers 200 with `valid: false` and a
+                        message, not an error status — "this code is not for
+                        annual billing" is an answer, not a failure.
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [valid, tier, interval]
+                                properties:
+                                    valid: { type: boolean }
+                                    code:
+                                        type: string
+                                        nullable: true
+                                        description: The code as Stripe stores it, not the caller's casing.
+                                    headline:
+                                        type: string
+                                        nullable: true
+                                        description: >
+                                            The offer in one sentence, derived from the coupon —
+                                            e.g. "$5/mo for your first 6 months, then $29/mo".
+                                            Rendered rather than composed by the client, so a page
+                                            cannot advertise terms different from the ones charged.
+                                    tier: { type: string }
+                                    interval: { type: string }
+                                    list_cents: { type: integer, nullable: true }
+                                    first_cents:
+                                        type: integer
+                                        nullable: true
+                                        description: What the first invoice comes to, after the discount.
+                                    duration_months:
+                                        type: integer
+                                        nullable: true
+                                        description: How many invoices the discount covers.
+                                    expires_at:
+                                        type: string
+                                        format: date-time
+                                        nullable: true
+                                        description: >
+                                            Last moment the code can be redeemed. Someone who
+                                            subscribes before this keeps the discount for its
+                                            full length.
+                                    message: { type: string, nullable: true }
+                '400':
+                    description: Unknown tier or interval
     /v1/billing/promo/validate:
         get:
             tags: [Billing]
@@ -18893,6 +18974,58 @@ paths:
                     description: Forbidden, or the plan does not include this
                 '404':
                     description: Not found
+    /v1/runtimes/{runtime_id}/agent-token/renew:
+        parameters:
+            - name: runtime_id
+              in: path
+              required: true
+              schema:
+                  type: string
+        post:
+            tags: [Runtimes]
+            summary: "Renew this runtime's own agent JWT before it expires"
+            description: >-
+                Called by the runtime container itself, not by a human or an
+                external client.
+
+                A runtime's `ONECLAW_AGENT_TOKEN` is a short-lived JWT that Cloud
+                Run resolves from Secret Manager when the instance starts and
+                never again, so a container that outlives the TTL loses its
+                credential — and with it every 1claw tool — until it is
+                restarted. This lets it replace the token in place instead.
+
+                Authenticated by the credential being renewed: the caller must
+                present a still-valid runtime-bound agent JWT together with a
+                matching `X-1Claw-Runtime-Id` header, and must be the agent that
+                runtime is bound to. It grants nothing new — the same claims with
+                a later expiry — and stops working the moment the token lapses,
+                the token is revoked, the agent is suspended, or the runtime is
+                no longer deployed. Exempt from the monthly request quota: upkeep
+                of an already-paid-for runtime is not itself a billable request.
+            operationId: renew_runtime_agent_token
+            responses:
+                '200':
+                    description: A fresh access token
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    access_token:
+                                        type: string
+                                    expires_in:
+                                        type: integer
+                                    token_type:
+                                        type: string
+                                        example: Bearer
+                '400':
+                    description: The runtime is not deployed, so it has nothing to renew
+                '401':
+                    description: Unauthenticated, or the token presented has already expired
+                '403':
+                    description: Not an agent caller
+                '404':
+                    description: No such runtime, or it is not bound to this agent
     /v1/otel/stream:
         get:
             tags: [Observability]
@@ -19596,6 +19729,26 @@ paths:
                     description: Forbidden, or the plan does not include this
                 '404':
                     description: Not found
+    /v1/runtimes/{runtime_id}/enable-recommended-tools:
+        parameters:
+            - name: runtime_id
+              in: path
+              required: true
+              schema:
+                  type: string
+        post:
+            tags: [Runtimes]
+            summary: "Enable the recommended tool set (image generation, web search, memory, Shroud, intents) on the runtime's agent. Human-only."
+            operationId: enable_recommended_tools
+            responses:
+                '200':
+                    description: Success
+                '401':
+                    description: Unauthenticated
+                '403':
+                    description: Forbidden, or the plan does not include this
+                '404':
+                    description: Not found
     /v1/vaults/{vault_id}/secret-version-disable/{*path_and_version}:
         parameters:
             - name: vault_id

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@1claw/openapi-spec",
-  "version": "0.61.42",
-  "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
+  "version": "0.61.44",
+  "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
   "license": "MIT",
   "repository": {
     "type": "git",