@idelio/contracts 0.1.0-beta.0

package/openapi/openapi.yaml

@@ -0,0 +1,3026 @@
+# Idelio Public API - OpenAPI 3.1 (source of truth)
+# Full surface: 63 routes across 15 resource groups (see docs/API Specification v1.1).
+# This file starts with the core generation slice; extend additively only. One
+# route has ever been removed: POST /webhooks/paddle, when Paddle was retired
+# (#334). It was a signature-gated inbound callback that only Paddle itself
+# called, so no API client lost anything that worked - the additive-only rule
+# protects clients of this API, not a retired provider's callbacks.
+openapi: 3.1.0
+info:
+  title: Idelio API
+  version: 1.0.0
+  description: >
+    AI-native branding platform. Bearer auth (Clerk JWT or workspace API key
+    sk_live_/sk_test_). Idempotency-Key mandatory on paid generation routes.
+    Uniform error envelope on every 4xx/5xx. Cursor pagination on all lists.
+servers:
+  - url: https://api.idelio.pro/v1
+security:
+  - bearerAuth: []
+  - apiKeyAuth: []
+paths:
+  /me:
+    get:
+      operationId: getMe
+      summary: Return the authenticated user, their workspace and effective role.
+      responses:
+        "200":
+          description: User + workspace context
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MeResponse" }
+  /me/onboarding:
+    post:
+      operationId: completeOnboarding
+      summary: Record that the authenticated membership finished onboarding.
+      description: >-
+        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
+        timestamp is the server's. Refused for an API key, which acts for the
+        workspace rather than for a person and has no membership to settle.
+      responses:
+        "200":
+          description: The onboarding completion timestamp in force.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [onboardingCompletedAt]
+                properties:
+                  onboardingCompletedAt: { type: string, format: date-time }
+        "422":
+          description: Authenticated with an API key, which has no membership.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+  /workspace:
+    get:
+      operationId: getWorkspace
+      summary: Retrieve the current workspace.
+      responses:
+        "200":
+          description: Workspace object
+          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
+                properties:
+                  workspace: { $ref: "#/components/schemas/Workspace" }
+        "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.
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/UpdateWorkspaceRequest" }
+      responses:
+        "200":
+          description: Updated workspace
+          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
+                properties:
+                  workspace: { $ref: "#/components/schemas/Workspace" }
+        "422": { description: Invalid patch }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /workspace/members:
+    get:
+      operationId: listMembers
+      summary: List members and their roles.
+      parameters:
+        - { name: cursor, in: query, schema: { type: string } }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
+      responses:
+        "200":
+          description: Paginated members
+          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
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/Member" }
+                  next_cursor: { type: string, nullable: true }
+                  has_more: { type: boolean }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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`.
+      security: [{ bearerAuth: [] }]
+      summary: Invite a user by email with a role.
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/InviteMemberRequest" }
+      responses:
+        "201":
+          description: Invitation created
+          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
+                properties:
+                  invitation:
+                    type: object
+                    properties:
+                      email: { type: string }
+                      role: { type: string, enum: [admin, member] }
+                      status: { type: string }
+        "409": { description: Already a member }
+        "422": { description: Invalid request }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /workspace/members/{userId}:
+    patch:
+      operationId: changeMemberRole
+      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.
+      parameters:
+        - { name: userId, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ChangeMemberRoleRequest" }
+      responses:
+        "200":
+          description: Updated member
+          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
+                properties:
+                  member: { $ref: "#/components/schemas/Member" }
+        "404": { description: Member not found }
+        "409": { description: Would leave the workspace without an owner }
+        "422": { description: Invalid request }
+        "429": { $ref: "#/components/responses/RateLimited" }
+    delete:
+      operationId: removeMember
+      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.
+      parameters:
+        - { name: userId, in: path, required: true, schema: { type: string } }
+      responses:
+        "204": { description: Removed }
+        "404": { description: Member not found }
+        "409": { description: Would leave the workspace without an owner }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /brands:
+    get:
+      operationId: listBrands
+      summary: List brands in the workspace.
+      parameters:
+        - { name: status, in: query, schema: { type: string, enum: [draft, generating, ready, failed] } }
+        - { name: q, in: query, 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: Paginated brands
+          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
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/Brand" }
+                  next_cursor: { type: string, nullable: true }
+                  has_more: { type: boolean }
+        "429": { $ref: "#/components/responses/RateLimited" }
+    post:
+      operationId: createBrand
+      summary: Generate a new brand from a prompt or template (reserves credits, starts a durable workflow).
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/CreateBrandRequest" }
+      responses:
+        "202":
+          description: Job accepted
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "402": { description: Insufficient credits }
+        "409": { description: This workspace already has its plan's worth of generations running - `code` is `too_many_running_jobs` }
+        "422":
+          description: >-
+            Invalid request. `code` is `validation_failed`, or
+            `required_assets_missing` when an explicit `assets` list omits a
+            required kind (the message names which); `param` names the
+            failing field.
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /brands/surprise:
+    post:
+      operationId: surpriseBrief
+      summary: 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
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/SurpriseBriefResponse" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /brands/directions:
+    post:
+      operationId: brandCreativeDirections
+      summary: Shortlist creative directions against a brief - free, not persisted.
+      description: >-
+        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
+        colours or family names, and the API validates every id against its own
+        catalog before answering. Free and not persisted, so no
+        Idempotency-Key; rate limited like /brands/names. A failure here is not
+        an error the user needs to see - the client falls back to the catalog
+        order.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/CreativeDirectionsRequest" }
+      responses:
+        "200":
+          description: A ranked shortlist per axis, padded from the catalog
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/CreativeDirectionsShortlist" }
+        "422": { description: Invalid request body - the failing field is named in `param` }
+        "429": { $ref: "#/components/responses/RateLimited" }
+        "503": { description: The shortlist could not be produced - retryable }
+  /brands/names:
+    post:
+      operationId: brandNameIdeas
+      summary: Generate brand name ideas for the creator's name generator - free, not persisted.
+      description: >-
+        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
+        and not persisted, so no Idempotency-Key; rate limited like
+        /brands/surprise.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/NameIdeasRequest" }
+      responses:
+        "200":
+          description: A freshly generated set of name ideas
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/NameIdeasResponse" }
+        "422": { description: Invalid request body - the failing field is named in `param` }
+        "429": { $ref: "#/components/responses/RateLimited" }
+        "503": { description: The generator could not produce names - retryable }
+  /brands/{id}:
+    get:
+      operationId: getBrand
+      summary: Retrieve a brand with its head version summary.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Brand object
+          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
+                properties:
+                  brand: { $ref: "#/components/schemas/Brand" }
+        "404": { description: Not found }
+        "429": { $ref: "#/components/responses/RateLimited" }
+    patch:
+      operationId: updateBrand
+      summary: Rename a brand, change its slug, or update generation locks.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/UpdateBrandRequest" }
+      responses:
+        "200":
+          description: Updated brand
+          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
+                properties:
+                  brand: { $ref: "#/components/schemas/Brand" }
+        "404": { description: Not found }
+        "409": { description: Slug already in use in this workspace }
+        "422": { description: Invalid patch }
+        "429": { $ref: "#/components/responses/RateLimited" }
+    delete:
+      operationId: deleteBrand
+      summary: Soft-delete a brand (never hard-deleted).
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "204": { description: Deleted }
+        "404": { description: Not found }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /brands/{id}/assets:
+    get:
+      operationId: listBrandAssets
+      summary: List assets belonging to a brand.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: kind, in: query, schema: { type: string } }
+        - { name: cursor, in: query, schema: { type: string } }
+        - name: limit
+          in: query
+          description: >-
+            Page size, 1-100. A brand with the whole catalogue holds more than
+            one default page, so follow `next_cursor` or raise the limit.
+          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+      responses:
+        "200":
+          description: Paginated assets
+          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
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/Asset" }
+                  next_cursor: { type: string, nullable: true }
+                  has_more: { type: boolean }
+        "404": { description: Not found }
+        "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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ExpandBrandRequest" }
+      responses:
+        "202":
+          description: GenerationJob object (queued)
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "402": { description: Insufficient credits }
+        "404": { description: Not found }
+        "409": { description: "Brand not ready, one of the requested asset kinds already exists, or this workspace already has its plan's worth of generations running (`code` is `too_many_running_jobs`)" }
+        "422": { description: An asset kind cannot be expanded yet, or a templated/mockup asset was requested on the flash tier }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/BrandRefineRequest" }
+      responses:
+        "202":
+          description: GenerationJob object (queued)
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "402": { description: Insufficient credits }
+        "404": { description: Not found }
+        "409": { description: "Brand not ready, or this workspace already has its plan's worth of generations running (`code` is `too_many_running_jobs`)" }
+        "422": { description: Validation failed }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /brands/{id}/logo:
+    get:
+      operationId: getBrandLogo
+      summary: 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 } }
+        - name: size
+          in: query
+          description: >-
+            Kept for older brands only. The mark, wordmark and lockup are each
+            served as the file generation wrote, at its native resolution. A
+            brand from before the raster mark holds an SVG-only logo, and for
+            it a PNG request is answered with the favicon (`size` <= 64) or
+            the app icon. Fixed-size icons are their own assets: use
+            GET /assets/{id}/download with `size`.
+          schema: { type: integer, default: 512 }
+        - name: variant
+          in: query
+          description: >-
+            `mark` is the symbol alone (the `logo` asset), `wordmark` the
+            name alone (the `logo_wordmark` asset, or the retired `wordmark`
+            kind older brands hold, which is PNG-only), and `lockup` the two
+            arranged together (`logo_alternative`) in whichever arrangement
+            the brand pinned in the creator - horizontal when it pinned none.
+            Brands generated before lockups were produced answer 422 for
+            `lockup`.
+          schema: { type: string, enum: [mark, wordmark, lockup], default: mark }
+      responses:
+        "302": { description: Redirect to signed CDN URL }
+        "404": { description: Not found }
+        "409": { description: Brand not ready }
+        "422": { description: Unsupported format for this asset, or a lockup this brand does not have }
+  /brands/{id}/palette:
+    get:
+      operationId: getBrandPalette
+      summary: 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 } }
+      responses:
+        "200":
+          description: Tokens or CSS variables
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  brand_id: { type: string }
+                  colors: { type: object, additionalProperties: { type: string } }
+                  css: { type: string }
+        "404": { description: Not found }
+        "409": { description: Brand not ready }
+  /brands/{id}/tokens:
+    get:
+      operationId: getBrandTokens
+      summary: Full W3C design-token document (inline).
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: tokens.json
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tokens: { type: object }
+        "404": { description: Not found }
+        "409": { description: Brand not ready }
+  /brands/{id}/dna:
+    get:
+      operationId: getBrandDna
+      summary: The frozen creative genome (brief + strategy) the brand reads from.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Brand DNA
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  dna: { $ref: "#/components/schemas/BrandDna" }
+        "404": { description: Not found }
+        "409": { description: Brand not ready }
+  /brands/{id}/versions:
+    get:
+      operationId: listBrandVersions
+      summary: Version history (git-commit semantics) for the brand, newest first.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Brand versions
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/BrandVersionSummary" }
+        "404": { description: Not found }
+  /brands/{id}/suggestions:
+    get:
+      operationId: getBrandSuggestions
+      summary: 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:
+        "200":
+          description: Suggestions
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items: { $ref: "#/components/schemas/BrandSuggestionItem" }
+        "404": { description: Not found }
+        "409": { description: Brand not ready }
+  /brands/{id}/suggestions/{kind}/generate:
+    post:
+      operationId: generateBrandSuggestion
+      summary: 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 } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
+      responses:
+        "202":
+          description: GenerationJob object (queued) - poll GET /jobs/{id} or GET /brands/{id}/suggestions for status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  job_id: { type: string }
+        "404": { description: Suggestion not found }
+        "409": { description: "Already generating, or brand not ready, or this workspace already has its plan's worth of generations running (`code` is `too_many_running_jobs`), or the suggestion is a custom asset idea (`code` is `suggestion_needs_review`) - generate those through POST /brands/{id}/assets once the user has seen the prompt" }
+  /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.
+      responses:
+        "200":
+          description: Suggestions
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    maxItems: 3
+                    items: { $ref: "#/components/schemas/WorkspaceSuggestionItem" }
+  /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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RestoreRequest" }
+      responses:
+        "201":
+          description: Restored
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  brand: { $ref: "#/components/schemas/Brand" }
+        "404": { description: Not found }
+  /brands/{id}/export:
+    get:
+      operationId: exportBrandKit
+      summary: 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." }
+      responses:
+        "202":
+          description: GenerationJob object (queued) - poll GET /jobs/{id} for download_url
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/JobEnvelope" }
+        "404": { description: Not found }
+        "409": { description: Brand not ready }
+  /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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: target, in: query, schema: { type: string, enum: [tokens, next, vite, expo], default: tokens } }
+        - { name: version, in: query, schema: { type: string }, description: "Not yet supported - any value returns 422." }
+        - { name: redirect, in: query, schema: { type: boolean, default: true } }
+      responses:
+        "200":
+          description: Signed CDN URL as JSON (only when redirect=false and the archive already exists)
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [url]
+                properties: { url: { type: string } }
+        "302": { description: Redirect to a signed CDN URL for the already-built archive (default) }
+        "202":
+          description: Packaging job started - poll GET /jobs/{id} for download_url
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/JobEnvelope" }
+        "404": { description: Not found }
+        "409": { description: Brand not ready }
+        "422": { description: Invalid target, or version pinning requested (not supported) }
+  /brands/{id}/guidelines:
+    get:
+      operationId: getBrandGuidelines
+      summary: Download the brand guidelines PDF.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "302": { description: Redirect to signed CDN URL }
+        "404": { description: Not found - the brand hasn't expanded this asset yet }
+        "409": { description: Brand not ready }
+  /jobs:
+    get:
+      operationId: listJobs
+      summary: List generation jobs in the workspace.
+      parameters:
+        - { name: status, in: query, schema: { type: string, enum: [queued, running, completed, failed, canceled] } }
+        - { name: brand_id, in: query, schema: { type: string } }
+        - { name: cursor, in: query, schema: { type: string } }
+      responses:
+        "200":
+          description: Paginated jobs
+          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
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/GenerationJob" }
+                  next_cursor: { type: string, nullable: true }
+                  has_more: { type: boolean }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /jobs/{id}:
+    get:
+      operationId: getJob
+      summary: Get job status and per-step progress.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: GenerationJob object
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "404": { description: Not found }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /jobs/{id}/events:
+    get:
+      operationId: streamJobEvents
+      summary: Subscribe to the job's SSE event stream (text/event-stream).
+      description: >-
+        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
+        available mid-pipeline - e.g. the logo concepts a picker step needs to
+        render, before the job as a whole finishes. A single asset can
+        independently emit `asset.failed` (`{kind, error}`) or
+        `asset.insufficient_credits` (`{kind, required, available}`) without
+        ending the stream, and `asset.retrying` (`{kind}`) when a retry signal
+        is accepted. `assets.pending_retry` (`{brand_id, kinds}`) is a one-off
+        nudge, a couple of hours in, that those kinds are still waiting to be
+        retried before the free in-job retry window closes. The stream finally
+        ends with `job.completed`,
+        `job.completed_with_errors` (`{failed_kinds}`, when one or more assets
+        were never resolved), or `job.failed`, after which the stream closes.
+        Event ids are Redis stream entry ids; reconnect with Last-Event-ID to
+        resume without gaps. Comment lines (`: ping`) are heartbeats. Clients
+        must close the EventSource after a terminal event - the server ends
+        the stream and a reconnect would only replay it.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: Last-Event-ID, in: header, schema: { type: string } }
+      responses:
+        "200": { description: text/event-stream }
+        "404": { description: Not found }
+  /jobs/{id}/cancel:
+    post:
+      operationId: cancelJob
+      summary: Cancel a running job; the reservation is refunded on the ledger.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: GenerationJob object (canceling/canceled)
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "404": { description: Not found }
+        "409": { description: Job already finished }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /jobs/{id}/logo-selection:
+    post:
+      operationId: selectLogoConcept
+      summary: Approve one of the generated logo concepts; resumes the paused workflow.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/LogoSelectionRequest" }
+      responses:
+        "200":
+          description: >-
+            GenerationJob object (signal sent; the logo step transitions to
+            completed asynchronously once the workflow processes the
+            selection)
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "404": { description: Not found }
+        "409": { description: Job is not currently awaiting a logo selection }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /jobs/{id}/logo-concepts/{assetVersionId}/preview:
+    get:
+      operationId: previewLogoConceptLockup
+      summary: >-
+        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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: assetVersionId, in: path, required: true, schema: { type: string } }
+        - { name: lockup, in: query, schema: { type: string, enum: [horizontal, stacked] } }
+        - { name: family, in: query, schema: { type: string } }
+        - { name: ink, in: query, schema: { type: string } }
+        - { name: accent, in: query, schema: { type: string } }
+        - { name: style_seed, in: query, schema: { type: string }, description: "Free-form nonce for the 'shuffle wordmark style' control - a fresh value re-rolls which of a category's 5 treatments this render uses." }
+        - { name: redirect, in: query, schema: { type: boolean, default: true } }
+      responses:
+        "200":
+          description: Signed CDN URL as JSON (only when redirect=false)
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [url]
+                properties: { url: { type: string } }
+        "302": { description: Redirect to a signed CDN URL for the rendered preview (default) }
+        "404": { description: Not found }
+        "422": { description: Invalid lockup value }
+        "503": { description: The preview render could not be started - try again }
+  /jobs/{id}/logo-concepts/{assetVersionId}/palette:
+    get:
+      operationId: getLogoConceptPalette
+      summary: >-
+        The brand's generated DNA palette tokens, for the picker's colour
+        override swatches - free, read-only.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: assetVersionId, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: LogoConceptPalette object
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LogoConceptPalette" }
+        "404": { description: Not found }
+  /jobs/{id}/assets/{kind}/retry:
+    post:
+      operationId: retryJobAsset
+      summary: Retry one failed or credit-blocked asset within an in-progress generation job, for free.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: kind, in: path, required: true, schema: { type: string } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
+      responses:
+        "202":
+          description: Retry signal accepted.
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "404": { description: Not found, or the asset kind is not part of this job }
+        "409": { description: The asset is not in a retryable state (already generating/ready), or the job has already finalized - `code` distinguishes these }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /assets/{id}:
+    get:
+      operationId: getAsset
+      summary: Retrieve a single asset with its current version.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Asset object
+          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
+                properties:
+                  asset: { $ref: "#/components/schemas/Asset" }
+        "404": { description: Not found }
+        "429": { $ref: "#/components/responses/RateLimited" }
+    delete:
+      operationId: deleteAsset
+      summary: Remove an asset from the brand library.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "204": { description: Deleted }
+        "404": { description: Not found }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /assets/{id}/qa:
+    get:
+      operationId: getAssetQaReport
+      summary: Get the Pixel Check QA report (per-dimension scores).
+      description: >-
+        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
+        it returns are a stable, intentional part of the public surface, the
+        same status GET /ai-teams holds while its own in-app picker is
+        parked.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: QA report
+          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
+                properties:
+                  report:
+                    allOf: [{ $ref: "#/components/schemas/QaReport" }]
+                    nullable: true
+        "404": { description: Not found }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /assets/{id}/download:
+    get:
+      operationId: downloadAsset
+      summary: Redirect to a time-limited signed CDN URL, or return it as JSON
+        with `redirect=false`.
+      description: |
+        `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
+        request to the CDN: on a same-origin-to-cross-origin 302, browsers
+        replace Origin with "null" for the follow-up request, which the
+        CDN's CORS policy can never allow-list, so the redirect path fails
+        CORS regardless of how the bucket is configured (confirmed live
+        2026-09-17). A plain link or `<img>` navigation is not subject to
+        CORS at all and should keep using the default redirect.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - name: format
+          in: query
+          description: >-
+            An extension (`png`, `svg`) or a file's full label from the
+            version's `files` (`png-favicon-32`). With neither `format` nor
+            `size`, the SVG is served when the asset has one.
+          schema: { type: string }
+        - name: size
+          in: query
+          description: >-
+            Picks a pre-rendered size - favicon 16/32/48/512, app icon
+            64/128/192/512/1024 - and implies `format=png` when `format` is
+            omitted. Nothing is resized on request: a size the asset was not
+            rendered at answers 415 `unsupported_size`, naming the sizes it has.
+          schema: { type: integer, minimum: 1 }
+        - { name: redirect, in: query, schema: { type: boolean, default: true } }
+      responses:
+        "200":
+          description: Signed CDN URL as JSON (only when redirect=false)
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [url]
+                properties: { url: { type: string } }
+        "302": { description: Redirect to signed CDN URL (default) }
+        "404": { description: Not found }
+        "415": { description: "The asset has no file in that format (`unsupported_format`) or was not rendered at that size (`unsupported_size`)" }
+        "422": { description: "`size` is not a positive whole number" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: versionId, in: path, required: true, schema: { type: string } }
+        - name: format
+          in: query
+          description: >-
+            An extension (`png`, `svg`) or a file's full label from the
+            version's `files` (`png-favicon-32`). With neither `format` nor
+            `size`, the SVG is served when the asset has one.
+          schema: { type: string }
+        - name: size
+          in: query
+          description: >-
+            Picks a pre-rendered size - favicon 16/32/48/512, app icon
+            64/128/192/512/1024 - and implies `format=png` when `format` is
+            omitted. Nothing is resized on request: a size the asset was not
+            rendered at answers 415 `unsupported_size`, naming the sizes it has.
+          schema: { type: integer, minimum: 1 }
+        - { name: redirect, in: query, schema: { type: boolean, default: true } }
+      responses:
+        "200":
+          description: Signed CDN URL as JSON (only when redirect=false)
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [url]
+                properties: { url: { type: string } }
+        "302": { description: Redirect to signed CDN URL (default) }
+        "404": { description: Not found }
+        "415": { description: "The asset has no file in that format (`unsupported_format`) or was not rendered at that size (`unsupported_size`)" }
+        "422": { description: "`size` is not a positive whole number" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: redirect, in: query, schema: { type: boolean, default: true } }
+      responses:
+        "200":
+          description: Signed CDN URL as JSON (only when redirect=false)
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [url]
+                properties: { url: { type: string } }
+        "302": { description: Redirect to a signed CDN URL for the ZIP (default) }
+        "404": { description: Not found }
+        "429": { $ref: "#/components/responses/RateLimited" }
+        "503": { description: Packaging failed or timed out }
+  /assets/{id}/versions:
+    get:
+      operationId: listAssetVersions
+      summary: 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:
+        "200":
+          description: Paginated asset versions
+          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
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/AssetVersion" }
+                  next_cursor: { type: string, nullable: true }
+                  has_more: { type: boolean }
+        "404": { description: Not found }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /assets/{id}/regenerate:
+    post:
+      operationId: regenerateAsset
+      summary: 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 } }
+      responses:
+        "202":
+          description: GenerationJob object (queued)
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "402": { description: Insufficient credits }
+        "404": { description: Not found }
+        "409": { description: This workspace already has its plan's worth of generations running - `code` is `too_many_running_jobs` }
+        "422": { description: "This build cannot price this asset's kind - `code` is `asset_kind_not_priceable`" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+        "501": { description: This asset kind is not regenerable yet }
+  /assets/{id}/refine:
+    post:
+      operationId: refineAsset
+      summary: Refine an asset - a free-text instruction, or font/accent/style overrides for `logo_wordmark`.
+      description: >-
+        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
+        exactly those three fields, constrained to the font catalog the
+        platform can render and to the brand's own palette, so it never
+        becomes an image prompt. `logo_wordmark` follows the same pricing rule
+        as other assets: first 2 refinements are free, then 25% of the asset's
+        base price per refinement. A `logo_wordmark` instruction that turns
+        out to change the font on a brand whose typography is locked, or that
+        resolves to no change at all, is refused by the job rather than
+        applied in part: the job ends `failed`, its failure event carries the
+        reason, and the reservation is refunded in full.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RefineRequest" }
+      responses:
+        "202":
+          description: GenerationJob object (queued)
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "404": { description: Not found }
+        "409": { description: "This workspace already has its plan's worth of generations running (`code` is `too_many_running_jobs`), or a structured `family` override was sent for a brand whose typography is locked (`code` is `typography_locked`)" }
+        "422": { description: "Invalid instruction, or this build cannot price this asset's kind - `code` is `asset_kind_not_priceable`" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+        "501": { description: This asset kind is not regenerable yet }
+  /assets/{id}/logo-treatment:
+    get:
+      operationId: getLogoTreatment
+      summary: Read a wordmark/logo's current treatment (font, accent, style).
+      tags: [Assets]
+      security: [{ bearerAuth: [] }, { apiKeyAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string }, description: A `logo_wordmark` asset's id. }
+      responses:
+        "200":
+          description: The brand's current logo treatment.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LogoTreatment" }
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /assets/{id}/logo-treatment/preview:
+    get:
+      operationId: previewLogoTreatment
+      summary: >-
+        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
+        that treatment's current value.
+      tags: [Assets]
+      security: [{ bearerAuth: [] }, { apiKeyAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string }, description: A `logo_wordmark` asset's id. }
+        - { name: family, in: query, schema: { type: string }, description: Font family name. }
+        - { name: ink, in: query, schema: { type: string, pattern: "^#[0-9a-fA-F]{6}$" }, description: Hex name (ink) color. }
+        - { name: accent, in: query, schema: { type: string, pattern: "^#[0-9a-fA-F]{6}$" }, description: Hex accent color. }
+        - { name: style_seed, in: query, schema: { type: string }, description: Free-form nonce for shuffling wordmark style - a fresh value re-rolls which of a category's treatments this render uses. }
+        - { name: style_index, in: query, schema: { type: integer, minimum: 0, maximum: 10 }, description: "Names one of the category's 11 wordmark treatments outright, instead of re-rolling for one. Preferred over style_seed." }
+        - { name: redirect, in: query, schema: { type: boolean, default: true }, description: When true (default), redirect to the preview URL; when false, return the URL as JSON. }
+      responses:
+        "200":
+          description: Signed CDN URL as JSON (only when redirect=false).
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [url]
+                properties:
+                  url: { type: string }
+        "302":
+          description: Redirect to a signed CDN URL for the rendered preview (default).
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "422":
+          description: Invalid query parameters.
+        "503":
+          description: The preview render could not be started - try again.
+  /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).
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VariationRequest" }
+      responses:
+        "202":
+          description: GenerationJob object (queued)
+          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: { $ref: "#/components/schemas/JobEnvelope" }
+        "402": { description: Insufficient credits }
+        "404": { description: Not found }
+        "409": { description: "This workspace already has its plan's worth of generations running - `code` is `too_many_running_jobs`" }
+        "422": { description: "Unknown preset, the logo has no approved concept yet, or this build cannot price this asset's kind - `code` is `asset_kind_not_priceable`" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+        "501": { description: This asset kind is not regenerable yet }
+  /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).
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RestoreRequest" }
+      responses:
+        "201":
+          description: Restored
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  asset: { $ref: "#/components/schemas/Asset" }
+                  job:
+                    description: Present only when restoring a `logo` version started the free background cascade that re-derives favicon/app_icon/profile_avatar/logo_mono/logo_reversed/logo_alternative from the restored mark. `restore` itself is already complete by the time this response arrives - `job` is purely a handle for a client that wants to know when those derived tiles are caught up too.
+                    allOf: [{ $ref: "#/components/schemas/GenerationJob" }]
+        "404": { description: Not found }
+  /credits/balance:
+    get:
+      operationId: getCreditBalance
+      summary: Get the current balance, plan and renewal date.
+      responses:
+        "200":
+          description: Balance summary
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/CreditBalance" }
+  /credits/ledger:
+    get:
+      operationId: listCreditLedger
+      summary: 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 } }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
+      responses:
+        "200":
+          description: Ledger page, newest first
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LedgerPage" }
+  /ai-teams:
+    get:
+      operationId: listAiTeams
+      summary: List the AI team tiers and their credit multipliers.
+      responses:
+        "200":
+          description: AI team tiers
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/AiTeam" }
+  /healthz:
+    get:
+      operationId: healthz
+      summary: Liveness and dependency health probe (unversioned in prod routing).
+      security: []
+      responses:
+        "200": { description: Healthy }
+        "503": { description: Degraded }
+  /waitlist:
+    post:
+      operationId: joinWaitlist
+      summary: Join the public waitlist. No authentication required.
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WaitlistSignupRequest" }
+      responses:
+        "200":
+          description: >-
+            Joined (or already on the list - the response is identical
+            either way).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WaitlistSignupResponse" }
+        "422":
+          description: >-
+            Validation failed - including when marketing_consent is true but
+            privacy_policy_version is missing.
+        "429": { description: Rate limit exceeded }
+  /consent:
+    post:
+      operationId: recordConsent
+      summary: >-
+        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.
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ConsentRequest" }
+      responses:
+        "201":
+          description: Consent recorded.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ConsentResponse" }
+        "400":
+          description: Validation failed.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
+        "401":
+          description: >-
+            A terms_acceptance was sent without a verifiable session. That type
+            alone is never recorded anonymously - an anonymous row is scoped to
+            no workspace, so nothing can ever read it back.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
+        "422":
+          description: >-
+            A terms_acceptance whose checkbox_text or accepted_versions are not
+            the canonical values the sign-up screen shows.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /api-keys:
+    get:
+      operationId: listApiKeys
+      summary: List the workspace's API keys (non-revoked only).
+      responses:
+        "200":
+          description: API keys
+          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
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/ApiKey" }
+        "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.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/CreateApiKeyRequest" }
+      responses:
+        "201":
+          description: The new key, including its one-time secret
+          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: { $ref: "#/components/schemas/ApiKeyWithSecret" }
+        "403": { description: Caller's role is below admin }
+        "422": { description: Invalid request body }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "204": { description: Revoked }
+        "403": { description: Caller's role is below admin }
+        "404": { description: No active key with that id }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /usage:
+    get:
+      operationId: getUsage
+      summary: 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 } }
+        - { name: granularity, in: query, schema: { type: string, enum: [day, week, month], default: day } }
+      responses:
+        "200":
+          description: Usage buckets
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UsagePage" }
+  /webhook-endpoints:
+    get:
+      operationId: listWebhookEndpoints
+      summary: List the workspace's outbound webhook endpoints (secrets never included).
+      responses:
+        "200":
+          description: Webhook endpoints
+          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
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/WebhookEndpoint" }
+        "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.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/CreateWebhookEndpointRequest" }
+      responses:
+        "201":
+          description: The new endpoint, including its one-time signing secret
+          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: { $ref: "#/components/schemas/WebhookEndpointWithSecret" }
+        "403": { description: Caller's role is below admin }
+        "422": { description: Invalid request body }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/UpdateWebhookEndpointRequest" }
+      responses:
+        "200":
+          description: The updated endpoint
+          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
+                properties:
+                  endpoint: { $ref: "#/components/schemas/WebhookEndpoint" }
+        "403": { description: Caller's role is below admin }
+        "404": { description: No webhook endpoint with that id }
+        "422": { description: Invalid request body }
+        "429": { $ref: "#/components/responses/RateLimited" }
+    delete:
+      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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "204": { description: Removed }
+        "403": { description: Caller's role is below admin }
+        "404": { description: No webhook endpoint with that id }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "202":
+          description: Delivery dispatched
+          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
+                properties:
+                  dispatched: { type: boolean }
+        "403": { description: Caller's role is below admin }
+        "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.
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/StripeWebhookEvent" }
+      responses:
+        "200":
+          description: Received (and processed, or a no-op replay of an already-seen event id)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  received: { type: boolean }
+        "401":
+          description: Signature verification failed
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
+        "422": { description: Payload failed validation (after signature verification) }
+  /webhooks/clerk:
+    post:
+      operationId: receiveClerkWebhook
+      summary: >-
+        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.
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { type: object, description: "Clerk's own event envelope (opaque - not tightly typed here)." }
+      responses:
+        "200":
+          description: Received (and processed, or a no-op replay of an already-seen event id)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  received: { type: boolean }
+        "401":
+          description: Signature verification failed
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
+  /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.
+      responses:
+        "200":
+          description: Subscription object
+          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
+                properties:
+                  subscription:
+                    oneOf:
+                      - { $ref: "#/components/schemas/Subscription" }
+                      - { type: "null" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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.
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/CheckoutRequest" }
+      responses:
+        "201":
+          description: Checkout session
+          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
+                properties:
+                  checkout:
+                    type: object
+                    properties:
+                      url: { type: string }
+        "422":
+          description: >
+            Unrecognized price_id, or a success_url whose origin is not the
+            app's own (APP_BASE_URL).
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /billing/checkout/{id}:
+    get:
+      operationId: getCheckoutSession
+      security: [{ bearerAuth: [] }]
+      summary: Read whether a checkout has been applied to this workspace yet.
+      description: >
+        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
+        purchase is only `paid` once both the credit grant and the plan change
+        have landed, because they arrive on separate provider webhooks in an
+        order the provider does not guarantee. Answers 404 - never 403 - for
+        an id belonging to another workspace, so the endpoint cannot be used
+        to confirm that an id exists.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Checkout session
+          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
+                properties:
+                  checkout: { $ref: "#/components/schemas/CheckoutSession" }
+        "404": { description: No such checkout session for this workspace }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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: >-
+        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.
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ChangePlanRequest" }
+      responses:
+        "200":
+          description: The subscription after applying (or queuing) the change
+          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
+                properties:
+                  subscription: { $ref: "#/components/schemas/Subscription" }
+        "409": { description: No active subscription to change - use POST /billing/checkout instead }
+        "422": { description: Unrecognized price_id, a top-up price, or the workspace's current plan }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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.
+      responses:
+        "200":
+          description: Provider-agnostic price catalog
+          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: { $ref: "#/components/schemas/BillingCatalog" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /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.
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string }
+      responses:
+        "201":
+          description: Portal session URL
+          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
+                properties:
+                  portal:
+                    type: object
+                    properties:
+                      url: { type: string }
+        "409": { description: No billing customer for this workspace yet }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /billing/payment-method:
+    get:
+      operationId: getPaymentMethod
+      security: [{ bearerAuth: [] }]
+      summary: The card this workspace's charges land on.
+      description: >
+        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).
+        Null is an answer rather than a failure: render the absence. Never the full number and
+        never a token; this exists so a user can tell WHICH of their cards is on file. Changing
+        it happens in the provider's own portal.
+      responses:
+        "200":
+          description: The card on file, or null
+          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
+                properties:
+                  payment_method:
+                    nullable: true
+                    allOf: [{ $ref: "#/components/schemas/PaymentMethod" }]
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /billing/invoices:
+    get:
+      operationId: listInvoices
+      security: [{ bearerAuth: [] }]
+      summary: List the workspace's invoices from Stripe.
+      description: >
+        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
+        first. Note that `billed_at` is the date the invoice was issued, which is not the key
+        the list is ordered by: an invoice finalized long after it was created carries a
+        `billed_at` later than its position in the list implies. Order by `billed_at`
+        client-side if you need the two to agree.
+      parameters:
+        - { name: cursor, in: query, schema: { type: string } }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
+      responses:
+        "200":
+          description: Paginated invoices
+          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
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/Invoice" }
+                  next_cursor: { type: string, nullable: true }
+                  has_more: { type: boolean }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /billing/auto-topup:
+    get:
+      operationId: getAutoTopup
+      security: [{ bearerAuth: [] }]
+      summary: Get the workspace's auto top-up preference.
+      description: >-
+        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).
+      responses:
+        "200":
+          description: Auto top-up preference
+          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
+                properties:
+                  auto_topup: { $ref: "#/components/schemas/AutoTopup" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+    patch:
+      operationId: updateAutoTopup
+      security: [{ bearerAuth: [] }]
+      summary: Store the workspace's auto top-up preference.
+      description: >-
+        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
+        automatically (#426). Do not build against an automatic top-up until
+        that issue closes.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/UpdateAutoTopupRequest" }
+      responses:
+        "200":
+          description: Updated auto top-up preference
+          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
+                properties:
+                  auto_topup: { $ref: "#/components/schemas/AutoTopup" }
+        "422": { description: "pack_credits missing while enabling, or not one of 100/300/1000" }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /templates:
+    get:
+      operationId: listTemplates
+      summary: List available brand templates.
+      parameters:
+        - { name: category, in: query, schema: { type: string } }
+        - { name: cursor, in: query, schema: { type: string } }
+      responses:
+        "200":
+          description: Paginated templates
+          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
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/Template" }
+                  next_cursor: { type: string, nullable: true }
+                  has_more: { type: boolean }
+        "429": { $ref: "#/components/responses/RateLimited" }
+  /templates/{id}:
+    get:
+      operationId: getTemplate
+      summary: Retrieve a template definition.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Template object
+          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
+                properties:
+                  template: { $ref: "#/components/schemas/Template" }
+        "404": { description: Not found }
+        "429": { $ref: "#/components/responses/RateLimited" }
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+    apiKeyAuth:
+      type: http
+      scheme: bearer
+      description: >
+        Machine credential `sk_live_...` / `sk_test_...` sent as the Bearer
+        token; scoped per key. A key acts for the workspace, not a person, so it
+        holds no workspace role: operations that need one (API keys, billing,
+        members, workspace settings) are session-only and answer a key with 403
+        `session_required`. Webhook endpoints are the exception - a key manages
+        them with the `webhooks:write` scope.
+  # Per-API-key token-bucket rate limiting. Every route reachable via an API
+  # key returns these three headers on success and a 429 (see the
+  # RateLimited response below) once the caller's bucket is empty.
+  # OpenAPI has no single $ref for a group of headers - reference all three
+  # individually wherever RateLimitLimit is referenced. Applied here to the
+  # api-keys, webhook-endpoints, brands, assets and jobs resource groups (the
+  # ones a machine client actually calls) as a representative, meaningfully
+  # -scoped set; apply to the remaining paths in a follow-up once the
+  # limiter's uniform coverage across all authenticated routes is confirmed
+  # in production.
+  headers:
+    RateLimitLimit:
+      description: Sustained requests-per-minute allowed for the caller's plan.
+      schema: { type: integer }
+    RateLimitRemaining:
+      description: Tokens left in the caller's bucket right now.
+      schema: { type: integer }
+    RateLimitReset:
+      description: Seconds until the bucket is fully refilled back to its burst ceiling.
+      schema: { type: integer }
+  responses:
+    RateLimited:
+      description: Rate limit exceeded - the caller's token bucket is empty.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
+          example:
+            error:
+              type: rate_limit_error
+              code: rate_limited
+              message: Rate limit exceeded. Retry after the interval in Retry-After.
+              request_id: req_01hz3x9k2q
+              docs_url: https://docs.idelio.pro/errors/rate_limited
+  schemas:
+    CreditBalance:
+      type: object
+      properties:
+        balance: { type: integer }
+        plan: { type: string, enum: [free, pro, studio, agency] }
+        monthly_allowance: { type: integer }
+        renews_at: { type: string, format: date-time, nullable: true }
+    LedgerEntry:
+      type: object
+      properties:
+        id: { type: string }
+        delta: { type: integer }
+        reason: { type: string, enum: [grant, purchase, reserve, settle, refund, clawback] }
+        job_id: { type: string, nullable: true }
+        balance_after: { type: integer }
+        created_at: { type: string, format: date-time }
+    LedgerPage:
+      type: object
+      properties:
+        data:
+          type: array
+          items: { $ref: "#/components/schemas/LedgerEntry" }
+        next_cursor: { type: string, nullable: true }
+        has_more: { type: boolean }
+    CreateBrandRequest:
+      type: object
+      properties:
+        prompt: { type: string, minLength: 8 }
+        template_id: { type: string }
+        name: { type: string, minLength: 1, maxLength: 80 }
+        tagline: { type: string, minLength: 1, maxLength: 60, description: What the user typed in the creator - pinned in code rather than suggested to the model }
+        assets:
+          type: array
+          description: >-
+            The asset kinds to generate. Every brand includes five kinds -
+            "logo" (the symbol), "logo_alternative" (the logo lockup),
+            "logo_wordmark", "color_palette" and "font_pairing" - 7 credits
+            at Studio together. Omit the list, or send an empty array, to
+            generate exactly those five. A non-empty list MUST contain all
+            five, and anything else is added on top; a list missing any of
+            them answers 422 `required_assets_missing`. More kinds can be
+            added to an existing brand later with POST /brands/{id}/assets.
+          items: { type: string }
+        team: { type: string, enum: [flash, studio, elite], default: studio }
+        customize:
+          type: object
+          deprecated: true
+          description: >-
+            Superseded by creative_direction, which is typed against the
+            published catalogs instead of accepting free-form records. Still
+            accepted for released SDK versions. Neither block reaches the
+            generation pipeline yet - both are accepted and validated only -
+            so new clients should send creative_direction and stop sending
+            this one.
+        creative_direction: { $ref: "#/components/schemas/CreativeDirection" }
+        auto_select_logo:
+          type: boolean
+          default: false
+          description: >
+            Every generation pauses once its logo concepts exist and waits for
+            one to be picked through `POST /jobs/{id}/logo-selection` - for up
+            to 24 hours, after which the job fails and its credits are
+            refunded. `true` picks the first concept on the server instead, so
+            a caller with nobody to choose can poll the job straight to
+            `completed`.
+    CreativeDirection:
+      type: object
+      additionalProperties: false
+      description: >-
+        The creative direction the user chose. Every axis accepts the literal
+        "ai", which means "let the pipeline decide" - an explicit value, not
+        an omitted field. Ids come from the published catalogs in
+        @idelio/contracts; an id outside them is rejected.
+      properties:
+        styles:
+          type: array
+          maxItems: 5
+          items: { type: string, enum: [modern, minimal, bold, playful, elegant, corporate, luxury, organic, geometric, handcrafted, brutalist, editorial, retro, vintage, futuristic, timeless, art_deco, y2k, calm, energetic, warm, technical, rebellious, premium] }
+        color:
+          oneOf:
+            - type: object
+              additionalProperties: false
+              required: [mode]
+              properties:
+                mode: { type: string, enum: [ai] }
+            - type: object
+              additionalProperties: false
+              required: [mode, preset_id]
+              properties:
+                mode: { type: string, enum: [preset] }
+                preset_id: { type: string, enum: [indigo, teal, amber, forest, rose, slate, midnight, coral, sand, plum, ocean, citrus, mono_warm, berry] }
+            - type: object
+              additionalProperties: false
+              required: [mode, colors]
+              properties:
+                mode: { type: string, enum: [custom] }
+                colors:
+                  type: array
+                  minItems: 3
+                  maxItems: 6
+                  items: { type: string, pattern: "^#[0-9a-fA-F]{6}$" }
+        typography:
+          oneOf:
+            - type: object
+              additionalProperties: false
+              required: [mode]
+              properties:
+                mode: { type: string, enum: [ai] }
+            - type: object
+              additionalProperties: false
+              required: [mode, preset_id]
+              properties:
+                mode: { type: string, enum: [preset] }
+                preset_id: { type: string, enum: [sora_inter, fraunces_inter, space_inter, playfair_source, dmserif_dmsans, outfit_inter, manrope_manrope, bricolage_inter, instrument_inter, archivo_archivo, lora_lato, syne_inter, epilogue_inter, ibmplex_ibmplex, jost_inter, newsreader_inter, chivo_chivo, unbounded_inter, figtree_figtree, spectral_inter] }
+        logo:
+          type: object
+          additionalProperties: false
+          description: >-
+            Two independent axes. A mark style and a lockup are not
+            alternatives - a brand has one of each. The single impossible
+            pair is rejected: style "wordmark_only" with lockup "icon_only"
+            describes a logo with neither icon nor name.
+          properties:
+            style: { type: string, enum: [ai, geometric, rounded, circular, sharp, monogram, lettermark, abstract, emblem, organic, line, gradient, wordmark_only], default: ai }
+            lockup: { type: string, enum: [ai, horizontal, stacked, icon_only], default: ai }
+    UpdateBrandRequest:
+      type: object
+      properties:
+        name: { type: string, minLength: 1 }
+        slug: { type: string, minLength: 1 }
+        locks: { type: object }
+    ExpandBrandRequest:
+      type: object
+      required: [assets]
+      properties:
+        assets:
+          type: array
+          minItems: 1
+          items: { type: string }
+        team:
+          type: string
+          enum: [flash, studio, elite]
+        custom_image_prompt:
+          type: string
+          minLength: 1
+          maxLength: 500
+          description: Required when assets is exactly ["custom_image"].
+        custom_image_format:
+          type: string
+          enum: [square_1_1, portrait_4_5, story_9_16, landscape_16_9, wide_21_9, photo_3_2, poster_2_3, standard_4_3, auto, instagram_post, story, linkedin_post, ad_banner, custom]
+        custom_image_name:
+          type: string
+          minLength: 1
+          maxLength: 60
+          description: >-
+            Library name for the generated custom asset. Optional - when absent
+            the name is derived from custom_image_prompt. Only valid when assets
+            is exactly ["custom_image"]. Leading and trailing whitespace is
+            trimmed BEFORE minLength/maxLength are applied, so a 64-character
+            value whose padding trims to 58 is accepted, and a value of only
+            spaces is rejected as empty. Control characters (C0 and DEL) are
+            refused.
+    BrandRefineRequest:
+      type: object
+      required: [message]
+      properties:
+        message: { type: string, minLength: 1, maxLength: 500 }
+    QaCheck:
+      type: object
+      description: >-
+        One criterion the Brand Guardian evaluated. `label` travels with the
+        check because the set of criteria is the Guardian's to decide - a client
+        owning the labels would print nothing for a check it had not heard of.
+      required: [id, label, status]
+      properties:
+        id: { type: string }
+        label: { type: string }
+        status: { type: string, enum: [pass, warn, fail] }
+        detail: { type: string, nullable: true, description: "Why, in the user's language." }
+        source: { type: string, enum: [deterministic, ai], description: Which producer wrote this check. }
+    QaReport:
+      type: object
+      description: >-
+        Pixel Check report for one asset version. `overall_score` is required
+        because it already has a consumer: the API derives `Asset.pixel_check`
+        from it. The object is open on purpose - a Guardian that learns to
+        report more must not fail validation in clients that predate it.
+        The Brand Guardian writes this on generation, logo regeneration and
+        DNA refine, so a real report exists on many asset versions - no
+        current app UI surfaces it, but that is a client-side choice, not a
+        sign the field is unused.
+      required: [overall_score]
+      additionalProperties: true
+      properties:
+        overall_score: { type: integer, minimum: 0, maximum: 100 }
+        checks:
+          type: array
+          items: { $ref: "#/components/schemas/QaCheck" }
+    UsageBucket:
+      type: object
+      description: >-
+        One time bucket of API-key usage. `requests` and `credits` are measures
+        on different scales - a bucket can hold many cheap reads or one expensive
+        generation - so a consumer must not plot them against a shared axis.
+      required: [bucket, requests, credits]
+      properties:
+        bucket: { type: string, format: date-time, description: Start of the bucket, RFC 3339 UTC. }
+        requests: { type: integer, minimum: 0 }
+        credits: { type: integer, minimum: 0 }
+    UsagePage:
+      type: object
+      description: >-
+        Not cursor-paginated: the window is bounded by the from/to query rather
+        than by a cursor, so `data` is the whole slice.
+      required: [data]
+      properties:
+        data:
+          type: array
+          items: { $ref: "#/components/schemas/UsageBucket" }
+    Subscription:
+      type: object
+      properties:
+        plan: { type: string, enum: [free, pro, studio, agency] }
+        status: { type: string, nullable: true }
+        next_billed_at: { type: string, format: date-time, nullable: true }
+        cancel_at_period_end: { type: boolean }
+        pending_plan: { type: string, enum: [free, pro, studio, agency], nullable: true }
+        plan_change_effective_at: { type: string, format: date-time, nullable: true }
+    CheckoutSession:
+      type: object
+      required: [id, status, kind, plan, credits, amount, currency, created_at, settled_at]
+      properties:
+        id: { type: string }
+        status: { type: string, enum: [pending, paid, failed, cancelled] }
+        kind: { type: string, enum: [plan, topup] }
+        plan: { type: string, enum: [free, pro, studio, agency], nullable: true }
+        credits: { type: integer, nullable: true }
+        amount:
+          type: string
+          nullable: true
+          description: >-
+            The catalogue list price frozen when this checkout was created -
+            NOT the amount billed. Prices are tax-exclusive, so a customer in
+            a taxed jurisdiction pays this plus tax (#425), and adaptive
+            pricing may convert the currency. Read the invoice's total for the
+            money that actually moved.
+        currency:
+          type: string
+          nullable: true
+          description: Currency of `amount`; USD for every catalogue price today.
+        created_at: { type: string, format: date-time }
+        settled_at: { type: string, format: date-time, nullable: true }
+    CheckoutRequest:
+      type: object
+      required: [price_id]
+      properties:
+        price_id: { type: string, minLength: 1 }
+        success_url:
+          type: string
+          format: uri
+          description: >
+            Absolute URL the provider returns the buyer to. Must be on the
+            app's own origin (APP_BASE_URL); any other origin is rejected
+            with 422 validation_failed rather than followed, so this field
+            cannot be used as an open redirect. Idelio appends its own
+            `checkout` outcome and `ref` query parameters to it.
+    ChangePlanRequest:
+      type: object
+      required: [price_id]
+      properties:
+        price_id: { type: string, minLength: 1 }
+    BillingCatalog:
+      type: object
+      properties:
+        plans:
+          type: object
+          properties:
+            pro: { type: string, nullable: true }
+            studio: { type: string, nullable: true }
+            agency: { type: string, nullable: true }
+        topups:
+          type: object
+          properties:
+            "100": { type: string, nullable: true }
+            "300": { type: string, nullable: true }
+            "1000": { type: string, nullable: true }
+    AutoTopup:
+      type: object
+      properties:
+        enabled: { type: boolean }
+        pack_credits: { type: integer, enum: [100, 300, 1000], nullable: true }
+    UpdateAutoTopupRequest:
+      type: object
+      required: [enabled]
+      properties:
+        enabled: { type: boolean }
+        pack_credits:
+          type: integer
+          enum: [100, 300, 1000]
+          description: Required when enabled is true.
+    Template:
+      type: object
+      properties:
+        id: { type: string }
+        name: { type: string }
+        category: { type: string }
+        description: { type: string }
+        prompt: { type: string }
+        accent: { type: string }
+    PaymentMethod:
+      type: object
+      properties:
+        brand:
+          type: string
+          description: >
+            The card network as the provider names it - "visa", "mastercard", "amex" and so on.
+            Deliberately NOT an enum: providers add networks over time, so render a known mark
+            when you recognise one and fall back to the raw value otherwise. It must stay
+            readable as text, since an unrecognised brand with only an icon is a blank square.
+        last4: { type: string }
+        exp_month: { type: integer, minimum: 1, maximum: 12 }
+        exp_year: { type: integer }
+    Invoice:
+      type: object
+      properties:
+        id: { type: string }
+        status: { type: string }
+        total:
+          type: string
+          nullable: true
+          description: >
+            The amount billed for this invoice after discounts, tax and any customer credit
+            applied, as a string in the MINOR UNITS of `currency` - "2900" with a currency of
+            "USD" is $29.00. Some currencies have no minor unit (JPY, KRW) and some have three
+            (BHD, KWD), so derive the exponent from `currency` and never divide by 100. The
+            integer-minor-unit encoding is established by Stripe's own SDK type, and the
+            post-credit definition is what the provider maps (`amount_due`).
+        currency:
+          type: string
+          nullable: true
+          description: >
+            ISO 4217 currency code. Its case is NOT normalised - Stripe returns it lowercase
+            ("usd") - so compare it case-insensitively.
+        billed_at: { type: string, format: date-time, nullable: true }
+        invoice_number: { type: string, nullable: true }
+        url:
+          type: string
+          format: uri
+          nullable: true
+          description: >
+            Provider-hosted page where the customer can read or download this invoice, or null
+            when the provider has not produced one - a draft has no hosted document yet. Render
+            the absence rather than a dead link. The URL carries its own provider session and
+            expires on the provider's terms, so treat it as a redirect target rather than
+            something to embed or store.
+    Workspace:
+      type: object
+      properties:
+        id: { type: string }
+        name: { type: string }
+        plan: { type: string, enum: [free, pro, studio, agency] }
+        settings: { type: object }
+    UpdateWorkspaceRequest:
+      type: object
+      properties:
+        name: { type: string, minLength: 1 }
+        settings: { type: object }
+    Member:
+      type: object
+      properties:
+        id: { type: string }
+        email: { type: string }
+        role: { type: string, enum: [owner, admin, member] }
+        created_at: { type: string, format: date-time }
+    InviteMemberRequest:
+      type: object
+      required: [email, role]
+      properties:
+        email: { type: string, format: email }
+        role: { type: string, enum: [admin, member] }
+    ChangeMemberRoleRequest:
+      type: object
+      required: [role]
+      properties:
+        role: { type: string, enum: [owner, admin, member] }
+    StripeWebhookEvent:
+      type: object
+      required: [id, type]
+      description: >-
+        Stripe's own event envelope - opaque/generic, not tightly typed here
+        since we do not own Stripe's schema. The resource itself is nested
+        under data.object.
+      properties:
+        id: { type: string }
+        type: { type: string }
+        data:
+          type: object
+          properties:
+            object: { type: object }
+    ErrorEnvelope:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [type, code, message, request_id]
+          properties:
+            type: { type: string }
+            code: { type: string }
+            message: { type: string }
+            param: { type: string }
+            request_id: { type: string }
+            docs_url: { type: string }
+    Brand:
+      type: object
+      properties:
+        id: { type: string }
+        workspace_id: { type: string }
+        name: { type: string }
+        slug: { type: string }
+        status: { type: string, enum: [draft, generating, ready, failed] }
+        current_version_id: { type: string, nullable: true }
+        locks: { type: object }
+        preview:
+          $ref: "#/components/schemas/BrandPreview"
+        created_at: { type: string, format: date-time }
+        updated_at: { type: string, format: date-time }
+    BrandPreview:
+      type: object
+      description: >
+        Visual summary for list and card views. Absent on reads that do not
+        need it.
+      properties:
+        palette:
+          type: array
+          items: { type: string }
+          description: >
+            Every colour of the brand's current version, in the order its Brand
+            DNA lists them - role-grouped by construction (text, surface, then
+            accents, with any founder-chosen colour appended). The same array
+            GET /brands/{id}/dna serves, so no two surfaces order it
+            differently.
+        cover: { type: string, nullable: true }
+        asset_count: { type: integer, minimum: 0 }
+        logo_url: { type: string, nullable: true }
+        gradient_stops:
+          type: array
+          items: { type: string }
+          description: >
+            The two colours every surface draws this brand's gradient from -
+            the DNA's first two accent-role tokens, the same ones the logo is
+            drawn in. Empty before generation.
+    BrandDna:
+      type: object
+      properties:
+        brief:
+          type: object
+          properties:
+            industry: { type: string }
+            audience: { type: string }
+            tone: { type: string }
+            keywords: { type: array, items: { type: string } }
+            constraints: { type: array, items: { type: string } }
+        strategy:
+          type: object
+          properties:
+            positioning: { type: string }
+            archetype: { type: string }
+            values: { type: array, items: { type: string } }
+            name: { type: string }
+            tagline: { type: string }
+            name_rationale: { type: string }
+        visual_system:
+          type: object
+          properties:
+            palette:
+              type: object
+              properties:
+                tokens:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      name: { type: string }
+                      hex: { type: string }
+            typography:
+              type: object
+              properties:
+                heading_font: { type: string }
+                body_font: { type: string }
+                mono_font: { type: string, nullable: true }
+    BrandVersionSummary:
+      type: object
+      properties:
+        id: { type: string }
+        version_no: { type: integer }
+        message: { type: string, nullable: true }
+        created_by: { type: string }
+        qa_score: { type: integer, nullable: true }
+        created_at: { type: string, format: date-time }
+        is_current: { type: boolean }
+    BrandSuggestionItem:
+      type: object
+      properties:
+        kind: { type: string, enum: [logo_alternative, logo_wordmark, logo_mono, logo_reversed, favicon, brand_guide, profile_avatar, social_x, social_linkedin, social_linkedin_personal, social_facebook, social_youtube, social_post, social_story, app_icon, og_image, email_signature, hero_image, play_feature_graphic, business_card, letterhead, mockup, custom_image] }
+        tag: { type: string }
+        title: { type: string }
+        desc: { type: string }
+        state: { type: string, enum: [idle, generating, ready] }
+        asset_id: { type: string, nullable: true }
+        custom:
+          nullable: true
+          description: "Set exactly when kind is custom_image - an idea offered only once the brand owns every catalogue kind it can be offered. It is never generated in one click: prefill POST /brands/{id}/assets (custom_image_name, custom_image_prompt, custom_image_format) and let the user review it."
+          allOf:
+            - $ref: "#/components/schemas/CustomSuggestion"
+    CustomSuggestion:
+      type: object
+      required: [name, prompt, format]
+      properties:
+        name: { type: string, minLength: 1, maxLength: 60 }
+        prompt: { type: string, minLength: 1, maxLength: 500 }
+        format: { type: string, enum: [square_1_1, portrait_4_5, story_9_16, landscape_16_9, wide_21_9, photo_3_2, poster_2_3, standard_4_3, auto] }
+    WorkspaceSuggestionItem:
+      allOf:
+        - $ref: "#/components/schemas/BrandSuggestionItem"
+        - type: object
+          required: [job_id, brand]
+          properties:
+            job_id: { type: string, nullable: true, description: "The job behind a generating item, null otherwise." }
+            brand:
+              type: object
+              required: [id, name]
+              properties:
+                id: { type: string }
+                name: { type: string }
+                preview: { $ref: "#/components/schemas/BrandPreview" }
+    CreativeDirectionsRequest:
+      type: object
+      required: [prompt]
+      properties:
+        prompt:
+          type: string
+          minLength: 8
+          maxLength: 500
+          description: The founder's own description of the brand - what the ranking is against.
+        styles:
+          type: array
+          description: The style chips already picked, if any - catalog ids, not labels.
+          items: { $ref: "#/components/schemas/CreativeDirection/properties/styles/items" }
+    CreativeDirectionsShortlist:
+      type: object
+      required: [palettes, font_pairs, logo_styles]
+      description: >-
+        Catalog ids, best fit first, padded from the catalog's own order so a
+        section is never half empty. Enums are generated from the TypeScript
+        catalogs by scripts/sync-creative-direction-enums.mjs - do not edit by
+        hand.
+      properties:
+        palettes:
+          type: array
+          items: { type: string, enum: [indigo, teal, amber, forest, rose, slate, midnight, coral, sand, plum, ocean, citrus, mono_warm, berry] }
+        font_pairs:
+          type: array
+          items: { type: string, enum: [sora_inter, fraunces_inter, space_inter, playfair_source, dmserif_dmsans, outfit_inter, manrope_manrope, bricolage_inter, instrument_inter, archivo_archivo, lora_lato, syne_inter, epilogue_inter, ibmplex_ibmplex, jost_inter, newsreader_inter, chivo_chivo, unbounded_inter, figtree_figtree, spectral_inter] }
+        logo_styles:
+          type: array
+          items: { type: string, enum: [geometric, rounded, circular, sharp, monogram, lettermark, abstract, emblem, organic, line, gradient, wordmark_only] }
+        rationale:
+          type: string
+          maxLength: 200
+          description: One line on why the top choices fit - shown as a caption, never parsed.
+    NameIdeasRequest:
+      type: object
+      required: [style]
+      properties:
+        style:
+          type: string
+          enum: [compound, abstract, evocative, playful]
+        keyword: { type: string, maxLength: 80 }
+        description: { type: string, maxLength: 500 }
+    NameIdea:
+      type: object
+      required: [name, hint]
+      properties:
+        name: { type: string }
+        hint:
+          type: string
+          description: One line on why the name works - the only thing that distinguishes two invented words to a user.
+    NameIdeasResponse:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/NameIdea" }
+    SurpriseBriefResponse:
+      type: object
+      properties:
+        name: { type: string }
+        tagline: { type: string }
+        description: { type: string }
+        styles:
+          type: array
+          description: >-
+            Catalog ids, not display labels - the creator seeds its style chips
+            with these and matches them against the same ids.
+          items: { type: string, enum: [modern, minimal, bold, playful, elegant, corporate, luxury, organic, geometric, handcrafted, brutalist, editorial, retro, vintage, futuristic, timeless, art_deco, y2k, calm, energetic, warm, technical, rebellious, premium] }
+    JobStep:
+      type: object
+      properties:
+        step:
+          type: string
+          enum: [intake, strategy, visual_system, logo, brand_guardian, applications, render_package, persist_deliver, color_palette, font_pairing, logo_alternative, logo_mono, logo_reversed, logo_wordmark, favicon, brand_guide, business_card, letterhead, mockup, app_icon, og_image, email_signature, hero_image, play_feature_graphic, profile_avatar, social_x, social_linkedin, social_linkedin_personal, social_facebook, social_youtube, social_post, social_story, custom_image, packaging, dna_refine]
+        status: { type: string, enum: [pending, running, completed, failed, skipped] }
+        started_at: { type: string, format: date-time, nullable: true }
+        completed_at: { type: string, format: date-time, nullable: true }
+    GenerationJob:
+      type: object
+      properties:
+        id: { type: string }
+        brand_id: { type: string }
+        kind: { type: string, enum: [brand_generation, asset_regeneration, brand_expand, brand_export, brand_bundle, brand_dna_refine] }
+        workflow_id: { type: string }
+        team_tier: { type: string, enum: [flash, studio, elite] }
+        credit_multiplier: { type: number }
+        status: { type: string, enum: [queued, running, completed, completed_with_errors, failed, canceled] }
+        steps:
+          type: array
+          items: { $ref: "#/components/schemas/JobStep" }
+        credits_reserved: { type: integer }
+        credits_used: { type: integer, nullable: true }
+        eta_seconds: { type: integer, nullable: true }
+        download_url: { type: string, nullable: true }
+        created_at: { type: string, format: date-time }
+    JobEnvelope:
+      type: object
+      properties:
+        job: { $ref: "#/components/schemas/GenerationJob" }
+    LogoSelectionRequest:
+      type: object
+      properties:
+        asset_version_id: { type: string }
+        lockup_override:
+          type: string
+          enum: [horizontal, stacked]
+          description: >-
+            Changes ONLY this approval's logo_alternative render - never the
+            brand's own pinned Logo direction.
+        family_override:
+          type: string
+          description: >-
+            Changes ONLY this approval's logo_alternative wordmark font -
+            never the brand's own typography.heading_font DNA value.
+        ink_override:
+          type: string
+          description: >-
+            Changes ONLY this approval's logo_alternative wordmark ink
+            (main text) colour - never the brand's own DNA palette
+            (color_palette asset). Must be #rrggbb and one of the brand's
+            own generated palette tokens.
+        accent_override:
+          type: string
+          description: >-
+            Changes ONLY this approval's logo_alternative wordmark accent
+            (highlighted run) colour - never the brand's own DNA palette
+            (color_palette asset). Must be #rrggbb and one of the brand's
+            own generated palette tokens.
+        style_seed_override:
+          type: string
+          description: >-
+            Carries forward the "shuffle wordmark style" control's last
+            value so approving does not silently re-roll the treatment the
+            user picked.
+    LogoConceptPalette:
+      type: object
+      properties:
+        tokens:
+          type: array
+          items:
+            type: object
+            properties:
+              hex: { type: string }
+              role: { type: string }
+        # The brand's generated name, from the same concept recipe the tokens
+        # come from. Null on a batch persisted before the strategy was stored
+        # with it. The brand row itself carries only a working name derived
+        # from the prompt until persist_brand_version runs, which is the last
+        # activity before the job completes - so this is the only place the
+        # real name is readable while the concept picker is on screen.
+        brand_name: { type: string, nullable: true }
+    Asset:
+      type: object
+      properties:
+        id: { type: string }
+        brand_id: { type: string }
+        version_id: { type: string, nullable: true }
+        kind: { type: string }
+        name: { type: string }
+        status: { type: string, enum: [queued, generating, ready, failed] }
+        url: { type: string, nullable: true }
+        thumbnail_url: { type: string, nullable: true }
+        credits: { type: integer }
+        pixel_check: { type: integer, nullable: true }
+        qa_report:
+          allOf: [{ $ref: "#/components/schemas/QaReport" }]
+          nullable: true
+        formats:
+          description: >-
+            Downloadable file formats of the effective version, normalized for
+            display (png-1024 and png-256 collapse to PNG). The effective
+            version is version_id's row, or - where an asset has versions but
+            none is current yet (logo concepts awaiting selection) - the latest
+            one, so this can be non-empty while version_id is still null. Empty
+            when the asset has no version at all.
+          type: array
+          items: { type: string }
+        created_at: { type: string, format: date-time }
+    AssetVersion:
+      type: object
+      properties:
+        id: { type: string }
+        asset_id: { type: string }
+        parent_version_id: { type: string, nullable: true }
+        files:
+          type: array
+          items:
+            type: object
+            properties:
+              format: { type: string }
+              content_hash: { type: string }
+              storage_key: { type: string }
+              bytes: { type: integer }
+        credit_cost: { type: integer }
+        qa_report:
+          allOf: [{ $ref: "#/components/schemas/QaReport" }]
+          nullable: true
+        created_at: { type: string, format: date-time }
+    RefineRequest:
+      description: >-
+        A free-text instruction, accepted by `logo` and `logo_wordmark`, or
+        structured treatment overrides, accepted by `logo_wordmark` only.
+      oneOf:
+        - type: object
+          required: [instruction]
+          properties:
+            instruction: { type: string, minLength: 1, maxLength: 500 }
+        - $ref: "#/components/schemas/LogoTreatmentOverrides"
+    VariationRequest:
+      type: object
+      required: [preset]
+      properties:
+        preset:
+          type: string
+          enum:
+            - more_minimal
+            - more_startup
+            - bolder
+            - playful
+            - elegant
+            - geometric
+            - hand_drawn
+            - monochrome
+    RestoreRequest:
+      type: object
+      required: [to_version]
+      properties:
+        to_version: { type: string }
+    LogoTreatmentOverrides:
+      type: object
+      description: >-
+        Structured overrides for wordmark treatment - font, ink (name) colour,
+        accent colour and style variant. At least one field is required.
+      properties:
+        family: { type: string, minLength: 1, maxLength: 200 }
+        ink: { type: string, pattern: "^#[0-9a-fA-F]{6}$" }
+        accent: { type: string, pattern: "^#[0-9a-fA-F]{6}$" }
+        styleSeed: { type: string, minLength: 1, maxLength: 64 }
+        styleIndex:
+          type: integer
+          minimum: 0
+          maximum: 10
+          description: >-
+            Names one of the category's 5 wordmark treatments outright.
+            Preferred over styleSeed, which re-rolls: a nonce lands on the
+            treatment already in force one time in five and names nothing
+            a caller can return to. Persisted on the asset recipe, so
+            every later render of the brand reproduces it.
+    LogoTreatment:
+      type: object
+      description: >-
+        The wordmark/logo's current treatment (font, ink, accent, style) -
+        read from the brand's logo asset's own current-version recipe, the
+        durable source of truth. Provides pre-fill values for the wordmark
+        treatment panel.
+      required: [family, ink, accent, style_seed, style_index]
+      properties:
+        family: { type: string }
+        ink: { type: string, pattern: "^#[0-9a-fA-F]{6}$" }
+        accent: { type: string, pattern: "^#[0-9a-fA-F]{6}$" }
+        style_seed: { type: string }
+        style_index:
+          type: integer
+          minimum: 0
+          maximum: 10
+          nullable: true
+          description: >-
+            Which of the category's 11 wordmark treatments is currently
+            drawn, or null for a brand that has never named one (the
+            renderer then picks by hash, as it always did).
+    MeResponse:
+      type: object
+      properties:
+        user:
+          type: object
+          properties:
+            id: { type: string }
+            clerkUserId: { type: string, nullable: true }
+            email: { type: string, nullable: true }
+            termsAcceptedAt:
+              type: string
+              format: date-time
+              nullable: true
+              description: >-
+                When this membership first accepted the Terms of Service, or null
+                if no acceptance is on record. Scoped to the workspace membership
+                rather than the person. Always null for an API key, which has no
+                membership to read. Reports the earliest acceptance, so it does
+                not track later revisions of the Terms.
+        workspace:
+          type: object
+          properties:
+            id: { type: string }
+            clerkOrgId: { type: string }
+            name: { type: string }
+            plan: { type: string }
+        role: { type: string, enum: [owner, admin, member] }
+    AiTeam:
+      type: object
+      properties:
+        tier: { type: string, enum: [flash, studio, elite] }
+        credit_multiplier: { type: number }
+    WaitlistSignupRequest:
+      type: object
+      required: [email]
+      properties:
+        email: { type: string, format: email }
+        marketing_consent: { type: boolean, default: false }
+        privacy_policy_version: { type: string }
+        attribution: { $ref: "#/components/schemas/WaitlistAttribution" }
+    WaitlistAttribution:
+      description: >-
+        First-touch acquisition snapshot captured on the landing page:
+        utm_* / ad click ids from the entry URL, the external referrer and
+        the entry path. All fields optional; unknown fields are stripped and
+        never persisted.
+      type: object
+      properties:
+        utm_source: { type: string, minLength: 1, maxLength: 512 }
+        utm_medium: { type: string, minLength: 1, maxLength: 512 }
+        utm_campaign: { type: string, minLength: 1, maxLength: 512 }
+        utm_term: { type: string, minLength: 1, maxLength: 512 }
+        utm_content: { type: string, minLength: 1, maxLength: 512 }
+        gclid: { type: string, minLength: 1, maxLength: 512 }
+        fbclid: { type: string, minLength: 1, maxLength: 512 }
+        referrer: { type: string, minLength: 1, maxLength: 512 }
+        landing_page: { type: string, minLength: 1, maxLength: 512 }
+    WaitlistSignupResponse:
+      type: object
+      properties:
+        status: { type: string, enum: [joined] }
+    ConsentCookieRequest:
+      type: object
+      required: [type, region, categories, banner_version, gpc, client_id]
+      properties:
+        type: { type: string, enum: [cookie_consent] }
+        region: { type: string, minLength: 1, maxLength: 16 }
+        categories:
+          type: array
+          maxItems: 16
+          items: { type: string, minLength: 1, maxLength: 64 }
+        banner_version: { type: integer, minimum: 0 }
+        gpc: { type: boolean }
+        client_id: { type: string, minLength: 1, maxLength: 128 }
+    ConsentPrivacyChoiceRequest:
+      type: object
+      required: [type, region, choices, gpc, client_id]
+      properties:
+        type: { type: string, enum: [privacy_choice] }
+        region: { type: string, minLength: 1, maxLength: 16 }
+        choices:
+          type: object
+          additionalProperties: { type: boolean }
+        gpc: { type: boolean }
+        client_id: { type: string, minLength: 1, maxLength: 128 }
+    ConsentTermsAcceptanceRequest:
+      type: object
+      required: [type, checkbox_text, accepted_versions, client_id]
+      properties:
+        type: { type: string, enum: [terms_acceptance] }
+        checkbox_text: { type: string, minLength: 1, maxLength: 512 }
+        accepted_versions:
+          type: object
+          additionalProperties: { type: string, maxLength: 32 }
+        client_id: { type: string, minLength: 1, maxLength: 128 }
+    ConsentPurchaseDisclosureRequest:
+      type: object
+      description: >-
+        What the checkout confirmation step displayed before the buyer approved
+        the purchase (#424). A record of a DISCLOSURE, not of a permission -
+        pressing the pay button is the agreement, and no separate tick for the
+        payment or the renewal is shown. Recorded before the redirect to the
+        payment provider, so `recorded_at` is when the buyer approved, not when
+        the money moved.
+      required:
+        [type, idempotency_key, price_id, kind, amount, currency, billing_period,
+         disclosure_version, client_id]
+      properties:
+        type: { type: string, enum: [purchase_disclosure] }
+        idempotency_key:
+          type: string
+          minLength: 1
+          maxLength: 128
+          description: >-
+            The Idempotency-Key the checkout request carries - what ties this
+            record to one purchase attempt. Not a checkout session id: the
+            session is created by the request this disclosure precedes.
+        price_id: { type: string, minLength: 1, maxLength: 255 }
+        kind: { type: string, enum: [plan, topup] }
+        plan: { type: string, enum: [pro, studio, agency] }
+        credits: { type: integer, enum: [100, 300, 1000] }
+        amount: { type: string, minLength: 1, maxLength: 32 }
+        currency: { type: string, minLength: 1, maxLength: 8 }
+        billing_period: { type: string, enum: [month, one_time] }
+        renewal_text:
+          type: string
+          minLength: 1
+          maxLength: 512
+          description: >-
+            The automatic-renewal sentence as shown. Stored rather than
+            derived, so a later wording change cannot rewrite what a past buyer
+            was told. Absent for a one-time pack, which renews nothing.
+        disclosure_version: { type: integer, minimum: 0 }
+        client_id: { type: string, minLength: 1, maxLength: 128 }
+    ConsentRequest:
+      oneOf:
+        - { $ref: "#/components/schemas/ConsentCookieRequest" }
+        - { $ref: "#/components/schemas/ConsentPrivacyChoiceRequest" }
+        - { $ref: "#/components/schemas/ConsentTermsAcceptanceRequest" }
+        - { $ref: "#/components/schemas/ConsentPurchaseDisclosureRequest" }
+      discriminator:
+        propertyName: type
+        mapping:
+          cookie_consent: "#/components/schemas/ConsentCookieRequest"
+          privacy_choice: "#/components/schemas/ConsentPrivacyChoiceRequest"
+          terms_acceptance: "#/components/schemas/ConsentTermsAcceptanceRequest"
+          purchase_disclosure: "#/components/schemas/ConsentPurchaseDisclosureRequest"
+    ConsentResponse:
+      type: object
+      required: [id, recorded_at]
+      properties:
+        id: { type: string }
+        recorded_at: { type: string, format: date-time }
+    ApiKey:
+      type: object
+      properties:
+        id: { type: string }
+        name: { type: string }
+        environment: { type: string, enum: [live, test] }
+        prefix: { type: string }
+        last4: { type: string }
+        requests: { type: integer }
+        credits: { type: integer }
+        created_at: { type: string, format: date-time }
+        last_used_at: { type: string, format: date-time, nullable: true }
+        created_by_email: { type: string, nullable: true, description: "Null for keys created before this field existed." }
+    ApiKeyWithSecret:
+      allOf:
+        - { $ref: "#/components/schemas/ApiKey" }
+        - type: object
+          properties:
+            secret: { type: string }
+    CreateApiKeyRequest:
+      type: object
+      required: [name]
+      properties:
+        name: { type: string, minLength: 1, maxLength: 80 }
+        environment:
+          type: string
+          enum: [live, test]
+          default: live
+          description: >
+            A label only - a test key reaches the real workspace and spends
+            real credits exactly like a live one.
+    WebhookEndpoint:
+      type: object
+      properties:
+        id: { type: string }
+        url: { type: string, format: uri }
+        events:
+          type: array
+          items: { $ref: "#/components/schemas/WebhookEventType" }
+        disabled: { type: boolean }
+        created_at: { type: string, format: date-time }
+    WebhookEndpointWithSecret:
+      allOf:
+        - type: object
+          properties:
+            endpoint: { $ref: "#/components/schemas/WebhookEndpoint" }
+            secret: { type: string }
+    CreateWebhookEndpointRequest:
+      type: object
+      required: [url, events]
+      properties:
+        url: { type: string, format: uri }
+        events:
+          type: array
+          minItems: 1
+          items: { $ref: "#/components/schemas/WebhookEventType" }
+    UpdateWebhookEndpointRequest:
+      type: object
+      properties:
+        events:
+          type: array
+          minItems: 1
+          items: { $ref: "#/components/schemas/WebhookEventType" }
+        disabled: { type: boolean }
+    WebhookEventType:
+      type: string
+      enum:
+        - brand.completed
+        - brand.updated
+        - asset.ready
+        - asset.regenerated
+        - job.failed
+        - credits.low
+        - credits.settled
+        - subscription.changed