@idelio/contracts 0.1.0-beta.0 → 0.1.0-beta.1

package/openapi/openapi.yaml

@@ -22,7 +22,9 @@ paths:
   /me:
     get:
       operationId: getMe
-      summary: Return the authenticated user, their workspace and effective role.
+      summary: Get the current user
+      description: >-
+        Return the authenticated user, their workspace and effective role.
       responses:
         "200":
           description: User + workspace context
@@ -32,8 +34,10 @@ paths:
   /me/onboarding:
     post:
       operationId: completeOnboarding
-      summary: Record that the authenticated membership finished onboarding.
+      summary: Complete onboarding
       description: >-
+        Record that the authenticated membership finished onboarding.
+
         Idempotent. A repeat returns the stored timestamp rather than moving it,
         so a retry or a second tab cannot rewrite when a user was onboarded.
         Takes no request body - the only fact is that it happened, and the
@@ -53,11 +57,11 @@ paths:
           description: Authenticated with an API key, which has no membership.
           content:
             application/json:
-              schema: { $ref: "#/components/schemas/Error" }
+              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
   /workspace:
     get:
       operationId: getWorkspace
-      summary: Retrieve the current workspace.
+      summary: Get the workspace
       responses:
         "200":
           description: Workspace object
@@ -74,9 +78,12 @@ paths:
         "429": { $ref: "#/components/responses/RateLimited" }
     patch:
       operationId: updateWorkspace
-      description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: Update workspace name and settings.
+      summary: Update the workspace
+      description: >-
+        Update workspace name and settings.
+
+        Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       parameters:
         - name: Idempotency-Key
           in: header
@@ -105,7 +112,7 @@ paths:
   /workspace/members:
     get:
       operationId: listMembers
-      summary: List members and their roles.
+      summary: List members
       parameters:
         - { name: cursor, in: query, schema: { type: string } }
         - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
@@ -130,9 +137,15 @@ paths:
   /workspace/invitations:
     post:
       operationId: inviteMember
-      description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
+      # Team workspaces are phase 6: kept out of the published reference
+      # until the app can manage members (apps/docs drops x-internal).
+      x-internal: true
       security: [{ bearerAuth: [] }]
-      summary: Invite a user by email with a role.
+      summary: Invite a member
+      description: >-
+        Invite a user by email with a role.
+
+        Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       parameters:
         - name: Idempotency-Key
           in: header
@@ -167,9 +180,12 @@ paths:
   /workspace/members/{userId}:
     patch:
       operationId: changeMemberRole
+      # Team workspaces are phase 6: kept out of the published reference
+      # until the app can manage members (apps/docs drops x-internal).
+      x-internal: true
       description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: Change a member's role.
+      summary: Change a member's role
       parameters:
         - { name: userId, in: path, required: true, schema: { type: string } }
       requestBody:
@@ -196,9 +212,12 @@ paths:
         "429": { $ref: "#/components/responses/RateLimited" }
     delete:
       operationId: removeMember
+      # Team workspaces are phase 6: kept out of the published reference
+      # until the app can manage members (apps/docs drops x-internal).
+      x-internal: true
       description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: Remove a member from the workspace.
+      summary: Remove a member
       parameters:
         - { name: userId, in: path, required: true, schema: { type: string } }
       responses:
@@ -209,7 +228,7 @@ paths:
   /brands:
     get:
       operationId: listBrands
-      summary: List brands in the workspace.
+      summary: List brands
       parameters:
         - { name: status, in: query, schema: { type: string, enum: [draft, generating, ready, failed] } }
         - { name: q, in: query, schema: { type: string } }
@@ -235,7 +254,10 @@ paths:
         "429": { $ref: "#/components/responses/RateLimited" }
     post:
       operationId: createBrand
-      summary: Generate a new brand from a prompt or template (reserves credits, starts a durable workflow).
+      summary: Create a brand
+      description: >-
+        Generate a new brand from a prompt or template (reserves credits, starts
+        a durable workflow).
       parameters:
         - name: Idempotency-Key
           in: header
@@ -268,7 +290,10 @@ paths:
   /brands/surprise:
     post:
       operationId: surpriseBrief
-      summary: Generate a random brand idea to seed the creator's Describe step ("Surprise me") - free, not persisted.
+      summary: Generate a random brand idea
+      description: >-
+        Generate a random brand idea to seed the creator's Describe step
+        ("Surprise me") - free, not persisted.
       responses:
         "200":
           description: A freshly generated random brief
@@ -279,8 +304,10 @@ paths:
   /brands/directions:
     post:
       operationId: brandCreativeDirections
-      summary: Shortlist creative directions against a brief - free, not persisted.
+      summary: Shortlist creative directions
       description: >-
