@1claw/openapi-spec 0.61.43 → 0.61.45

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.43",
+    "version": "0.61.45",
     "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,261 @@
         }
       }
     },
+    "/v1/marketing/unsubscribe": {
+      "get": {
+        "tags": [
+          "Billing"
+        ],
+        "summary": "Unsubscribe an address from offers and announcements",
+        "description": "Public and session-less by necessity: the link lives in an email, and an unsubscribe that asks the reader to log in first is one they abandon — they mark the next message as spam instead, which costs the sending domain far more. The `t` parameter is an HMAC over the address, which is what stops a stranger unsubscribing somebody else.\n\nOffers and announcements only. Transactional mail — sign-in codes, approval requests, invitations, reports the recipient asked for — does not consult this flag and is unaffected; turning it off must never lock someone out of their account.\n\nIdempotent, and the answer is the same whether or not the address has an account. \"Stop emailing me\" is always answered \"done\", and a 404 here would tell a caller holding a valid token which addresses are registered.\n",
+        "operationId": "marketing_unsubscribe",
+        "security": [],
+        "parameters": [
+          {
+            "name": "email",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "email"
+            }
+          },
+          {
+            "name": "t",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "HMAC over the address, from the link."
+          },
+          {
+            "name": "c",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Campaign the link came from. Recorded, not trusted."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Unsubscribed (or already was)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "unsubscribed",
+                    "email",
+                    "message"
+                  ],
+                  "properties": {
+                    "unsubscribed": {
+                      "type": "boolean"
+                    },
+                    "email": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The link's signature did not verify"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Billing"
+        ],
+        "summary": "Unsubscribe (one-click)",
+        "description": "Identical to the GET. Present because `List-Unsubscribe-Post: List-Unsubscribe=One-Click` makes Gmail and Yahoo POST here without ever opening the page, and both require that header on bulk mail — an endpoint that only answered GET would look like a working unsubscribe to a person and a broken one to the providers scoring the domain.\n",
+        "operationId": "marketing_unsubscribe_post",
+        "security": [],
+        "parameters": [
+          {
+            "name": "email",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "email"
+            }
+          },
+          {
+            "name": "t",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "HMAC over the address, from the link."
+          },
+          {
+            "name": "c",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Campaign the link came from. Recorded, not trusted."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Unsubscribed (or already was)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "unsubscribed",
+                    "email",
+                    "message"
+                  ],
+                  "properties": {
+                    "unsubscribed": {
+                      "type": "boolean"
+                    },
+                    "email": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The link's signature did not verify"
+          }
+        }
+      }
+    },
+    "/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": [

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.43"
+    version: "0.61.45"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -18000,6 +18000,152 @@ paths:
                     description: Forbidden, or the plan does not include this
                 '404':
                     description: Not found
+    /v1/marketing/unsubscribe:
+        get: &marketing_unsubscribe
+            tags: [Billing]
+            summary: "Unsubscribe an address from offers and announcements"
+            description: >
+                Public and session-less by necessity: the link lives in an
+                email, and an unsubscribe that asks the reader to log in
+                first is one they abandon — they mark the next message as
+                spam instead, which costs the sending domain far more.
+                The `t` parameter is an HMAC over the address, which is what
+                stops a stranger unsubscribing somebody else.
+
+
+                Offers and announcements only. Transactional mail — sign-in
+                codes, approval requests, invitations, reports the recipient
+                asked for — does not consult this flag and is unaffected;
+                turning it off must never lock someone out of their account.
+
+
+                Idempotent, and the answer is the same whether or not the
+                address has an account. "Stop emailing me" is always
+                answered "done", and a 404 here would tell a caller holding
+                a valid token which addresses are registered.
+            operationId: marketing_unsubscribe
+            security: []
+            parameters:
+                - name: email
+                  in: query
+                  required: true
+                  schema: { type: string, format: email }
+                - name: t
+                  in: query
+                  required: true
+                  schema: { type: string }
+                  description: HMAC over the address, from the link.
+                - name: c
+                  in: query
+                  required: false
+                  schema: { type: string }
+                  description: Campaign the link came from. Recorded, not trusted.
+            responses:
+                '200':
+                    description: Unsubscribed (or already was)
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [unsubscribed, email, message]
+                                properties:
+                                    unsubscribed: { type: boolean }
+                                    email: { type: string }
+                                    message: { type: string }
+                '400':
+                    description: The link's signature did not verify
+        post:
+            <<: *marketing_unsubscribe
+            summary: "Unsubscribe (one-click)"
+            description: >
+                Identical to the GET. Present because
+                `List-Unsubscribe-Post: List-Unsubscribe=One-Click` makes
+                Gmail and Yahoo POST here without ever opening the page, and
+                both require that header on bulk mail — an endpoint that only
+                answered GET would look like a working unsubscribe to a
+                person and a broken one to the providers scoring the domain.
+            operationId: marketing_unsubscribe_post
+    /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]

package/package.json

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