+        Shortlist creative directions against a brief - free, not persisted.
+
         Ranks the palette, typography and logo catalogs against the founder's
         own description so the Customize step suggests directions that suit
         their brand instead of a fixed order. Returns catalog ids only, never
@@ -306,8 +333,11 @@ paths:
   /brands/names:
     post:
       operationId: brandNameIdeas
-      summary: Generate brand name ideas for the creator's name generator - free, not persisted.
+      summary: Generate brand name ideas
       description: >-
+        Generate brand name ideas for the creator's name generator - free, not
+        persisted.
+
         Returns six brand name candidates in the requested style, each with a
         one-line hint explaining why it works. Pass the founder's own keyword
         and description to keep the ideas about their actual business. Free
@@ -330,7 +360,9 @@ paths:
   /brands/{id}:
     get:
       operationId: getBrand
-      summary: Retrieve a brand with its head version summary.
+      summary: Get a brand
+      description: >-
+        Retrieve a brand with its head version summary.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -350,7 +382,9 @@ paths:
         "429": { $ref: "#/components/responses/RateLimited" }
     patch:
       operationId: updateBrand
-      summary: Rename a brand, change its slug, or update generation locks.
+      summary: Update a brand
+      description: >-
+        Rename a brand, change its slug, or update generation locks.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       requestBody:
@@ -377,7 +411,9 @@ paths:
         "429": { $ref: "#/components/responses/RateLimited" }
     delete:
       operationId: deleteBrand
-      summary: Soft-delete a brand (never hard-deleted).
+      summary: Delete a brand
+      description: >-
+        Soft-delete a brand (never hard-deleted).
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -387,7 +423,7 @@ paths:
   /brands/{id}/assets:
     get:
       operationId: listBrandAssets
-      summary: List assets belonging to a brand.
+      summary: List a brand's assets
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: kind, in: query, schema: { type: string } }
@@ -419,7 +455,14 @@ paths:
         "429": { $ref: "#/components/responses/RateLimited" }
     post:
       operationId: expandBrand
-      summary: Expand a brand - generate additional assets from its frozen head DNA (every asset kind except logo, which has its own generate/approve path). custom_image requires custom_image_prompt and is never combined with other kinds in the same request; color_palette/font_pairing are likewise never combined with any other kind. mockup and hero_image are studio/elite only - flash has no model route for them.
+      summary: Expand a brand
+      description: >-
+        Expand a brand - generate additional assets from its frozen head DNA
+        (every asset kind except logo, which has its own generate/approve path).
+        custom_image requires custom_image_prompt and is never combined with
+        other kinds in the same request; color_palette/font_pairing are likewise
+        never combined with any other kind. mockup and hero_image are
+        studio/elite only - flash has no model route for them.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
@@ -446,7 +489,10 @@ paths:
   /brands/{id}/refine:
     post:
       operationId: refineBrandDna
-      summary: Free-text Creative Director chat edit to the brand's DNA (strategy/palette/typography); forks a new BrandVersion.
+      summary: Refine a brand's DNA
+      description: >-
+        Free-text Creative Director chat edit to the brand's DNA
+        (strategy/palette/typography); forks a new BrandVersion.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
@@ -473,7 +519,9 @@ paths:
   /brands/{id}/logo:
     get:
       operationId: getBrandLogo
-      summary: Redirect to the brand's logo file, as PNG or SVG.
+      summary: Get a brand's logo
+      description: >-
+        Redirect to the brand's logo file, as PNG or SVG.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: format, in: query, schema: { type: string, enum: [png, svg], default: png } }
@@ -506,7 +554,9 @@ paths:
   /brands/{id}/palette:
     get:
       operationId: getBrandPalette
-      summary: Export the palette as design tokens (inline).
+      summary: Get a brand's palette
+      description: >-
+        Export the palette as design tokens (inline).
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: format, in: query, schema: { type: string, enum: [json, css], default: json } }
@@ -526,7 +576,9 @@ paths:
   /brands/{id}/tokens:
     get:
       operationId: getBrandTokens
-      summary: Full W3C design-token document (inline).
+      summary: Get a brand's design tokens
+      description: >-
+        Full W3C design-token document (inline).
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -543,7 +595,9 @@ paths:
   /brands/{id}/dna:
     get:
       operationId: getBrandDna
-      summary: The frozen creative genome (brief + strategy) the brand reads from.
+      summary: Get a brand's DNA
+      description: >-
+        The frozen creative genome (brief + strategy) the brand reads from.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -560,7 +614,9 @@ paths:
   /brands/{id}/versions:
     get:
       operationId: listBrandVersions
-      summary: Version history (git-commit semantics) for the brand, newest first.
+      summary: List a brand's versions
+      description: >-
+        Version history (git-commit semantics) for the brand, newest first.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -578,7 +634,10 @@ paths:
   /brands/{id}/suggestions:
     get:
       operationId: getBrandSuggestions
-      summary: This week's Creative-Director suggestions for the dashboard - computed weekly per brand, cached.
+      summary: List a brand's suggestions
+      description: >-
+        This week's Creative-Director suggestions for the dashboard - computed
+        weekly per brand, cached.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -597,7 +656,10 @@ paths:
   /brands/{id}/suggestions/{kind}/generate:
     post:
       operationId: generateBrandSuggestion
-      summary: Start generating one of this week's suggestions - delegates entirely to POST /brands/{id}/assets.
+      summary: Generate a suggestion
+      description: >-
+        Start generating one of this week's suggestions - delegates entirely to
+        POST /brands/{id}/assets.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: kind, in: path, required: true, schema: { type: string } }
@@ -616,7 +678,13 @@ paths:
   /suggestions:
     get:
       operationId: listSuggestions
-      summary: The dashboard's cross-brand suggestions - up to 3 items from the 3 most recently active ready brands, mixed round-robin. Never 404/409; a workspace with nothing to suggest gets an empty list. A brand that owns every catalogue kind it can be offered contributes custom asset ideas (kind custom_image) instead.
+      summary: List suggestions
+      description: >-
+        The dashboard's cross-brand suggestions - up to 3 items from the 3 most
+        recently active ready brands, mixed round-robin. Never 404/409; a
+        workspace with nothing to suggest gets an empty list. A brand that owns
+        every catalogue kind it can be offered contributes custom asset ideas
+        (kind custom_image) instead.
       responses:
         "200":
           description: Suggestions
@@ -633,7 +701,11 @@ paths:
   /brands/{id}/versions/restore:
     post:
       operationId: restoreBrandVersion
-      summary: Restore a prior brand DNA version as the current version (creates a new version, like git revert - nothing is edited in place). Asset versions are untouched.
+      summary: Restore a brand version
+      description: >-
+        Restore a prior brand DNA version as the current version (creates a new
+        version, like git revert - nothing is edited in place). Asset versions
+        are untouched.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
@@ -655,7 +727,9 @@ paths:
   /brands/{id}/export:
     get:
       operationId: exportBrandKit
-      summary: Package the full brand kit as a ZIP (async, always repackaged fresh).
+      summary: Export a brand kit
+      description: >-
+        Package the full brand kit as a ZIP (async, always repackaged fresh).
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: include, in: query, schema: { type: string }, description: "Comma-separated asset kinds, e.g. logo,color_palette. Omit for all." }
@@ -670,7 +744,11 @@ paths:
   /brands/{id}/bundle:
     get:
       operationId: getBrandBundle
-      summary: Repo-ready package (tokens, CSS/framework config, logo/favicon) for a target toolchain - deterministic per brand+target; 302 if already built, 202 otherwise.
+      summary: Get a brand bundle
+      description: >-
+        Repo-ready package (tokens, CSS/framework config, logo/favicon) for a
+        target toolchain - deterministic per brand+target; 302 if already built,
+        202 otherwise.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: target, in: query, schema: { type: string, enum: [tokens, next, vite, expo], default: tokens } }
@@ -697,7 +775,7 @@ paths:
   /brands/{id}/guidelines:
     get:
       operationId: getBrandGuidelines
-      summary: Download the brand guidelines PDF.
+      summary: Get the brand guidelines PDF
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -707,7 +785,7 @@ paths:
   /jobs:
     get:
       operationId: listJobs
-      summary: List generation jobs in the workspace.
+      summary: List jobs
       parameters:
         - { name: status, in: query, schema: { type: string, enum: [queued, running, completed, failed, canceled] } }
         - { name: brand_id, in: query, schema: { type: string } }
@@ -733,7 +811,9 @@ paths:
   /jobs/{id}:
     get:
       operationId: getJob
-      summary: Get job status and per-step progress.
+      summary: Get a job
+      description: >-
+        Get job status and per-step progress.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -751,8 +831,10 @@ paths:
   /jobs/{id}/events:
     get:
       operationId: streamJobEvents
-      summary: Subscribe to the job's SSE event stream (text/event-stream).
+      summary: Stream job events
       description: >-
+        Subscribe to the job's SSE event stream (text/event-stream).
+
         Emits `stream.connected`, then `job.step.started`/`job.step.completed`
         (skipped steps carry `"skipped": true`), interleaved with `asset.ready`
         (payload `{asset_id, kind}`) whenever a generated asset becomes
@@ -775,12 +857,18 @@ paths:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: Last-Event-ID, in: header, schema: { type: string } }
       responses:
-        "200": { description: text/event-stream }
+        "200":
+          description: Server-sent events stream of job progress (asset.ready, job.step.*, job.completed, job.failed).
+          content:
+            text/event-stream:
+              schema: { type: string }
         "404": { description: Not found }
   /jobs/{id}/cancel:
     post:
       operationId: cancelJob
-      summary: Cancel a running job; the reservation is refunded on the ledger.
+      summary: Cancel a job
+      description: >-
+        Cancel a running job; the reservation is refunded on the ledger.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -799,7 +887,9 @@ paths:
   /jobs/{id}/logo-selection:
     post:
       operationId: selectLogoConcept
-      summary: Approve one of the generated logo concepts; resumes the paused workflow.
+      summary: Select a logo concept
+      description: >-
+        Approve one of the generated logo concepts; resumes the paused workflow.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       requestBody:
@@ -826,11 +916,12 @@ paths:
   /jobs/{id}/logo-concepts/{assetVersionId}/preview:
     get:
       operationId: previewLogoConceptLockup
-      summary: >-
+      summary: Preview a logo concept lockup
+      description: >-
         A free, instant redirect to a preview render of one logo concept in a
-        different arrangement and/or font - never persisted, never charged,
-        no Idempotency-Key. Query params are both optional; omitting one
-        previews with that concept's own current value.
+        different arrangement and/or font - never persisted, never charged, no
+        Idempotency-Key. Query params are both optional; omitting one previews
+        with that concept's own current value.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: assetVersionId, in: path, required: true, schema: { type: string } }
@@ -856,7 +947,8 @@ paths:
   /jobs/{id}/logo-concepts/{assetVersionId}/palette:
     get:
       operationId: getLogoConceptPalette
-      summary: >-
+      summary: Get a logo concept's palette
+      description: >-
         The brand's generated DNA palette tokens, for the picker's colour
         override swatches - free, read-only.
       parameters:
@@ -872,7 +964,11 @@ paths:
   /jobs/{id}/assets/{kind}/retry:
     post:
       operationId: retryJobAsset
-      summary: Retry one failed or credit-blocked asset within an in-progress generation job, for free.
+      summary: Retry a failed asset
+      description: >-
+        Retry one failed or credit-blocked asset within an in-progress
+        generation job. The failed attempt was already refunded, so the
+        asset's price is charged once, and only if the retry succeeds.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: kind, in: path, required: true, schema: { type: string } }
@@ -893,7 +989,9 @@ paths:
   /assets/{id}:
     get:
       operationId: getAsset
-      summary: Retrieve a single asset with its current version.
+      summary: Get an asset
+      description: >-
+        Retrieve a single asset with its current version.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -913,7 +1011,9 @@ paths:
         "429": { $ref: "#/components/responses/RateLimited" }
     delete:
       operationId: deleteAsset
-      summary: Remove an asset from the brand library.
+      summary: Delete an asset
+      description: >-
+        Remove an asset from the brand library.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -923,8 +1023,10 @@ paths:
   /assets/{id}/qa:
     get:
       operationId: getAssetQaReport
-      summary: Get the Pixel Check QA report (per-dimension scores).
+      summary: Get an asset's QA report
       description: >-
+        Get the Pixel Check QA report (per-dimension scores).
+
         Supported for API consumers regardless of what the Idelio app UI
         currently renders. No in-app screen shows this report today - see
         QaReport's own description for why - but the endpoint and the data
@@ -953,9 +1055,10 @@ paths:
   /assets/{id}/download:
     get:
       operationId: downloadAsset
-      summary: Redirect to a time-limited signed CDN URL, or return it as JSON
-        with `redirect=false`.
+      summary: Download an asset
       description: |
+        Redirect to a time-limited signed CDN URL, or return it as JSON
+
         `redirect=false` returns `{ url }` as JSON instead of a 302. A
         browser `fetch()` that then requests that URL directly - rather than
         following our own 302 to it - keeps its real Origin header on the
@@ -1000,10 +1103,10 @@ paths:
   /assets/{id}/versions/{versionId}/download:
     get:
       operationId: downloadAssetVersion
-      summary: Redirect to a time-limited signed CDN URL for a SPECIFIC version - unlike
-        /assets/{id}/download (always the current version), this previews any version of
-        this asset, selected or not (e.g. a logo concept awaiting the human pick).
-        `redirect=false` returns it as JSON instead - see /assets/{id}/download.
+      summary: Download an asset version
+      description: >-
+        Redirect to a time-limited signed CDN URL for a SPECIFIC version -
+        unlike
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: versionId, in: path, required: true, schema: { type: string } }
@@ -1040,11 +1143,9 @@ paths:
   /assets/{id}/download-all:
     get:
       operationId: downloadAllAssetFiles
-      summary: Zip every file of the current version together and redirect to a
-        time-limited signed CDN URL for the ZIP - unlike /assets/{id}/download
-        (one file, chosen by `format`), this bundles all of them, one entry
-        per file, so "Download all files" stops silently picking one.
-        `redirect=false` returns it as JSON instead - see /assets/{id}/download.
+      summary: Download all asset files
+      description: >-
+        Zip every file of the current version together and redirect to a
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: redirect, in: query, schema: { type: boolean, default: true } }
@@ -1064,7 +1165,10 @@ paths:
   /assets/{id}/versions:
     get:
       operationId: listAssetVersions
-      summary: List an asset's versions (e.g. logo concepts awaiting selection, or version history).
+      summary: List an asset's versions
+      description: >-
+        List an asset's versions (e.g. logo concepts awaiting selection, or
+        version history).
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -1089,7 +1193,10 @@ paths:
   /assets/{id}/regenerate:
     post:
       operationId: regenerateAsset
-      summary: Regenerate an asset's concepts (2 free per asset, then 25% of its base price).
+      summary: Regenerate an asset
+      description: >-
+        Regenerate an asset's concepts (2 free per asset, then 25% of its base
+        price).
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
@@ -1112,8 +1219,11 @@ paths:
   /assets/{id}/refine:
     post:
       operationId: refineAsset
-      summary: Refine an asset - a free-text instruction, or font/accent/style overrides for `logo_wordmark`.
+      summary: Refine an asset
       description: >-
+        Refine an asset - a free-text instruction, or font/accent/style
+        overrides for `logo_wordmark`.
+
         For `logo`, sends a free-text instruction. For `logo_wordmark`, sends
         either a free-text instruction or structured treatment overrides (font
         family, accent color, style seed) - an instruction is resolved to
@@ -1152,7 +1262,9 @@ paths:
   /assets/{id}/logo-treatment:
     get:
       operationId: getLogoTreatment
-      summary: Read a wordmark/logo's current treatment (font, accent, style).
+      summary: Get a logo treatment
+      description: >-
+        Read a wordmark/logo's current treatment (font, accent, style).
       tags: [Assets]
       security: [{ bearerAuth: [] }, { apiKeyAuth: [] }]
       parameters:
@@ -1164,11 +1276,12 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/LogoTreatment" }
         "404":
-          $ref: "#/components/responses/NotFound"
+          description: Not found
   /assets/{id}/logo-treatment/preview:
     get:
       operationId: previewLogoTreatment
-      summary: >-
+      summary: Preview a logo treatment
+      description: >-
         A free, instant redirect to a preview render of a wordmark with
         different font/accent/style - never persisted, never charged, no
         Idempotency-Key. Query params are optional; omitting one previews with
@@ -1196,7 +1309,7 @@ paths:
         "302":
           description: Redirect to a signed CDN URL for the rendered preview (default).
         "404":
-          $ref: "#/components/responses/NotFound"
+          description: Not found
         "422":
           description: Invalid query parameters.
         "503":
@@ -1204,7 +1317,10 @@ paths:
   /assets/{id}/variations:
     post:
       operationId: variationsAsset
-      summary: Generate a curated preset variation of a logo (always logo-kind, counts against the 2-free-regens budget).
+      summary: Generate a logo variation
+      description: >-
+        Generate a curated preset variation of a logo (always logo-kind, counts
+        against the 2-free-regens budget).
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
@@ -1232,7 +1348,10 @@ paths:
   /assets/{id}/restore:
     post:
       operationId: restoreAsset
-      summary: Restore a prior asset version as the current version (creates a new version, like git revert - nothing is edited in place).
+      summary: Restore an asset version
+      description: >-
+        Restore a prior asset version as the current version (creates a new
+        version, like git revert - nothing is edited in place).
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
         - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
@@ -1257,7 +1376,9 @@ paths:
   /credits/balance:
     get:
       operationId: getCreditBalance
-      summary: Get the current balance, plan and renewal date.
+      summary: Get the credit balance
+      description: >-
+        Get the current balance, plan and renewal date.
       responses:
         "200":
           description: Balance summary
@@ -1267,7 +1388,9 @@ paths:
   /credits/ledger:
     get:
       operationId: listCreditLedger
-      summary: List the workspace's append-only credit ledger entries.
+      summary: List ledger entries
+      description: >-
+        List the workspace's append-only credit ledger entries.
       parameters:
         - { name: reason, in: query, schema: { type: string, enum: [grant, purchase, reserve, settle, refund, clawback] } }
         - { name: cursor, in: query, schema: { type: string } }
@@ -1281,7 +1404,9 @@ paths:
   /ai-teams:
     get:
       operationId: listAiTeams
-      summary: List the AI team tiers and their credit multipliers.
+      summary: List AI teams
+      description: >-
+        List the AI team tiers and their credit multipliers.
       responses:
         "200":
           description: AI team tiers
@@ -1296,7 +1421,9 @@ paths:
   /healthz:
     get:
       operationId: healthz
-      summary: Liveness and dependency health probe (unversioned in prod routing).
+      summary: Check health
+      description: >-
+        Liveness and dependency health probe (unversioned in prod routing).
       security: []
       responses:
         "200": { description: Healthy }
@@ -1304,7 +1431,9 @@ paths:
   /waitlist:
     post:
       operationId: joinWaitlist
-      summary: Join the public waitlist. No authentication required.
+      summary: Join the waitlist
+      description: >-
+        Join the public waitlist. No authentication required.
       security: []
       requestBody:
         required: true
@@ -1327,14 +1456,15 @@ paths:
   /consent:
     post:
       operationId: recordConsent
-      summary: >-
+      summary: Record consent
+      description: >-
         Record proof of cookie/privacy/Terms consent, or of what a checkout
         confirmation step disclosed. Cookie and privacy records need no
-        authentication (client_id is the caller's anonymous/session
-        identifier), and a purchase disclosure is sent with a session so it
-        attributes to the workspace. A terms_acceptance REQUIRES a session and
-        is refused with 401 without one: a record scoped to no workspace could
-        never be read back, so an anonymous one would evidence nothing.
+        authentication (client_id is the caller's anonymous/session identifier),
+        and a purchase disclosure is sent with a session so it attributes to the
+        workspace. A terms_acceptance REQUIRES a session and is refused with 401
+        without one: a record scoped to no workspace could never be read back,
+        so an anonymous one would evidence nothing.
       security: []
       requestBody:
         required: true
@@ -1371,7 +1501,9 @@ paths:
   /api-keys:
     get:
       operationId: listApiKeys
-      summary: List the workspace's API keys (non-revoked only).
+      summary: List API keys
+      description: >-
+        List the workspace's API keys (non-revoked only).
       responses:
         "200":
           description: API keys
@@ -1390,9 +1522,12 @@ paths:
         "429": { $ref: "#/components/responses/RateLimited" }
     post:
       operationId: createApiKey
-      description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: Mint a new API key. The secret is shown only in this response.
+      summary: Create an API key
+      description: >-
+        Mint a new API key. The secret is shown only in this response.
+
+        Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       requestBody:
         required: true
         content:
@@ -1414,9 +1549,12 @@ paths:
   /api-keys/{id}:
     delete:
       operationId: revokeApiKey
-      description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: Revoke an API key immediately.
+      summary: Revoke an API key
+      description: >-
+        Revoke an API key immediately.
+
+        Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -1427,7 +1565,9 @@ paths:
   /usage:
     get:
       operationId: getUsage
-      summary: Aggregate API-key usage for the workspace, bucketed by time.
+      summary: Get API usage
+      description: >-
+        Aggregate API-key usage for the workspace, bucketed by time.
       parameters:
         - { name: from, in: query, schema: { type: string, format: date-time } }
         - { name: to, in: query, schema: { type: string, format: date-time } }
@@ -1441,7 +1581,10 @@ paths:
   /webhook-endpoints:
     get:
       operationId: listWebhookEndpoints
-      summary: List the workspace's outbound webhook endpoints (secrets never included).
+      summary: List webhook endpoints
+      description: >-
+        List the workspace's outbound webhook endpoints (secrets never
+        included).
       responses:
         "200":
           description: Webhook endpoints
@@ -1460,8 +1603,12 @@ paths:
         "429": { $ref: "#/components/responses/RateLimited" }
     post:
       operationId: createWebhookEndpoint
-      description: A session needs at least the admin role; an API key needs the `webhooks:write` scope.
-      summary: Register a new outbound webhook endpoint. The signing secret is shown only in this response.
+      summary: Create a webhook endpoint
+      description: >-
+        Register a new outbound webhook endpoint. The signing secret is shown
+        only in this response.
+
+        A session needs at least the admin role; an API key needs the `webhooks:write` scope.
       requestBody:
         required: true
         content:
@@ -1483,8 +1630,11 @@ paths:
   /webhook-endpoints/{id}:
     patch:
       operationId: updateWebhookEndpoint
-      description: A session needs at least the admin role; an API key needs the `webhooks:write` scope.
-      summary: Update an endpoint's subscribed events, or enable/disable it.
+      summary: Update a webhook endpoint
+      description: >-
+        Update an endpoint's subscribed events, or enable/disable it.
+
+        A session needs at least the admin role; an API key needs the `webhooks:write` scope.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       requestBody:
@@ -1513,9 +1663,9 @@ paths:
       operationId: deleteWebhookEndpoint
       description: >-
         A session needs at least the admin role; an API key needs the `webhooks:write` scope.
-        The endpoint stops receiving events at once, including retries of a delivery already in
-        flight, and every later call naming it answers 404.
-      summary: Remove a webhook endpoint.
+        The endpoint stops receiving new events at once. A delivery already waiting on its retry
+        schedule makes at most one more attempt, then stops. Every later call naming it answers 404.
+      summary: Delete a webhook endpoint
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -1526,8 +1676,11 @@ paths:
   /webhook-endpoints/{id}/test:
     post:
       operationId: testWebhookEndpoint
-      description: A session needs at least the admin role; an API key needs the `webhooks:write` scope.
-      summary: Dispatch a synthetic test.ping event to the endpoint.
+      summary: Test a webhook endpoint
+      description: >-
+        Dispatch a synthetic test.ping event to the endpoint.
+
+        A session needs at least the admin role; an API key needs the `webhooks:write` scope.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -1546,15 +1699,47 @@ paths:
         "403": { description: Caller's role is below admin }
         "404": { description: No webhook endpoint with that id }
         "429": { $ref: "#/components/responses/RateLimited" }
+  /webhook-endpoints/{id}/deliveries:
+    get:
+      operationId: listWebhookDeliveries
+      summary: List an endpoint's deliveries
+      description: >-
+        The endpoint's recent deliveries, newest first, including test pings: what was
+        sent, how many attempts it took, and the last HTTP status or error.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: cursor, in: query, schema: { type: string } }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
+      responses:
+        "200":
+          description: A page of deliveries
+          headers:
+            X-RateLimit-Limit: { $ref: "#/components/headers/RateLimitLimit" }
+            X-RateLimit-Remaining: { $ref: "#/components/headers/RateLimitRemaining" }
+            X-RateLimit-Reset: { $ref: "#/components/headers/RateLimitReset" }
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, next_cursor, has_more]
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/WebhookDelivery" }
+                  next_cursor: { type: [string, "null"] }
+                  has_more: { type: boolean }
+        "404": { description: No webhook endpoint with that id }
+        "429": { $ref: "#/components/responses/RateLimited" }
   /webhooks/stripe:
     post:
       operationId: receiveStripeWebhook
-      summary: >-
-        Inbound Stripe event (checkout/invoice/subscription). HMAC-SHA256
-        signed via the Stripe-Signature header - not the same auth as the rest
-        of the API. Drives the credit ledger and workspace plan/entitlements.
-        Stripe is not Merchant of Record: SFER LABS LLC is the seller, so tax
-        and invoicing responsibility sits with us.
+      summary: Receive a Stripe event
+      description: >-
+        Inbound Stripe event (checkout/invoice/subscription). HMAC-SHA256 signed
+        via the Stripe-Signature header - not the same auth as the rest of the
+        API. Drives the credit ledger and workspace plan/entitlements. Stripe is
+        not Merchant of Record: SFER LABS LLC is the seller, so tax and
+        invoicing responsibility sits with us.
       security: []
       requestBody:
         required: true
@@ -1579,11 +1764,12 @@ paths:
   /webhooks/clerk:
     post:
       operationId: receiveClerkWebhook
-      summary: >-
+      summary: Receive a Clerk event
+      description: >-
         Inbound Clerk lifecycle event (organization.deleted,
-        organizationMembership.deleted, ...). Verified via svix
-        (svix-id/svix-timestamp/svix-signature headers) - not the same auth
-        as the rest of the API.
+        organizationMembership.deleted, ...). Verified via svix (svix-id/svix-
+        timestamp/svix-signature headers) - not the same auth as the rest of the
+        API.
       security: []
       requestBody:
         required: true
@@ -1607,9 +1793,12 @@ paths:
   /billing/subscription:
     get:
       operationId: getSubscription
-      description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: Get the active subscription and entitlements.
+      summary: Get the subscription
+      description: >-
+        Get the active subscription and entitlements.
+
+        Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       responses:
         "200":
           description: Subscription object
@@ -1630,9 +1819,12 @@ paths:
   /billing/checkout:
     post:
       operationId: createCheckout
-      description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: Create a checkout session for a plan or credit pack.
+      summary: Create a checkout session
+      description: >-
+        Create a checkout session for a plan or credit pack.
+
+        Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       parameters:
         - name: Idempotency-Key
           in: header
@@ -1668,8 +1860,10 @@ paths:
     get:
       operationId: getCheckoutSession
       security: [{ bearerAuth: [] }]
-      summary: Read whether a checkout has been applied to this workspace yet.
+      summary: Get a checkout session
       description: >
+        Read whether a checkout has been applied to this workspace yet.
+
         Available to a signed-in app session with at least the admin role; an
         API key receives 403 `session_required`.
         Reports settlement in Idelio, not at the payment provider. A plan
@@ -1698,13 +1892,15 @@ paths:
   /billing/subscription/change-plan:
     post:
       operationId: changeSubscriptionPlan
-      description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: >-
+      summary: Change the subscription plan
+      description: >-
         Switch an existing subscription to a different plan. Upgrades apply
-        immediately (prorated credits granted right away); downgrades are
-        queued for the end of the current billing period and reported back
-        via pending_plan/plan_change_effective_at.
+        immediately (prorated credits granted right away); downgrades are queued
+        for the end of the current billing period and reported back via
+        pending_plan/plan_change_effective_at.
+
+        Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       parameters:
         - name: Idempotency-Key
           in: header
@@ -1734,9 +1930,12 @@ paths:
   /billing/catalog:
     get:
       operationId: getBillingCatalog
-      description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: Resolve the active provider's price_id for every plan and top-up pack.
+      summary: Get the billing catalog
+      description: >-
+        Resolve the active provider's price_id for every plan and top-up pack.
+
+        Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       responses:
         "200":
           description: Provider-agnostic price catalog
@@ -1751,9 +1950,12 @@ paths:
   /billing/portal:
     post:
       operationId: createPortalSession
-      description: Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       security: [{ bearerAuth: [] }]
-      summary: Create a Stripe customer-portal session.
+      summary: Create a portal session
+      description: >-
+        Create a Stripe customer-portal session.
+
+        Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
       parameters:
         - name: Idempotency-Key
           in: header
@@ -1781,8 +1983,10 @@ paths:
     get:
       operationId: getPaymentMethod
       security: [{ bearerAuth: [] }]
-      summary: The card this workspace's charges land on.
+      summary: Get the payment method
       description: >
+        The card this workspace's charges land on.
+
         Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
         Returns null when there is no card on file - which is the normal state for a workspace
         that has never paid, and for a saved method that is not a card (PayPal, a bank debit).
@@ -1809,8 +2013,10 @@ paths:
     get:
       operationId: listInvoices
       security: [{ bearerAuth: [] }]
-      summary: List the workspace's invoices from Stripe.
+      summary: List invoices
       description: >
+        List the workspace's invoices from Stripe.
+
         Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
         Results are newest first. That order is inherited rather than pinned: Stripe's invoice
         list exposes no ordering parameter and orders by creation date, which is already newest
@@ -1843,8 +2049,10 @@ paths:
     get:
       operationId: getAutoTopup
       security: [{ bearerAuth: [] }]
-      summary: Get the workspace's auto top-up preference.
+      summary: Get auto top-up
       description: >-
+        Get the workspace's auto top-up preference.
+
         Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
         The stored preference only. Nothing acts on it yet: no automatic
         purchase is made when the balance runs low, for any workspace (#426).
@@ -1865,8 +2073,10 @@ paths:
     patch:
       operationId: updateAutoTopup
       security: [{ bearerAuth: [] }]
-      summary: Store the workspace's auto top-up preference.
+      summary: Update auto top-up
       description: >-
+        Store the workspace's auto top-up preference.
+
         Available to a signed-in app session with at least the admin role. An API key receives 403 `session_required`.
         Records the preference and the pack it names. It does NOT arrange a
         purchase: nothing reads these values, and no credits are ever bought
@@ -1895,7 +2105,7 @@ paths:
   /templates:
     get:
       operationId: listTemplates
-      summary: List available brand templates.
+      summary: List templates
       parameters:
         - { name: category, in: query, schema: { type: string } }
         - { name: cursor, in: query, schema: { type: string } }
@@ -1920,7 +2130,9 @@ paths:
   /templates/{id}:
     get:
       operationId: getTemplate
-      summary: Retrieve a template definition.
+      summary: Get a template
+      description: >-
+        Retrieve a template definition.
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
@@ -2989,6 +3201,13 @@ components:
           type: array
           items: { $ref: "#/components/schemas/WebhookEventType" }
         disabled: { type: boolean }
+        disabled_reason:
+          type: [string, "null"]
+          enum: [manual, failures, null]
+          description: >-
+            Why the endpoint is disabled. `failures` means 3 fully failed deliveries in a
+            row disabled it; re-enabling it with PATCH resets the count.
+        consecutive_failures: { type: integer }
         created_at: { type: string, format: date-time }
     WebhookEndpointWithSecret:
       allOf:
@@ -3017,10 +3236,22 @@ components:
       type: string
       enum:
         - brand.completed
-        - brand.updated
         - asset.ready
         - asset.regenerated
         - job.failed
         - credits.low
-        - credits.settled
-        - subscription.changed
+    WebhookDelivery:
+      type: object
+      properties:
+        id: { type: string }
+        event_id: { type: string }
+        event_type: { type: string }
+        status:
+          type: string
+          enum: [pending, delivered, failed]
+        attempt_count: { type: integer }
+        last_status_code: { type: [integer, "null"] }
+        last_error: { type: [string, "null"] }
+        payload: { type: object, additionalProperties: true }
+        created_at: { type: string, format: date-time }
+        delivered_at: { type: [string, "null"], format: date-time }