{
  "openapi": "3.1.0",
  "info": {
    "title": "Rendry API",
    "version": "1.6.0",
    "description": "Template-based image generation API. Design a template in the visual editor (or via POST /presets), then render on-brand images with one call. Every capability the MCP server exposes as a tool is reachable over REST as well — same implementation behind both, so the two never drift. For AI agents a remote MCP endpoint is available at /mcp (streamable HTTP) — see https://rendry.io/llms-full.txt. Every refusal, on every door, is one JSON object {error: machine code, message: sentence, …fields} with the HTTP status of its class — see the Refusal schema; an MCP tool error carries the same object as its text.\n\nAuthentication: four bearer credentials open the render and template doors — a persisted live or test API key (sk_live_… / sk_test_…), the browser session of the signed-in owner (the JWT POST /auth/login returns) a connector token (the JWT the OAuth flow issues to an MCP client), and an ephemeral editor session (em_…). Browser/OAuth credentials may select a current team membership with X-Rendry-Account; API keys and embed sessions are bound to their persisted account and cannot switch accounts. GET /principal returns the resolved authority. Roles and scopes intersect; a removed member immediately loses access. Test mode is persisted on the credential: renders retain all admission limits, cost zero credits and carry a RENDRY TEST watermark; test credentials cannot publish public links. Operations that list the `session` scheme alone are the account cabinet: an API key is refused there with 401, a connector token with 403 `browser_session_required` (account deletion: `account_deletion_needs_session`). Operations with an empty `security` are public.\n\nAlso served, not described operation by operation: GET /templates/{id}/preview.png and GET /template-assets/{name} (public; the gallery's pictures), GET /assets/library (public; the built-in image stock), GET /plans, GET /billing/config and GET /version (public; prices and the running build), GET /openapi.json (public; this document), POST /feedback (public, rate-limited by IP) and POST /feedback/agent (render credentials), the OAuth 2.1 doors under /oauth (the three /.well-known discovery documents, /register, /authorize, /client-info, /token — public; POST /oauth/decision takes the owner's session), the guest batch under /batch-tasks/guest (public, rate-limited by IP: POST /preview, POST, GET /{token}, GET /{token}/archive), the sign-in, sign-up, e-mail verification and password doors under /auth (public; POST /auth/verify/resend takes the owner's session), the cabinet's POST /user/password, POST /checkout, GET /billing/history, GET /billing/subscription, GET /photos/search and POST /photos/used (owner's session only), the payment webhooks POST /billing/webhook and POST /billing/webhook/{provider} (signed by the provider), the /internal/* doors of the render nodes (internal token) and the /admin group (administrators, session only).",
    "contact": {
      "url": "https://rendry.io"
    }
  },
  "servers": [
    {
      "url": "https://rendry.io/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKey": []
    },
    {
      "session": []
    },
    {
      "connector": []
    },
    {
      "embed": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key sk_live_... or sk_test_... — create at Settings → API Keys. Every key has a scope (read, render or full — see the APIKey schema); a call the scope does not cover answers 403 with `error` = `api_key_scope_insufficient`, the refused `tool`, the key's `scope`, and a `message` naming what the key can call. A key limited to a list of presets answers a preset outside it with 403 `api_key_preset_not_allowed` and the refused `preset_id`; such a key renders and edits only its listed presets, and an inline design (canvas + layers, a document page or master of its own), a draft or a new template is refused with 403 `api_key_limited_to_presets` and a `reason` (inline_design, draft, create_template, inline_page). RESERVED: no door issues a key limited to presets yet — POST /user/api-keys hands out keys for the whole account — so `api_key_preset_not_allowed` and `api_key_limited_to_presets` are documented for clients built ahead of that door and are not answered by any key issued today."
      },
      "session": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "The browser session of the signed-in owner: the JWT POST /auth/login (or the SSO door) returns, sent as `Authorization: Bearer <jwt>`. Opens every render and template door and, alone, the account cabinet (API keys, account deletion, password, billing)."
      },
      "connector": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "The token the OAuth 2.1 flow under /oauth issues to an MCP client (claude.ai connectors): the same JWT shape as a session, tagged as issued to a connector. Opens the render and template doors and /mcp; every cabinet door refuses it with 403 `browser_session_required`, account deletion with 403 `account_deletion_needs_session`."
      },
      "embed": {
        "type": "http",
        "scheme": "bearer",
        "description": "Ephemeral em_... token redeemed by the origin-restricted embedded editor. Its account, trusted subject, role and live/test mode are persisted server-side. It cannot access account administration, billing, account-wide batch services or public links. Never persist or put it in a URL."
      }
    },
    "headers": {
      "RetryAfter": {
        "description": "Seconds to wait before retrying. Set on every 429 the render doors answer: the per-account request limit, the concurrency limit of live renders and the public link's daily budget.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "schemas": {
      "Refusal": {
        "type": "object",
        "description": "Every refusal of every door (status 400 and above), on REST and as the JSON text of an MCP tool error. `error` is a stable machine code to branch on; `message` is an English sentence for the log or the agent. A door that names its condition uses its own code (preset_not_found, unknown_field, variables_unresolved, insufficient_credits, api_key_scope_insufficient, …) and adds its fields beside the two; any other refusal carries the code of its HTTP status class: 400 invalid_input (invalid_request when the body is not the JSON the door reads), 401 unauthorized / invalid_token / invalid_api_key, 403 forbidden, 404 not_found, 405 method_not_allowed (with `allow`), 408/504 timeout, 409 conflict, 413 request_too_large (with `limit_bytes`), 422 unprocessable, 429 rate_limit_exceeded, 500 internal_error, 502/503 service_unavailable. A path that does not exist answers 404 not_found and a wrong method 405 before any credential is read. The message never carries our infrastructure's text (hosts, drivers, Go type names).",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine code, snake_case."
          },
          "message": {
            "type": "string",
            "description": "What was refused and what to do, in English."
          },
          "fields": {
            "type": "array",
            "description": "unknown_field: each key the door does not read, with the nearest known key. Nothing was run or charged. A near miss (a typo of one or two letters, a known alias) is not refused: it is renamed and reported in the reply: `autofixes` on /render/sync, /render/async, /batch-tasks, /assets/import and /user/api-keys; `autofixed_fields` on the doors that run an MCP tool (/render/batch, /render/preview, PATCH /presets/{id}, components, theme, clone, palette).",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "The key as sent, with its path: `items[0].filenme`."
                },
                "did_you_mean": {
                  "type": "string"
                }
              }
            }
          },
          "diagnostics": {
            "type": "array",
            "description": "variables_unresolved: why the template's variables do not resolve for this call. Never a source, a supplied value or a result. Absent on the public /u/ link, whose visitor is not the template's author.",
            "items": {
              "$ref": "#/components/schemas/VariableDiagnostic"
            }
          },
          "prompt": {
            "type": "string",
            "description": "art_missing: the resolved art description."
          },
          "prepare_art": {
            "$ref": "#/components/schemas/PrepareArtRequest"
          },
          "style_id": {
            "type": "string",
            "description": "An unavailable or unowned art style."
          },
          "generate_asset": {
            "type": "object",
            "description": "Exact cache-sharing repair for inline layouts, drafts, document masters and document-specific variable or page facts. Generate the supplied resolved prompt, then retry the render.",
            "properties": {
              "style_id": {
                "type": "string"
              },
              "prompt": {
                "type": "string"
              },
              "aspect": {
                "type": "string"
              }
            }
          },
          "credits_charged": {
            "type": [
              "number",
              "null"
            ],
            "description": "generate_asset and prepare_art operation refusals report the confirmed net charge after refunds. Null means a paid outcome could not be confirmed; never assume no charge from an unreadable outcome. Common authentication, authorization and protocol refusals before tool dispatch may omit this field."
          },
          "balance": {
            "type": [
              "number",
              "null"
            ],
            "description": "Current credit-ledger balance on generate_asset and prepare_art operation refusals; null when it could not be read. Unrelated tools and common refusals before tool dispatch may omit this field."
          }
        },
        "additionalProperties": true
      },
      "VariableDiagnostic": {
        "type": "object",
        "description": "One reason a variable does not resolve (spec 007). Names, codes, positions — never a source string, a supplied value or a resolved value.",
        "required": [
          "code",
          "severity"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/VariableDiagnosticCode"
          },
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ]
          },
          "variable": {
            "type": "string",
            "description": "The definition or supplied input the problem belongs to; empty for a context-wide limit."
          },
          "reference": {
            "type": "string",
            "description": "The referenced name (unknown_reference, nonnumeric_operand)."
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "A cycle, its first name repeated at the end."
          },
          "reason": {
            "type": "string",
            "description": "A stable sub-code: which syntax rule or which limit."
          },
          "span": {
            "type": "object",
            "description": "Half-open range of Unicode code points in the definition's source.",
            "properties": {
              "start": {
                "type": "integer"
              },
              "end": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Preset": {
        "type": "object",
        "description": "A stored template as GET /presets/{id} returns it: the DSL POST /presets accepted plus the ids the server assigned. `id` is this VERSION; `preset_group_id` is the template, the value every render, patch, share and delete-group door takes as the preset id.",
        "properties": {
          "id": {
            "type": "string",
            "description": "This version's id; changes on every saved version"
          },
          "user_id": {
            "type": "string"
          },
          "preset_group_id": {
            "type": "string",
            "description": "The template's id, stable across versions — what /render/*, PATCH, /share and DELETE /presets/{id}/group take"
          },
          "parent_id": {
            "type": "string",
            "description": "The version this one was saved over or forked from"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "preview_key": {
            "type": "string",
            "description": "Storage key of the server-made preview picture; fetch it as /files/{preview_key}"
          },
          "version_note": {
            "type": "string",
            "description": "Label of an explicitly marked version; routine saves carry none"
          },
          "canvas": {
            "$ref": "#/components/schemas/Canvas"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Ordinary DSL layers; text layers may opt into document continuation with text_flow (see TextFlow). The authoritative native text_flows receipt is returned before charge in dry runs. Text may use text_overflow:\"clip_lines\" with positive integer max_lines and explicit width. It keeps complete native lines without an ellipsis after full-source auto_fit/fit_group; height is optional and never a second line cap. Plates size retained content; text_flow cannot truncate. Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata. Image layers may declare generate (ImageGenerate): style_id, prompt and optional aspect. Rendering reads prepared art; a nonempty dynamic_key URL wins."
          },
          "modifications": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Sample values of the {variables}: the defaults of every render that omits a key"
          },
          "variable_modes": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "text",
                "template",
                "formula"
              ]
            },
            "description": "How each modifications source is read; a missing name is text"
          },
          "sample_rows": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            "description": "Sample rows of repeat groups and tables; a call's rows override them"
          },
          "derived": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Colours derived from an image layer, as in PresetInput"
          },
          "palettes": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "description": "Colours a field takes from data, as in PresetInput"
          },
          "variable_formats": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "$ref": "#/components/schemas/DisplayFormat"
            },
            "description": "Sparse name -> display format beside modifications and variable_modes. A name needs a source in modifications and cannot be page, pages or row.*. Applied after source evaluation and also to caller overrides; formulas consume raw exact values while templates insert formatted text. Invalid schema refuses save; invalid data refuses dry run and render before any charge, without echoing values. update_preset patches: absent or {} keeps; name:null removes; top-level null clears. Whole preset and document saves replace the map."
          }
        }
      },
      "PresetWriteResult": {
        "type": "object",
        "description": "The reply of POST /presets and PUT /presets/{id}/current. preset_id and preset_group_id carry the SAME value — the template's group id, which every render, patch, share and delete-group door takes; version_id is the row this write produced (what GET /presets rows show as `id`).",
        "required": [
          "preset_id",
          "preset_group_id",
          "version_id",
          "status",
          "variables"
        ],
        "properties": {
          "preset_id": {
            "type": "string",
            "description": "The template's group id (equal to preset_group_id)"
          },
          "preset_group_id": {
            "type": "string"
          },
          "version_id": {
            "type": "string",
            "description": "The version written: the id GET /presets rows show"
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "updated"
            ]
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every name the written template accepts in dynamic_data, sorted. For a template that computes, the names a caller supplies — not the computed ones. The same list the MCP create_preset and update_preset tools return."
          },
          "autofixes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Fields renamed on the way in (e.g. font_size read as size) — send the canonical names from now on"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What will look broken in the output; fix before rendering"
          }
        }
      },
      "PresetPatchResult": {
        "type": "object",
        "description": "The reply of PATCH /presets/{id}: the same JSON the MCP tool update_preset returns.",
        "properties": {
          "preset_id": {
            "type": "string",
            "description": "The template's group id"
          },
          "preset_group_id": {
            "type": "string",
            "description": "The template's group id, equal to preset_id"
          },
          "version_id": {
            "type": "string",
            "description": "The exact version row written by this patch"
          },
          "parent_id": {
            "type": "string",
            "description": "The exact predecessor version read before applying this patch"
          },
          "name": {
            "type": "string"
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every {variable} the patched layers accept in dynamic_data"
          },
          "inputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InputDescriptor"
            },
            "description": "Present for a template that computes some of its values (a template or formula definition): the class, mode and dependencies of every name. Absent otherwise."
          },
          "hint": {
            "type": "string"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Findings about the FINAL state after the patch; empty when the layout checks found nothing"
          },
          "warnings_note": {
            "type": "string",
            "description": "What the warnings list covers"
          },
          "chart_fit": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Measured geometry of every chart layer; sent only when the preset has one"
          },
          "palettes": {
            "type": "object",
            "description": "The data palettes in force, when the preset declares any"
          },
          "autofixed_fields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Fields renamed on the way in"
          },
          "autofix_note": {
            "type": "string"
          },
          "image_base64": {
            "type": "string",
            "description": "With preview: true — the updated design as a JPEG"
          },
          "mime_type": {
            "type": "string"
          },
          "look_at_it": {
            "type": "string",
            "description": "With preview: true — what to check on the picture"
          },
          "preview_note": {
            "type": "string",
            "description": "With preview: true — why no picture came back"
          },
          "preview_refusal": {
            "$ref": "#/components/schemas/Refusal"
          }
        }
      },
      "ClonedPreset": {
        "type": "object",
        "description": "The reply of POST /templates/{id}/clone: a renderable preset made from the gallery template.",
        "required": [
          "preset_id",
          "name",
          "variables"
        ],
        "properties": {
          "preset_id": {
            "type": "string",
            "description": "The new template's group id — pass it to /render/*"
          },
          "name": {
            "type": "string"
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every {variable} the template accepts in dynamic_data"
          },
          "sample_data": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Realistic sample values for every variable"
          },
          "hint": {
            "type": "string"
          },
          "duplicate_note": {
            "type": "string",
            "description": "Sent when the account already holds a clone of this template: the slot was spent again"
          }
        }
      },
      "ShareLink": {
        "type": "object",
        "description": "The public link of a template, as POST and GET /presets/{id}/share report it.",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "true while the link is open; {enabled: false} is the whole reply of a closed link"
          },
          "url": {
            "type": "string",
            "description": "Path of the public picture, /u/{token}.png — prefix https://rendry.io; absent while closed. Template variables go on as query parameters (`example` shows this template's own); a parameter named after a computed value overrides it"
          },
          "daily_render_budget": {
            "type": "integer",
            "description": "NEW pictures this link may render a day; cached variants are free"
          },
          "rotated": {
            "type": "boolean",
            "description": "POST only: true when rotate: true issued a NEW url and killed the previous one; false when the reply re-reports the live url (opening an open link never replaces it)"
          },
          "hint": {
            "type": "string",
            "description": "POST only: how to use the link"
          },
          "example": {
            "type": "string",
            "description": "POST only: the url with this template's own first variable and its sample as a query parameter (the same example share_preset_url gives); the bare url when the template has no variables"
          },
          "inputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InputDescriptor"
            },
            "description": "Present for a template that computes some of its values (a template or formula definition): the class, mode and dependencies of every name. Absent otherwise."
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Present with inputs: the names a caller supplies — not the computed ones, which a value sent under their name overrides for the call."
          }
        }
      },
      "BatchTaskAccepted": {
        "type": "object",
        "description": "POST /batch-tasks queued the rows; poll status_url.",
        "required": [
          "task_id",
          "rows_total",
          "enqueued",
          "status_url"
        ],
        "properties": {
          "task_id": {
            "type": "string"
          },
          "rows_total": {
            "type": "integer",
            "description": "Data rows in the table"
          },
          "enqueued": {
            "type": "integer",
            "description": "Rows that reached the render queue; the rest are reported as failed rows in the status"
          },
          "status_url": {
            "type": "string",
            "description": "Path of GET /batch-tasks/{id}, relative to the API origin"
          },
          "delivery": {
            "$ref": "#/components/schemas/DeliveryReceipt"
          }
        }
      },
      "BatchTaskPreview": {
        "type": "object",
        "description": "How the table maps onto the template, and what the batch will cost — nothing is created.",
        "properties": {
          "columns": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Header row of the table"
          },
          "rows_total": {
            "type": "integer"
          },
          "max_cost_credits": {
            "type": "number",
            "description": "What the batch charges up front if every row renders: rows × the page price of this template in the format passed"
          },
          "sample_rows": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "The first data rows, as cells"
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every {variable} the template accepts"
          },
          "suggested_mapping": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "column -> variable, by name"
          },
          "unmatched_variables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Variables no column feeds; they render with the template's sample value"
          },
          "variables_without_sample": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Variables that have neither a column nor a sample: a row that leaves them unfed FAILS"
          },
          "inputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InputDescriptor"
            },
            "description": "Present for a template that computes some of its values (a template or formula definition): the class, mode and dependencies of every name. Absent otherwise."
          },
          "has_prepared_art": {
            "type": "boolean",
            "description": "The saved template declares AI art. Check and prepare its table art before rendering; renders never generate."
          }
        }
      },
      "BatchTaskStatus": {
        "type": "object",
        "description": "Progress of a batch task: counts, every row with its own outcome, and the archive once the run is over.",
        "required": [
          "task_id",
          "status",
          "rows_total",
          "rows_done",
          "rows_failed",
          "rows"
        ],
        "properties": {
          "task_id": {
            "type": "string"
          },
          "preset_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "mapping": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "column -> variable used for this run"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "done",
              "partial",
              "failed"
            ],
            "description": "partial: the run is over with both finished and failed rows"
          },
          "rows_total": {
            "type": "integer"
          },
          "rows_done": {
            "type": "integer"
          },
          "rows_failed": {
            "type": "integer"
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchTaskRow"
            }
          },
          "needs_attention": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Row indexes (idx) that failed or carry warnings; sent when there are any"
          },
          "verdict": {
            "type": "string",
            "description": "One sentence for a person: clean, with warnings, failed — sent with needs_attention"
          },
          "archive_url": {
            "type": "string",
            "description": "Path of GET /batch-tasks/{id}/archive, relative to the API origin; sent once every row is done or failed"
          },
          "delivery": {
            "$ref": "#/components/schemas/DeliveryReceipt"
          }
        }
      },
      "BatchTaskRow": {
        "type": "object",
        "description": "One data row of a batch task and what became of it.",
        "properties": {
          "idx": {
            "type": "integer",
            "description": "0-based row number in the table"
          },
          "data": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "The variables this row fed"
          },
          "render_job_id": {
            "type": "string",
            "description": "The render job; poll-able through GET /render/status/{id}. A row refused before rendering carries a marker instead of an id"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "done",
              "error"
            ]
          },
          "result_url": {
            "type": "string",
            "description": "Path under /api/v1/files/… relative to the API origin — prefix https://rendry.io to download. Historical image results are public. New document attempt files and their page previews require the authenticated owner; a user asset (user_assets/…) is served only to its owner."
          },
          "error": {
            "type": "string"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Layout findings of the finished picture (shrunk or clipped text, a sample photo printed)"
          },
          "ai_content": {
            "type": "string",
            "enum": [
              "composite"
            ],
            "description": "Present only when the rendered output contains an owned AI image; the artifact carries composite AI-content metadata."
          }
        }
      },
      "Asset": {
        "type": "object",
        "description": "A stored file of the account: an image or a TTF/OTF font.",
        "required": [
          "id",
          "file_name",
          "storage_key",
          "url",
          "content_type",
          "size",
          "asset_type",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "storage_key": {
            "type": "string",
            "description": "user_assets/{user}/… — what image layers, /images/* and fonts (font_storage_key) refer to"
          },
          "url": {
            "type": "string",
            "description": "Path under /api/v1/files/… relative to the API origin. NOT a public link: a user asset is served only to its owner's key or session (GET /files/{path}); the renderer reads it internally, so it works in a layer"
          },
          "content_type": {
            "type": "string"
          },
          "size": {
            "type": "integer",
            "description": "Bytes"
          },
          "asset_type": {
            "type": "string",
            "enum": [
              "image",
              "font"
            ]
          },
          "font_family": {
            "type": "string",
            "description": "Fonts only: the family name to put in a text layer's font"
          },
          "created_via": {
            "type": "string",
            "enum": [
              "web",
              "api",
              "derived",
              "ai_api",
              "ai_web"
            ],
            "description": "web: uploaded by a person in the browser; api: uploaded with a key; derived: made by a cutout tool; ai_api: AI image made through an agent surface; ai_web: AI image made by a person in the editor"
          },
          "created_at": {
            "type": "string"
          },
          "ai": {
            "type": "boolean",
            "description": "True for an AI image; omitted for ordinary uploads and fonts."
          },
          "provenance": {
            "$ref": "#/components/schemas/AIImageProvenance"
          }
        }
      },
      "AIImageProvenance": {
        "type": "object",
        "description": "Short provenance for an owned AI image. Provider prompts and reference URLs or storage keys are not exposed here.",
        "required": [
          "prompt",
          "model",
          "references",
          "created_at"
        ],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The stored user prompt."
          },
          "model": {
            "type": "string"
          },
          "references": {
            "type": "integer",
            "description": "Number of style references."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AssetUploaded": {
        "type": "object",
        "description": "The reply of the multipart POST /assets.",
        "required": [
          "id",
          "file_name",
          "url",
          "storage_key",
          "size",
          "asset_type"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Path under /api/v1/files/…, served to the owner only (see Asset.url)"
          },
          "storage_key": {
            "type": "string"
          },
          "size": {
            "type": "integer"
          },
          "asset_type": {
            "type": "string",
            "enum": [
              "image",
              "font"
            ]
          },
          "font_family": {
            "type": "string",
            "description": "Fonts only"
          }
        }
      },
      "PhotoPalette": {
        "type": "object",
        "description": "Dominant colours of a photo and the roles suggested for a layout around it.",
        "properties": {
          "colors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "hex": {
                  "type": "string"
                },
                "share": {
                  "type": "number",
                  "description": "Fraction of the measured pixels"
                }
              }
            }
          },
          "suggestion": {
            "type": "object",
            "properties": {
              "background": {
                "type": "string"
              },
              "support": {
                "type": "string"
              },
              "accent": {
                "type": "string"
              }
            }
          },
          "measured_over": {
            "type": "string",
            "description": "What was measured: the whole photo, or the frame passed"
          },
          "roles": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "bg, support, accent, on and the ranked colours 0..5 — the names a derived colour is addressed by"
          },
          "hint": {
            "type": "string"
          }
        }
      },
      "Cutout": {
        "type": "object",
        "description": "A cutout saved to the account's files (asset_type image, created_via derived).",
        "required": [
          "url",
          "storage_key",
          "file_name"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "Absolute URL of the PNG; served to the owner only, like every user asset"
          },
          "storage_key": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          },
          "evicted_note": {
            "type": "string",
            "description": "Sent when the asset slots were full and the OLDEST previous cutout was removed to make room"
          },
          "image_base64": {
            "type": "string",
            "description": "A JPEG preview of the cutout"
          },
          "mime_type": {
            "type": "string"
          }
        }
      },
      "CreditCost": {
        "type": "object",
        "description": "What this call took and what is left.",
        "properties": {
          "credits_charged": {
            "type": "number"
          },
          "balance": {
            "type": "number"
          }
        }
      },
      "BatchRenderResponse": {
        "type": "object",
        "description": "The reply of POST /render/batch: every item's outcome. The run stops at the first item the balance cannot pay for.",
        "required": [
          "rendered",
          "total",
          "items"
        ],
        "properties": {
          "rendered": {
            "type": "integer",
            "description": "Items that finished"
          },
          "total": {
            "type": "integer"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchRenderItem"
            }
          },
          "hint": {
            "type": "string"
          },
          "cost": {
            "$ref": "#/components/schemas/CreditCost"
          },
          "needs_attention": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Item indexes with warnings; sent when there are any"
          },
          "delivery": {
            "$ref": "#/components/schemas/DeliveryReceipt"
          },
          "task_id": {
            "type": "string",
            "description": "Durable batch identity for delivery status; present with deliver_to."
          },
          "status_url": {
            "type": "string",
            "description": "Durable batch identity for delivery status; present with deliver_to."
          }
        }
      },
      "BatchRenderItem": {
        "type": "object",
        "required": [
          "index",
          "status"
        ],
        "properties": {
          "index": {
            "type": "integer"
          },
          "job_id": {
            "type": "string",
            "description": "Poll-able through GET /render/status/{id}"
          },
          "status": {
            "type": "string",
            "description": "success, error, insufficient_credits or quota_exceeded"
          },
          "result_url": {
            "type": "string",
            "description": "Absolute URL of the file (https://rendry.io/api/v1/files/…): the tool-bridge doors return full links, the native REST doors return paths."
          },
          "error": {
            "type": "string"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ai_content": {
            "type": "string",
            "enum": [
              "composite"
            ],
            "description": "Present only when the rendered output contains an owned AI image; the artifact carries composite AI-content metadata."
          }
        }
      },
      "Generation": {
        "type": "object",
        "description": "One render job of the account, as the feed shows it.",
        "required": [
          "id",
          "status",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Path under /api/v1/files/… relative to the API origin — prefix https://rendry.io to download. Historical image results are public. New document attempt files and their page previews require the authenticated owner; a user asset (user_assets/…) is served only to its owner."
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "done",
              "error"
            ]
          },
          "preset_id": {
            "type": "string"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "format": {
            "type": "string"
          },
          "page_count": {
            "type": "integer",
            "description": "Documents: pages in the file"
          },
          "channel": {
            "type": "string",
            "enum": [
              "ui",
              "api",
              "agent"
            ],
            "description": "ui: the editor; api: REST and batch doors; agent: MCP"
          },
          "error": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          }
        }
      },
      "GenerationsResponse": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Generation"
            }
          },
          "next_cursor": {
            "type": "string",
            "description": "Pass as `before` to fetch the next page; absent at the end of the feed"
          }
        }
      },
      "DocumentOverview": {
        "type": "object",
        "description": "One row of GET /documents: a light listing entry, not the document. `pages` is the page COUNT; GET /documents/{id} returns the pages themselves.",
        "required": [
          "id",
          "name",
          "pages"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "pages": {
            "type": "integer",
            "description": "Number of pages"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "format": {
            "type": "string",
            "description": "Output format of the first page's canvas, when it names one"
          },
          "canvas": {
            "type": "object",
            "properties": {
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              },
              "output_format": {
                "type": "string",
                "description": "Set when the first page is a document canvas"
              }
            }
          },
          "sketch": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "t": {
                  "type": "string"
                },
                "x": {
                  "type": "number"
                },
                "y": {
                  "type": "number"
                },
                "w": {
                  "type": "number"
                },
                "h": {
                  "type": "number"
                }
              }
            },
            "description": "Top-level layer boxes (t = layer type) for a thumbnail sketch before a preview exists"
          },
          "composition": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Top-level layer count per type, e.g. {\"text\": 2, \"image\": 1}; group children are not counted"
          }
        }
      },
      "DocumentPageRef": {
        "type": "object",
        "description": "A page of a STORED document. On input a page may name preset_id; the server copies that template's canvas and layers in and stores the copy, so a stored page always carries its own content and later edits of the template never change the document.",
        "properties": {
          "canvas": {
            "$ref": "#/components/schemas/DocumentCanvas"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Ordinary DSL layers. Text may use text_overflow:\"clip_lines\" with positive integer max_lines and explicit width. It keeps complete native lines without an ellipsis after full-source auto_fit/fit_group; height is optional and never a second line cap. Plates size retained content; text_flow cannot truncate. Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata."
          },
          "modifications": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "This page's sample values; a render's dynamic_data overrides them"
          },
          "variable_modes": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "name -> text | template | formula, as on a preset"
          },
          "derived": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Colours derived from an image layer, as on a preset"
          },
          "sample_rows": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            "description": "Sample rows of the page's repeat groups and tables"
          },
          "palettes": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          },
          "preset_id": {
            "type": "string",
            "description": "Input only: the template to copy in. Not stored — the copied canvas and layers are"
          },
          "label": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "fixed"
            ],
            "description": "repeat_over_rows is reserved for when per-item arrays arrive"
          },
          "variable_formats": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "$ref": "#/components/schemas/DisplayFormat"
            },
            "description": "Sparse name -> display format beside modifications and variable_modes. A name needs a source in modifications and cannot be page, pages or row.*. Applied after source evaluation and also to caller overrides; formulas consume raw exact values while templates insert formatted text. Invalid schema refuses save; invalid data refuses dry run and render before any charge, without echoing values. update_preset patches: absent or {} keeps; name:null removes; top-level null clears. Whole preset and document saves replace the map."
          }
        }
      },
      "DocumentPage": {
        "type": "object",
        "description": "A page of a RENDER request: {preset_id, dynamic_data} or the page's own {canvas, layers}. No required field: \"one of two\" is expressible only through oneOf, which clients support unevenly — the server checks the choice and its refusal names both paths.",
        "properties": {
          "canvas": {
            "$ref": "#/components/schemas/DocumentCanvas",
            "description": "Own page content instead of preset_id"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Ordinary DSL layers; text layers may opt into document continuation with text_flow (see TextFlow). The authoritative native text_flows receipt is returned before charge in dry runs. Text may use text_overflow:\"clip_lines\" with positive integer max_lines and explicit width. It keeps complete native lines without an ellipsis after full-source auto_fit/fit_group; height is optional and never a second line cap. Plates size retained content; text_flow cannot truncate. Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata."
          },
          "modifications": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "An own-content page's sources for its {variables}, as PresetInput.modifications; dynamic_data overrides them"
          },
          "variable_modes": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "text",
                "template",
                "formula"
              ]
            },
            "description": "Same shape and rules as PresetInput.variable_modes: an own-content page owns its definitions, a schema problem refuses the save, an unresolvable definition refuses the render before any charge (dry_run included), and a page-dependent value (one that reads page or pages) read by the text of a paginating auto-height table is refused as circular_layout_dependency. A page that only names a preset inherits the preset's sources and modes; a reference to a preset with modes cannot also carry its own modifications or variable_modes — make it an own-content page, or pass per-call values as dynamic_data."
          },
          "derived": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "sample_rows": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            }
          },
          "rows": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            "description": "This page's rows for a table bound to rows_key; overrides the document-wide rows"
          },
          "palettes": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          },
          "preset_id": {
            "type": "string"
          },
          "dynamic_data": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "This page's substitutions; override the document-wide dynamic_data"
          },
          "kind": {
            "type": "string",
            "enum": [
              "fixed"
            ]
          },
          "variable_formats": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "$ref": "#/components/schemas/DisplayFormat"
            },
            "description": "Sparse name -> display format beside modifications and variable_modes. A name needs a source in modifications and cannot be page, pages or row.*. Applied after source evaluation and also to caller overrides; formulas consume raw exact values while templates insert formatted text. Invalid schema refuses save; invalid data refuses dry run and render before any charge, without echoing values. update_preset patches: absent or {} keeps; name:null removes; top-level null clears. Whole preset and document saves replace the map."
          },
          "rows_refs": {
            "$ref": "#/components/schemas/RowsReferences",
            "description": "Page source overrides either document-wide source kind; same-scope rows+rows_refs for the same key refuses, including empty inline rows"
          }
        }
      },
      "GuideSectionRefusal": {
        "type": "object",
        "description": "GET /design-guide?section= named a section that does not exist.",
        "required": [
          "error",
          "sections"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "sections": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every section name the door answers to"
          },
          "hint": {
            "type": "string"
          }
        }
      },
      "VersionConflict": {
        "type": "object",
        "description": "PUT /presets/{id}/current: the `id` sent is no longer the latest version — somebody saved from another tab, an agent or the API in between. Nothing was written; reload the template (GET /presets/{id}) and redo the edit on the version it returns.",
        "required": [
          "error",
          "preset_group_id"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "preset_changed_elsewhere"
            ]
          },
          "preset_group_id": {
            "type": "string"
          }
        }
      },
      "CanvasFinishProfile": {
        "type": "object",
        "required": [
          "id",
          "field",
          "label",
          "description",
          "formats",
          "cost_class",
          "min_dimension",
          "requires_transparent"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Exact versioned value accepted by Canvas.finish_profile. Values are generated from the runtime finish registry."
          },
          "field": {
            "type": "string",
            "description": "Public DSL path where the id is written."
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "formats": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Output formats accepted by this profile."
          },
          "cost_class": {
            "type": "string"
          },
          "min_dimension": {
            "type": "integer",
            "description": "Minimum final width and height in pixels."
          },
          "requires_transparent": {
            "type": "boolean",
            "description": "Whether the profile requires a fully transparent canvas background."
          }
        }
      },
      "Canvas": {
        "type": "object",
        "properties": {
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "background_color": {
            "type": "string"
          },
          "output_format": {
            "type": "string"
          },
          "quality": {
            "type": "integer"
          },
          "max_width": {
            "type": "integer"
          },
          "finish_profile": {
            "type": "string",
            "description": "Optional whole-canvas finish applied once after composition using the profile-specific paint policy. Use an exact id from the finish_profiles field returned by GET /capabilities; that runtime catalog also declares compatible formats and minimum dimensions."
          }
        },
        "additionalProperties": true
      },
      "DocumentCanvas": {
        "type": "object",
        "description": "Canvas for a PDF or HTML page. Raster-only finish_profile is intentionally unavailable and rejected by the server.",
        "properties": {
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "background_color": {
            "type": "string"
          },
          "output_format": {
            "type": "string",
            "description": "The enclosing document render selects PDF or HTML."
          },
          "dpi": {
            "type": "integer"
          },
          "bleed": {
            "type": "integer"
          },
          "safe_area": {
            "type": "integer"
          },
          "crop_marks": {
            "type": "boolean"
          }
        },
        "not": {
          "required": [
            "finish_profile"
          ]
        },
        "additionalProperties": true
      },
      "PresetInput": {
        "type": "object",
        "required": [
          "name",
          "canvas",
          "layers"
        ],
        "properties": {
          "sample_rows": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            "description": "Sample rows of repeat groups and tables, drawn until a render passes real rows"
          },
          "derived": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Colours FROM a photo: [{\"name\": \"hero\", \"from\": \"<image layer id>\"}]; then $hero.bg | .support | .accent | .on | .0..5 as any colour"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "canvas": {
            "$ref": "#/components/schemas/Canvas"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Ordinary DSL layers. Text may use text_overflow:\"clip_lines\" with positive integer max_lines and explicit width. It keeps complete native lines without an ellipsis after full-source auto_fit/fit_group; height is optional and never a second line cap. Plates size retained content; text_flow cannot truncate. Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata."
          },
          "modifications": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Sources of the template's variables: the sample (default) value of each {name} when dynamic_data does not supply one — or, with a mode in variable_modes, the template or formula that computes it."
          },
          "variable_modes": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "text",
                "template",
                "formula"
              ]
            },
            "description": "How each modifications source is read (grammar and limits: GET /capabilities nested_variables). Missing, null or {} means every source is text, literal. template: {name} inserts that variable's value, {{ and }} print one brace. formula: exact decimal arithmetic (+ - * /, unary signs, parentheses, round(x[, decimals]), min(a,b,...), max(a,b,...), abs(x)) over numbers and {name}; additive grammar 3 adds count({items}) and sum({items},{amount}) over the effective whole rows source. Aggregate brace arguments are source/field handles, not variable edges. Empty count/sum is zero; every needed sum cell must be decimal, with a private one-based row/field refusal before charge. Unused, hidden and overridden aggregates read nothing; table and aggregate sources share the fetch cache/budget. Aggregate-dependent visible_if inside link_dest/follows refuses before reads; a literal controller override is allowed; a terminating result prints in full, a repeating one is rounded to nested_variables.projection_digits significant digits. A mode needs a source under the same name; page and pages are engine facts and take no mode; row.* names take none. A save refuses a schema problem (VariableDiagnosticCode invalid_mode, invalid_name, reserved_name, unsupported_row_scope, source_limit) and writes nothing; a definition that does not resolve from the saved values is saved and named in warnings, and a render refuses it before any charge unless dynamic_data supplies a literal for it. dynamic_data is always literal: a supplied value replaces the definition of that name for the call and is never parsed as a template or a formula. What a caller sends and what the template computes is told apart by InputDescriptor."
          },
          "palettes": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "description": "Colours a field takes from data: {\"tier\": {\"gold\": \"#C9A227\", \"default\": \"#444444\"}}. A colour field then refers to one by the variable that chooses it — \"fill_color\": \"{tier}\" reads dynamic_data.tier, and inside a repeat the row's own tier field. An unknown value takes \"default\"; a palette without one refuses the render and names the values it admits."
          },
          "variable_formats": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "$ref": "#/components/schemas/DisplayFormat"
            },
            "description": "Sparse name -> display format beside modifications and variable_modes. A name needs a source in modifications and cannot be page, pages or row.*. Applied after source evaluation and also to caller overrides; formulas consume raw exact values while templates insert formatted text. Invalid schema refuses save; invalid data refuses dry run and render before any charge, without echoing values. update_preset patches: absent or {} keeps; name:null removes; top-level null clears. Whole preset and document saves replace the map."
          }
        },
        "additionalProperties": true
      },
      "Capabilities": {
        "type": "object",
        "properties": {
          "bind_measured": {
            "type": "boolean",
            "description": "This build supports formulas over measured sibling layers in image presets. Full rules and recipes: GET /design-guide?section=bind. Documents refuse."
          },
          "bind_measured_metrics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Supported metric names, generated from the engine measurement table."
          },
          "finish_profiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CanvasFinishProfile"
            },
            "description": "Whole-canvas finishes generated from the runtime registry."
          },
          "nested_variables": {
            "$ref": "#/components/schemas/NestedVariables",
            "description": "Present only when this build interprets variable_modes; a client gates authoring of templates and formulas on it and never downgrades them silently. Without ?sections= the whole struct is served, limits included; ?sections=nested_variables serves it alone. MCP get_capabilities carries grammar_version in its working set and the rest under that section."
          },
          "service_policy": {
            "type": "object",
            "description": "Typed rate, concurrency, lifetime and analytics-header contract; mirrors x-rendry-service-policy and is available through sections=service_policy.",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "NestedVariables": {
        "type": "object",
        "required": [
          "grammar_version"
        ],
        "properties": {
          "grammar_version": {
            "type": "integer",
            "description": "The template and formula grammar, the exact arithmetic and the text projection this build interprets. Compare it with the version your client was written for; refuse to author modes on a mismatch."
          },
          "projection_digits": {
            "type": "integer",
            "description": "Precision boundary: the significant digits a repeating decimal is rounded to (nearest, halves away from zero) when a formula result becomes text. A terminating decimal prints in full; a formula reading another formula receives the exact value, not the projection."
          },
          "limits": {
            "$ref": "#/components/schemas/VariableLimits"
          }
        }
      },
      "VariableLimits": {
        "type": "object",
        "description": "The resource contract of one effective context (one render, one batch row, one document page). Each limit is checked BEFORE the work it bounds; passing one is a named refusal (source_limit, node_limit, depth_limit, numeric_limit, output_limit) before any charge. A template without a template or formula definition is never judged by these; the text caps still apply to it.",
        "properties": {
          "names": {
            "type": "integer",
            "description": "definition, supplied-input and fact names of one context, once a template or formula is active"
          },
          "name_bytes": {
            "type": "integer",
            "description": "a name in an explicit mode and every reference; names are ASCII"
          },
          "value_code_points": {
            "type": "integer",
            "description": "one source, supplied value or expanded value, in Unicode scalar values — the same cap as max_text_chars"
          },
          "aggregate_source_bytes": {
            "type": "integer",
            "description": "all definition sources plus supplied values, UTF-8"
          },
          "definition_nodes": {
            "type": "integer",
            "description": "formula AST nodes or template segments of one definition"
          },
          "aggregate_nodes": {
            "type": "integer",
            "description": "their sum over the active definitions"
          },
          "fuel": {
            "type": "integer",
            "description": "evaluation work of one context, in units of instructions, emitted segments, digit parses and arithmetic operand words"
          },
          "depth": {
            "type": "integer",
            "description": "the longest dependency chain below a definition"
          },
          "nesting": {
            "type": "integer",
            "description": "parentheses plus unary signs inside one formula"
          },
          "aggregate_output_bytes": {
            "type": "integer",
            "description": "all computed text of one context, UTF-8"
          },
          "token_digits": {
            "type": "integer",
            "description": "digits of one decimal operand, leading and trailing zeros included"
          },
          "rational_bits": {
            "type": "integer",
            "description": "a reduced numerator and a reduced denominator, each"
          },
          "scratch_bits": {
            "type": "integer",
            "description": "every intermediate product or sum of the arithmetic"
          },
          "format_scratch_bits": {
            "type": "integer",
            "description": "the scaled integers of a decimal projection"
          }
        }
      },
      "VariableDiagnosticCode": {
        "type": "string",
        "description": "The stable codes of variable diagnostics (specs/007-nested-variables/contracts/language.md). A diagnostic names the variable, the code, a reason sub-code, the referenced name, a cycle path and a code-point span in the source — never a source string, a supplied value or a result. A schema problem refuses the save (invalid_name, invalid_mode, reserved_name, unsupported_row_scope, source_limit) and nothing is written; a definition that does not resolve from the saved values is saved and named in the save's warnings; at render every unresolvable definition refuses the request before any charge (400, nothing rendered, nothing charged) with the same codes.",
        "enum": [
          "invalid_name",
          "invalid_mode",
          "invalid_format",
          "invalid_format_value",
          "reserved_name",
          "unsupported_row_scope",
          "unsupported_reference_scope",
          "template_syntax",
          "formula_syntax",
          "unknown_reference",
          "cycle",
          "nonnumeric_operand",
          "division_by_zero",
          "numeric_limit",
          "source_limit",
          "node_limit",
          "depth_limit",
          "output_limit",
          "circular_layout_dependency"
        ]
      },
      "InputDescriptor": {
        "type": "object",
        "description": "One name of a template that computes some of its values: the `inputs` of POST /presets/{id}/share, POST /batch-tasks/preview and the MCP preset tools, beside `variables` (what a caller sends). Present only for a template with a template or formula definition. Never carries a source or a value.",
        "required": [
          "name",
          "class",
          "used"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "class": {
            "type": "string",
            "enum": [
              "required",
              "defaulted",
              "computed",
              "fact"
            ],
            "description": "required: referenced and never authored — send it, or the render refuses. defaulted: an authored text a caller may replace. computed: a template or formula the template evaluates; a literal a caller sends replaces it for that call and cuts its dependencies. fact: page or pages, the engine's — cannot be supplied."
          },
          "mode": {
            "type": "string",
            "enum": [
              "text",
              "template",
              "formula"
            ],
            "description": "The authored mode of a definition; absent for a name that has none."
          },
          "dependencies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The names a computed definition references, sorted."
          },
          "used": {
            "type": "boolean",
            "description": "Content reaches this name, directly or through computed definitions. An unused authored definition is still listed: removing one is an explicit act. Not what a render needs: every template and formula is evaluated on every render, drawn or not, so a required name that only an undrawn definition reads is still required and is listed in `variables`."
          },
          "format": {
            "$ref": "#/components/schemas/DisplayFormat"
          }
        }
      },
      "RenderRequest": {
        "type": "object",
        "properties": {
          "preset_id": {
            "type": "string",
            "description": "Template ID from GET /presets. Either this or draft_id."
          },
          "draft_id": {
            "type": "string",
            "description": "Draft returned by an inline preview (POST /render/preview with canvas+layers). Renders ONCE, charged as a normal render, no template slot spent, and dynamic_data does not apply to it. Either this or preset_id, not both. Accepted by POST /render/sync only; /render/async refuses it, because a draft renders once and is not queued."
          },
          "dynamic_data": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Variable substitutions: text variables take text, dynamic image slots take a public image URL"
          },
          "webhook_url": {
            "type": "string",
            "description": "Async only: POST-ed {job_id,status,result_url} on completion; the outcome of that call is reported as webhook on GET /render/status/{id}. Must be an http or https address on the public internet: an unparseable address, another scheme, an internal host name or a literal private, loopback or link-local IP is refused with 400 invalid_webhook_url before anything is queued or charged."
          },
          "preview": {
            "type": "boolean",
            "description": "POST /render/sync only: cap the file at 640 px on the long side and charge the preview price (0.1 credit) — the same price on every channel, api key or signed-in session, because the price follows the capped file and not the transport. Rejected for pdf/html, and refused by POST /render/async, which always renders the full page at the full price."
          },
          "format": {
            "type": "string",
            "enum": [
              "png",
              "jpeg",
              "webp",
              "pdf",
              "html"
            ],
            "description": "Overrides the template's canvas.output_format for this call only. pdf/html render the DOCUMENT profile."
          },
          "quality": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "jpeg/webp only. Accepts a number sent as a string."
          },
          "max_width": {
            "type": "integer",
            "description": "Downscale the finished canvas to this width, proportions kept, never upscales. Rejected for pdf/html."
          },
          "rows": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            "description": "Arrays of rows for repeat groups AND for a table bound to rows_key: {\"items\": [{\"name\":\"Coffee\",\"price\":\"3.50\"}, ...]}. A group with repeat.source=\"items\" clones its children once per row and values arrive as {row.key} in content and url, and a bound size or position reads them in its bind formula; a table with rows_key=\"items\" takes each row as a body row, mapped onto its columns by columns[i].key"
          },
          "preview_pages": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "pdf only: pages to also return as raster previews of the finished file, free of extra charge and capped like any preview. Page 1 comes back when the field is absent; at most 3 pages per reply, and a page the render does not have is refused before any charge. POST /render/sync renders ONE page, so only [1] applies there and the pictures arrive in its own page_previews; on POST /render/async and POST /render/document they arrive at GET /render/status/{id} once the job is done."
          },
          "watermark": {
            "$ref": "#/components/schemas/RenderWatermark"
          },
          "pdf_password": {
            "$ref": "#/components/schemas/PDFPassword"
          },
          "deliver_to": {
            "$ref": "#/components/schemas/DeliverTo"
          }
        },
        "description": "Exactly one of preset_id or draft_id names the design to render. These two doors sell a FINAL render and always deliver the whole page, so they refuse a region outright, \"preview\": true included; to read one box of a large page, call POST /render/preview, whose body describes region and whose reply carries region and scale."
      },
      "TextPlateFit": {
        "type": "object",
        "description": "Actual unrotated text plate assembly in DSL pixels, before effects and output scaling. Text coordinates identify the logical text box, not tight glyph bounds.",
        "required": [
          "x",
          "y",
          "width",
          "height",
          "text_x",
          "text_y",
          "text_width"
        ],
        "properties": {
          "x": {
            "type": "integer",
            "description": "Plate left relative to the layer origin"
          },
          "y": {
            "type": "integer",
            "description": "Plate top relative to the layer origin"
          },
          "width": {
            "type": "integer",
            "description": "Assembled plate width after minimum size and circle sizing"
          },
          "height": {
            "type": "integer",
            "description": "Assembled plate height after minimum size and circle sizing"
          },
          "text_x": {
            "type": "integer",
            "description": "Logical text origin inside the plate, including stroke and bearing placement"
          },
          "text_y": {
            "type": "integer",
            "description": "Logical text origin inside the plate"
          },
          "text_width": {
            "type": "integer",
            "description": "Resolved advance or constrained wrap width"
          }
        }
      },
      "TextRotationOrigin": {
        "type": "object",
        "description": "Actual pre-transform assembly center of ordinary raster text relative to the layer origin, in DSL pixels. Half-pixel centers are preserved.",
        "required": [
          "x",
          "y"
        ],
        "properties": {
          "x": {
            "type": "number"
          },
          "y": {
            "type": "number"
          }
        }
      },
      "TextFit": {
        "type": "object",
        "description": "What the finished render MEASURED for one text layer. Every number is in DSL layout coordinates.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The measured layer's own id. This is why text_fit is a list: the entry names its layer, the list does not"
          },
          "plate": {
            "$ref": "#/components/schemas/TextPlateFit",
            "description": "Present only for an assembled text plate"
          },
          "rotation_origin": {
            "$ref": "#/components/schemas/TextRotationOrigin",
            "description": "Present for ordinary raster text with rotation or flips; native document text uses its own placement"
          },
          "raster_top": {
            "type": "integer",
            "description": "Where the raster image put the top of the text block under vertical_align center or bottom, in whole pixels below the layer's y; absent for top alignment, no box height, a plate, and PDF or HTML output"
          },
          "size": {
            "type": "integer",
            "description": "The size that was asked for"
          },
          "fitted_size": {
            "type": "integer",
            "description": "The size auto_fit settled on; equal to size when nothing shrank"
          },
          "text_w": {
            "type": "integer",
            "description": "Width of the rendered text mask"
          },
          "text_h": {
            "type": "integer",
            "description": "Height of the rendered text mask"
          },
          "box_w": {
            "type": "integer",
            "description": "Declared layer width; 0 means unconstrained"
          },
          "box_h": {
            "type": "integer",
            "description": "Declared layer height; 0 means unconstrained"
          },
          "lines": {
            "type": "integer",
            "description": "Lines after wrapping, not only explicit newlines"
          },
          "tracking": {
            "type": "number",
            "description": "The letter spacing the render drew, in px, when auto_fit tightened it to keep the size; absent when the text is drawn at its own letter_spacing. A fit_group member can then be drawn smaller than size and keeps this spacing."
          },
          "wraps": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Where the render broke the text for width: the rune offset, in the text as drawn (variables substituted, list markers and soft hyphens in place, rich_text ** pairs removed), at which each line begins because the line before it was full. A line an explicit newline starts is not listed; absent when nothing wrapped. The editor draws its lines at these offsets"
          },
          "kept_spaces": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Visible-rune offsets of whitespace replaced with non-breaking spaces by keep_last_words. Shares the wraps coordinate system; absent when no spaces changed. The editor applies these exact substitutions before painting."
          },
          "mask_x": {
            "type": "integer",
            "description": "mask_text placement inside a shape or image"
          },
          "mask_y": {
            "type": "integer"
          },
          "mask_w": {
            "type": "integer"
          },
          "mask_h": {
            "type": "integer"
          },
          "ink_top": {
            "type": "integer",
            "description": "Mask offset from the logical text box; a diagnostic, not an alignment source — Pango bounds can include empty rows"
          },
          "ink_left": {
            "type": "integer"
          },
          "fit_group": {
            "type": "string",
            "description": "The layer's fit_group name, present only for a member of one"
          },
          "size_alone": {
            "type": "integer",
            "description": "The size this member would have taken fitted BY ITSELF, before the group levelled. Present only for a member of a fit_group; a layer in no group reports fitted_size and nothing more"
          },
          "fit_group_size": {
            "type": "integer",
            "description": "The size the group settled on — the smallest size_alone among its members. A member whose own min_size is above it keeps min_size, so fitted_size can exceed fit_group_size. Present only for a member of a fit_group"
          },
          "origin": {
            "$ref": "#/components/schemas/TextDiagnosticOrigin"
          },
          "list_paragraphs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListParagraph"
            },
            "description": "Native list geometry on the wraps rune coordinate system; includes blank/trailing paragraphs. Absent for ordinary non-list text."
          },
          "logical_h": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2097151,
            "description": "Native logical block height for lists and clip_lines, including blank lines and fallback-font metrics; absent legacy measurements keep existing line-step behavior."
          },
          "clip_end": {
            "type": "integer",
            "minimum": 0,
            "description": "Exclusive rune endpoint in the final parsed/formatted source, present only when clip_lines removed a suffix. Zero keeps a leading blank line. Slice already parsed styled content before applying wraps/list_paragraphs; this is server observation, never authored DSL."
          },
          "lines_cut": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of complete native lines removed by clip_lines after full-source fitting. lines is the retained count. Absent when no lines were cut."
          }
        }
      },
      "SyncRenderResponse": {
        "type": "object",
        "properties": {
          "mime_type": {
            "type": "string",
            "description": "Effective output MIME type on success, including request overrides."
          },
          "credits_charged": {
            "type": "number",
            "description": "Actual credits debited by this successful render attempt; zero when no charge was made."
          },
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ]
          },
          "result_url": {
            "type": "string",
            "description": "Path under /api/v1/files/… relative to the API origin — prefix https://rendry.io to download. Historical image results are public. New document attempt files and their page previews require the authenticated owner; a user asset (user_assets/…) is served only to its owner."
          },
          "error": {
            "type": "string",
            "description": "On a refusal (status error): the machine code — see Refusal."
          },
          "message": {
            "type": "string",
            "description": "On a refusal: the sentence that explains the code."
          },
          "diagnostics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VariableDiagnostic"
            },
            "description": "On variables_unresolved: why the template's variables do not resolve for this call."
          },
          "text_fit": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TextFit"
            },
            "description": "A LIST, one entry per measured layer, each naming its own layer in `id` — not a map keyed by layer id. Actual per-layer text metrics in DSL layout coordinates: requested size, fitted_size, text_w/text_h and box_w/box_h. Finishing and preview display resizing do not change these values; use geometry to map frames onto the displayed image. The clones of one repeat template arrive COLLAPSED into a single entry that carries the template id, the row count, the worst row and the rows that shrank or overflowed — that entry has collapsed_clones: true and is the only shape that differs from TextFit."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Document profile (pdf/html): which fragments were rasterized and stopped being text."
          },
          "pages_used": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "preset_id of every page actually rendered — the same call twice gives the same list."
          },
          "chart_fit": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "chart_type": {
                  "type": "string"
                },
                "values": {
                  "type": "integer",
                  "description": "how many numbers the series had after dynamic_data was applied"
                },
                "labels": {
                  "type": "integer"
                },
                "y_min": {
                  "type": "number"
                },
                "y_max": {
                  "type": "number",
                  "description": "the scale the ENGINE picked — this is why a bar is that tall"
                },
                "y_step": {
                  "type": "number"
                },
                "bars": {
                  "type": "integer",
                  "description": "bars or sectors actually drawn; fewer than values means some were dropped"
                },
                "labels_drawn": {
                  "type": "integer",
                  "description": "labels that fit the declared gutters; zero with non-zero labels means no room was reserved"
                },
                "plot_w": {
                  "type": "number"
                },
                "plot_h": {
                  "type": "number"
                }
              }
            },
            "description": "What the engine decided about each chart layer: the chosen scale, how many values were drawn and how many labels fit. Computed from the preset and the data, so it also comes back without a render"
          },
          "page_previews": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PagePreview"
            },
            "description": "pdf only: raster pictures of the pages of the file this call just produced — page 1 unless preview_pages named others. Free of extra charge: the pages were drawn in order to make the document. Absent for every other format, and for a pdf whose pictures could not be stored."
          },
          "geometry": {
            "$ref": "#/components/schemas/RenderGeometry"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Server-owned file deadline: authenticated live/test output expires 365 days after completion; guests expire 72 hours after batch creation."
          },
          "ai_content": {
            "type": "string",
            "enum": [
              "composite"
            ],
            "description": "Present only when the rendered output contains an owned AI image; the artifact carries composite AI-content metadata."
          }
        }
      },
      "PagePreview": {
        "type": "object",
        "description": "One rasterised page of a finished pdf. A LINK, not base64: an HTTP client can fetch it, and inlining a courtesy picture would add hundreds of kilobytes to every pdf reply. Fetched exactly like result_url; capped on the long side like any preview.",
        "properties": {
          "page": {
            "type": "integer",
            "description": "1-based page number of the document."
          },
          "url": {
            "type": "string",
            "description": "URL of the stored picture (image/jpeg)."
          },
          "width": {
            "type": "integer",
            "description": "Pixel width of the picture as stored, not of the pdf page."
          },
          "height": {
            "type": "integer"
          }
        }
      },
      "AsyncRenderResponse": {
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "description": "Document output format."
          },
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "status_url": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "pages_used": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "preset_id of every page queued — determinism between calls."
          },
          "pages": {
            "type": "integer",
            "description": "Output page count for document quotes and submissions."
          },
          "cost_credits": {
            "type": "number",
            "description": "Displayed credits for the document. A dry run does not charge."
          },
          "credits_charged": {
            "type": "number",
            "description": "What this call actually took, in credits, at the moment it was queued. Distinct from cost_credits, which a dry run reports for work that is NOT charged."
          },
          "result_wait_ms": {
            "type": "integer",
            "description": "Queued documents only: how long, in milliseconds from this reply, the server allows the job to reach done or error (its admission wait and every final page, plus the time to store the file). Poll at least this long before treating the job as stuck: before then it is still rendering and still charged."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "dry_run: the same warnings the finished job would carry."
          },
          "losses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Loss"
            },
            "description": "dry_run, machine-readable: every layer that will be rasterized."
          },
          "text_searchable": {
            "type": "boolean",
            "description": "dry_run: true when every page's text comes out of the file as the words it was typed as, false when a line stays text and stops being WORDS (letter_spacing past size/20). ABSENT when the document carries no text at all, so a client promises nothing about a sheet of scans."
          },
          "error": {
            "type": "string",
            "description": "On a refusal: the machine code (see Refusal); `message` is its sentence. On 402 it is the credit failure: see balance, required, packages_url."
          },
          "balance": {
            "type": "number",
            "description": "402 only: credits the account has."
          },
          "required": {
            "type": "number",
            "description": "402 only: credits this render needs."
          },
          "packages_url": {
            "type": "string",
            "description": "402 only: where to top up."
          },
          "diagnostics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VariableDiagnostic"
            },
            "description": "On variables_unresolved: why the template's variables do not resolve for this call."
          },
          "row_ranges": {
            "type": "array",
            "description": "Exact body-row placement from the prepared document: 1-based inclusive row ranges per final sheet, excluding the repeated header. Available in dry runs and submission replies. Empty tables use 0/0.",
            "items": {
              "$ref": "#/components/schemas/DocumentRowRange"
            }
          },
          "print": {
            "$ref": "#/components/schemas/PDFPrint"
          },
          "text_flows": {
            "type": "array",
            "maxItems": 800,
            "items": {
              "$ref": "#/components/schemas/TextFlowReceipt"
            }
          },
          "delivery": {
            "$ref": "#/components/schemas/DeliveryReceipt"
          },
          "ai_content": {
            "type": "string",
            "enum": [
              "composite"
            ],
            "description": "Present only when the rendered output contains an owned AI image; the artifact carries composite AI-content metadata."
          }
        }
      },
      "RenderJobStatus": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "done",
              "error"
            ]
          },
          "result_url": {
            "type": "string",
            "description": "Download URL through the API file proxy. New paid document attempt results require the same authenticated owner and use private/no-store caching; obsolete attempts are refused. Historical public render links retain their existing policy."
          },
          "error": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "started_at": {
            "type": "string"
          },
          "completed_at": {
            "type": "string"
          },
          "format": {
            "type": "string",
            "description": "Output format of the finished job: png | jpeg | webp | pdf | html."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Visible warnings from admission and the active worker; paid documents retain bounded per-source snapshots. warnings_omitted explains omitted findings. Compliance receipts use a protected typed field."
          },
          "geometry": {
            "$ref": "#/components/schemas/RenderGeometry"
          },
          "geometry_error": {
            "type": "string",
            "description": "Invalid or inconsistent recorded geometry; geometry is omitted. The completed result URL remains available. Do not infer a replacement transform from image dimensions."
          },
          "page_previews": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PagePreview"
            },
            "description": "pdf only: the available pictures of the requested pages, up to 3 and free of extra charge. Empty while pending; page_preview_status explicitly names requested and missing pages. Pictures of an unfinished job are never advertised."
          },
          "page_preview_status": {
            "$ref": "#/components/schemas/PagePreviewStatus"
          },
          "webhook": {
            "type": "object",
            "description": "Present only when the job was queued with a webhook_url: what became of calling it. The worker calls the webhook once the job is final (one retry after 2 s).",
            "required": [
              "status"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "delivered",
                  "failed",
                  "blocked"
                ],
                "description": "pending — not tried yet; delivered — the endpoint answered 2xx; failed — it could not be reached or did not answer 2xx; blocked — the address is not allowed (its name resolves to a private, loopback or link-local address, or a redirect led to one). Addresses that can be judged without DNS are refused at the door with invalid_webhook_url instead."
              },
              "reason": {
                "type": "string",
                "description": "Why, for failed and blocked. Never contains the webhook URL itself."
              }
            }
          },
          "compliance": {
            "$ref": "#/components/schemas/PDFComplianceReceipt"
          },
          "text_fit": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DocumentDiagnostics"
              },
              {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/TextFit"
                    },
                    {
                      "$ref": "#/components/schemas/LegacyCollapsedTextFit"
                    }
                  ]
                }
              }
            ],
            "description": "Paid documents return an exact-count bounded numeric summary. Historical raw arrays remain readable. Inline/image metrics retain details and wraps. Historical PDF/HTML arrays use the existing legacy summary without claiming prepared table/page provenance (text_fit_status: legacy)."
          },
          "text_fit_status": {
            "type": "string",
            "enum": [
              "pending",
              "unavailable",
              "invalid",
              "collapsed",
              "detailed",
              "legacy"
            ]
          },
          "text_fit_error": {
            "type": "string"
          },
          "warnings_omitted": {
            "type": "integer",
            "description": "Exact findings omitted by the paid document count/encoded-byte policy, including oversized entries; replay does not increase this count."
          },
          "warnings_status": {
            "type": "string",
            "enum": [
              "pending",
              "unavailable",
              "available",
              "invalid"
            ]
          },
          "warnings_error": {
            "type": "string"
          },
          "diagnostics_policy": {
            "$ref": "#/components/schemas/DiagnosticPolicy"
          },
          "print_receipt": {
            "$ref": "#/components/schemas/PDFPrintReceipt"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Persisted server-owned artifact deadline."
          },
          "delivery": {
            "$ref": "#/components/schemas/DeliveryReceipt"
          },
          "ai_content": {
            "type": "string",
            "enum": [
              "composite"
            ],
            "description": "Present only when the rendered output contains an owned AI image; the artifact carries composite AI-content metadata."
          }
        }
      },
      "PresetOverview": {
        "type": "object",
        "description": "One row of GET /presets. `id` is the LATEST VERSION of the template and changes on every save; `preset_group_id` is the template itself — POST /presets returns it as preset_id, and it is what the render, patch, share and delete-group doors take. DELETE /presets/{id} with the version id removes ONE version.",
        "required": [
          "id",
          "user_id",
          "preset_group_id",
          "name",
          "is_public",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The latest version's id"
          },
          "user_id": {
            "type": "string"
          },
          "preset_group_id": {
            "type": "string",
            "description": "The template's id — pass this to the render, patch, share and delete-group doors"
          },
          "parent_id": {
            "type": "string",
            "description": "The version the latest one was saved over"
          },
          "name": {
            "type": "string"
          },
          "preview_url": {
            "type": "string",
            "description": "Path of the preview picture, when one has been rendered"
          },
          "is_public": {
            "type": "boolean",
            "description": "Whether the template has a public link (GET /presets/{id}/share shows it)"
          },
          "canvas": {
            "type": "object",
            "properties": {
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              },
              "output_format": {
                "type": "string",
                "description": "Set when the first page is a document canvas"
              }
            }
          },
          "sketch": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "t": {
                  "type": "string"
                },
                "x": {
                  "type": "number"
                },
                "y": {
                  "type": "number"
                },
                "w": {
                  "type": "number"
                },
                "h": {
                  "type": "number"
                }
              }
            },
            "description": "Top-level layer boxes (t = layer type) for a thumbnail sketch before a preview exists"
          },
          "composition": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Top-level layer count per type, e.g. {\"text\": 2, \"image\": 1}; group children are not counted"
          },
          "version_note": {
            "type": "string",
            "description": "Label of an explicitly marked version"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        }
      },
      "TemplateIndex": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "canvas_size": {
            "type": "string",
            "example": "1080x1080"
          },
          "preview_url": {
            "type": "string"
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Variable names the template accepts via dynamic_data"
          },
          "sample_data": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Realistic example values for every variable"
          },
          "composition": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Top-level layer count per type, e.g. {\"text\": 2, \"image\": 1}; group children are not counted"
          },
          "kind": {
            "type": "string",
            "enum": [
              "document"
            ],
            "description": "Present for PDF document starters; absent for existing image templates"
          },
          "authored_pages": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "Authored pages before table continuation; document starters only"
          }
        }
      },
      "APIKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "key_value": {
            "type": "string",
            "description": "The whole key (sk_live_... or sk_test_...) in the create response, and ONLY there — it is not stored. The list shows the first 12 characters followed by ***."
          },
          "scope": {
            "type": "string",
            "enum": [
              "read",
              "render",
              "full"
            ],
            "description": "What the key may do. read: list and read templates, presets, documents, usage, and price a batch (POST /batch-tasks/preview parses the table and quotes the run, rendering and charging nothing) — no rendering, no changes. render: everything read may, plus render_image, render_batch, render_document and preview_preset (they spend credits) — no template edits or deletions. full: everything, including creating, editing, sharing and deleting templates and files."
          },
          "created_at": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ]
          },
          "actor_id": {
            "type": "string"
          },
          "issued_by_actor_id": {
            "type": "string"
          }
        }
      },
      "UserLimits": {
        "type": "object",
        "properties": {
          "plan": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "presets": {
            "type": "object",
            "properties": {
              "used": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              }
            }
          },
          "assets": {
            "type": "object",
            "properties": {
              "used": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              }
            }
          },
          "upgrade_url": {
            "type": "string",
            "description": "Legacy alias of packages_url."
          },
          "credits": {
            "type": "object",
            "description": "Credit balance — the only thing a render actually fails on.",
            "properties": {
              "balance": {
                "type": "number"
              },
              "spent_on_renders": {
                "type": "number"
              },
              "grant_withheld": {
                "type": "boolean",
                "description": "Starter credits are held until the email is confirmed."
              }
            }
          },
          "packages_url": {
            "type": "string",
            "description": "Where to buy credits."
          },
          "email_verified": {
            "type": "boolean"
          }
        }
      },
      "DocumentTemplate": {
        "type": "object",
        "description": "A stored document as POST, GET and PUT /documents/{id} return it. Pages carry their own content: a page sent as {preset_id} is copied in at save time (see DocumentPageRef). GET /documents lists DocumentOverview rows instead, where `pages` is a count.",
        "required": [
          "name",
          "pages"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "pages": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/DocumentPageRef"
            }
          },
          "master": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Layers under EVERY page: logo, footer, page number ({page}/{pages} are filled in) Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata."
          },
          "master_first": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object"
            },
            "description": "Replacement master for physical page 1, selected after pagination. Omitted/null inherits default; [] is blank. With document_id, omitted/null keeps the saved variant; reset inheritance by saving the document. Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata."
          },
          "master_even": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object"
            },
            "description": "Replacement master for other even physical pages, selected after pagination. Omitted/null inherits default; [] is blank. With document_id, omitted/null keeps the saved variant; reset inheritance by saving the document. Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata."
          },
          "variables": {
            "description": "Shared authored definitions, evaluated independently in each page context. Page definitions replace complete source/mode/format tuples. Literal page dynamic_data overrides request dynamic_data, which overrides authored definitions; final page/pages facts win. document_id inherits omitted/null variables; a supplied list replaces, [] clears. Full saves replace; no dynamic_data is persisted.",
            "items": {
              "$ref": "#/components/schemas/DocumentVariableDefinition"
            },
            "maxItems": 256,
            "type": [
              "array",
              "null"
            ]
          }
        }
      },
      "DocumentRequest": {
        "type": "object",
        "properties": {
          "document_id": {
            "type": "string",
            "description": "Saved template from GET /documents. Either this or pages"
          },
          "pages": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/DocumentPage"
            }
          },
          "dynamic_data": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Shared substitutions for pages without their own"
          },
          "rows": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            "description": "Rows for every page's top-level tables bound to rows_key. A page's own rows win; an absent key retains sample rows, while an explicit empty array clears them. With row_height > 0, body rows paginate in order and the header repeats. Row/cell limits apply to each final page for supplied document rows. At most 20 authored pages and 200 final pages; dry_run quotes the exact row_ranges and cost before submission."
          },
          "dry_run": {
            "type": "boolean",
            "description": "Count, do not draw: page count, price and the layers that will be rasterized. No job, no file, no credits spent"
          },
          "format": {
            "type": "string",
            "enum": [
              "pdf",
              "html",
              "html_embed"
            ],
            "description": "pdf (default) | html — one self-contained HTML file, pages stacked with print page breaks. html_embed is the same format under its older name"
          },
          "webhook_url": {
            "type": "string",
            "description": "POST-ed {job_id,status,result_url} once the document is done; the outcome of that call is reported as webhook on GET /render/status/{id}. Must be an http or https address on the public internet: an unparseable address, another scheme, an internal host name or a literal private, loopback or link-local IP is refused with 400 invalid_webhook_url before anything is priced, queued or charged."
          },
          "compliance": {
            "$ref": "#/components/schemas/PDFCompliance"
          },
          "rows_refs": {
            "$ref": "#/components/schemas/RowsReferences",
            "description": "Page source overrides either document-wide source kind; same-scope rows+rows_refs for the same key refuses, including empty inline rows"
          },
          "print": {
            "$ref": "#/components/schemas/PDFPrint"
          },
          "watermark": {
            "$ref": "#/components/schemas/RenderWatermark"
          },
          "master": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Default master layers; saved default is used when a document_id request supplies none. Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata."
          },
          "master_first": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object"
            },
            "description": "Replacement master for physical page 1, selected after pagination. Omitted/null inherits default; [] is blank. With document_id, omitted/null keeps the saved variant; reset inheritance by saving the document. Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata."
          },
          "master_even": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object"
            },
            "description": "Replacement master for other even physical pages, selected after pagination. Omitted/null inherits default; [] is blank. With document_id, omitted/null keeps the saved variant; reset inheritance by saving the document. Every layer, including nested children, accepts an optional literal printable single-line Unicode name label. Absent, null or empty is unnamed; duplicate labels are allowed. C0 controls (U+0000–U+001F), DEL (U+007F), and line/paragraph separators (U+2028/U+2029) are refused. Emoji, RTL and combining marks are preserved. Names never render, substitute variables, or define output IDs or metadata."
          },
          "pdf_password": {
            "$ref": "#/components/schemas/PDFPassword"
          },
          "variables": {
            "description": "Shared authored definitions, evaluated independently in each page context. Page definitions replace complete source/mode/format tuples. Literal page dynamic_data overrides request dynamic_data, which overrides authored definitions; final page/pages facts win. document_id inherits omitted/null variables; a supplied list replaces, [] clears. Full saves replace; no dynamic_data is persisted.",
            "items": {
              "$ref": "#/components/schemas/DocumentVariableDefinition"
            },
            "maxItems": 256,
            "type": [
              "array",
              "null"
            ]
          },
          "deliver_to": {
            "$ref": "#/components/schemas/DeliverTo"
          }
        }
      },
      "Loss": {
        "type": "object",
        "description": "One loss of the document profile, machine-readable — next to the prose in warnings, not instead of it.",
        "properties": {
          "page": {
            "type": "integer"
          },
          "layer_id": {
            "type": "string"
          },
          "layer_type": {
            "type": "string"
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Why it goes raster: rotation, shadow, mask, plate_shape, image_fill and so on."
          },
          "whole_page": {
            "type": "boolean",
            "description": "The whole page was rasterized (in html a blend_mode or backdrop_blur) — single layers are not listed."
          },
          "loses_text": {
            "type": "boolean",
            "description": "This fragment contained text and stopped being text."
          },
          "effect_only": {
            "type": "boolean",
            "description": "Only the listed effects are pixels (in pdf, a text or shape drop shadow): the layer itself stays vector and its text stays searchable."
          }
        }
      },
      "RenderGeometrySize": {
        "type": "object",
        "description": "Positive raster dimensions in pixels.",
        "required": [
          "width",
          "height"
        ],
        "properties": {
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "RenderGeometryRect": {
        "type": "object",
        "description": "Half-open integer pixel-edge rectangle. Transform rectangles have positive extents and are contained in their raster space. Diagnostic alpha bounds may be the all-zero rectangle for empty alpha.",
        "required": [
          "x",
          "y",
          "width",
          "height"
        ],
        "properties": {
          "x": {
            "type": "integer",
            "minimum": 0
          },
          "y": {
            "type": "integer",
            "minimum": 0
          },
          "width": {
            "type": "integer",
            "minimum": 0
          },
          "height": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "RenderGeometryFinish": {
        "type": "object",
        "description": "source_rect is in pre_finish; destination_rect is in output. These rectangles define the transform. source_bounds is diagnostic alpha in pre_finish; artwork_bounds and finished_bounds are diagnostic alpha in output. Alpha bounds never replace the transform.",
        "required": [
          "profile_id",
          "source_rect",
          "destination_rect",
          "source_bounds",
          "artwork_bounds",
          "finished_bounds"
        ],
        "properties": {
          "profile_id": {
            "type": "string",
            "minLength": 1
          },
          "source_rect": {
            "$ref": "#/components/schemas/RenderGeometryRect"
          },
          "destination_rect": {
            "$ref": "#/components/schemas/RenderGeometryRect"
          },
          "source_bounds": {
            "$ref": "#/components/schemas/RenderGeometryRect"
          },
          "artwork_bounds": {
            "$ref": "#/components/schemas/RenderGeometryRect"
          },
          "finished_bounds": {
            "$ref": "#/components/schemas/RenderGeometryRect"
          }
        }
      },
      "RenderGeometry": {
        "type": "object",
        "description": "Geometry of the successful render attempt, bound to job_id and attempt_id. Layout is the DSL coordinate space. Scale layout to pre_finish, map finish.source_rect to finish.destination_rect when present, then scale output to the actual displayed image. Without finish, pre_finish equals output. Display resizing never changes this report. Absent on legacy jobs or document results without raster geometry.",
        "required": [
          "version",
          "job_id",
          "attempt_id",
          "layout",
          "pre_finish",
          "output"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "enum": [
              1
            ]
          },
          "job_id": {
            "type": "string",
            "minLength": 1
          },
          "attempt_id": {
            "type": "string",
            "minLength": 1
          },
          "layout": {
            "$ref": "#/components/schemas/RenderGeometrySize"
          },
          "pre_finish": {
            "$ref": "#/components/schemas/RenderGeometrySize"
          },
          "output": {
            "$ref": "#/components/schemas/RenderGeometrySize"
          },
          "finish": {
            "$ref": "#/components/schemas/RenderGeometryFinish"
          }
        }
      },
      "RenderCompletion": {
        "type": "object",
        "required": [
          "id",
          "job_id",
          "cursor",
          "url",
          "format",
          "page_count",
          "completed_at",
          "credits_charged"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable job id for platform deduplication."
          },
          "job_id": {
            "type": "string"
          },
          "cursor": {
            "type": "string",
            "pattern": "^[0-9]+$",
            "description": "Commit-ordered completion cursor. Keep as a string."
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "preset_id": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "page_count": {
            "type": "integer"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time"
          },
          "credits_charged": {
            "type": "number",
            "description": "Actual successful ledger debit, including preview pricing when applicable. Never estimated from the current template."
          },
          "page_previews": {
            "type": "array",
            "description": "Stored pictures of the PDF pages requested by this render. Empty when none are available; page_preview_status names the requested and missing pages.",
            "items": {
              "$ref": "#/components/schemas/PagePreview"
            }
          },
          "page_preview_status": {
            "$ref": "#/components/schemas/PagePreviewStatus"
          },
          "print_receipt": {
            "$ref": "#/components/schemas/PDFPrintReceipt"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Server-owned file deadline: authenticated live/test output expires 365 days after completion; guests expire 72 hours after batch creation."
          }
        }
      },
      "PagePreviewStatus": {
        "type": "object",
        "required": [
          "status",
          "requested_pages",
          "available_pages",
          "missing_pages"
        ],
        "description": "The requested PDF page pictures and their current storage availability. pending means one or more pictures are unavailable now, including older jobs that never uploaded them; it does not promise a future upload. Re-read status to refresh without rendering or charging again.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "ready"
            ]
          },
          "requested_pages": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "available_pages": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "missing_pages": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      },
      "IntegrationInputs": {
        "type": "object",
        "required": [
          "fields",
          "rows"
        ],
        "description": "Input names and line-item shapes derived from the current template. Excludes formulas, sample values, and engine page facts. Computed output names are not input fields.",
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "required"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "required": {
                  "type": "boolean"
                }
              }
            }
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "source",
                "fields"
              ],
              "properties": {
                "source": {
                  "type": "string"
                },
                "fields": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "DocumentRowRange": {
        "type": "object",
        "required": [
          "authored_page",
          "final_page",
          "layer_id",
          "from_row",
          "to_row"
        ],
        "properties": {
          "authored_page": {
            "type": "integer",
            "minimum": 1
          },
          "final_page": {
            "type": "integer",
            "minimum": 1
          },
          "layer_id": {
            "type": "string"
          },
          "rows_key": {
            "type": "string"
          },
          "from_row": {
            "type": "integer",
            "minimum": 0
          },
          "to_row": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "DisplayFormat": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "number",
              "currency",
              "percent",
              "date",
              "upper",
              "lower"
            ]
          },
          "decimals": {
            "type": "integer",
            "minimum": 0,
            "maximum": 34,
            "default": 0
          },
          "grouping": {
            "type": "boolean",
            "default": false
          },
          "decimal_mark": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1,
            "default": "."
          },
          "group_mark": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1,
            "default": ","
          },
          "symbol": {
            "type": "string",
            "maxLength": 32
          },
          "symbol_position": {
            "type": "string",
            "enum": [
              "prefix",
              "suffix"
            ],
            "default": "prefix"
          },
          "prefix": {
            "type": "string",
            "maxLength": 32
          },
          "suffix": {
            "type": "string",
            "maxLength": 32
          },
          "pattern": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "default": "YYYY-MM-DD"
          }
        },
        "description": "One deterministic display vocabulary. Numbers use exact arithmetic and half away from zero rounding. Currency needs symbol (a symbol or ISO code), with explicit spacing in that text. Percent multiplies a raw ratio by 100. Dates accept strict YYYY-MM-DD only and patterns D, DD, M, MM, MMM, MMMM, YY, YYYY with English month names. upper/lower use Unicode simple case mapping; no locale or multi-character expansions. No format leaves existing text untouched. Fields unrelated to the selected type are refused."
      },
      "CompletionSubscription": {
        "type": "object",
        "required": [
          "id",
          "created_at",
          "start_cursor"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "start_cursor": {
            "type": "string",
            "pattern": "^[0-9]+$",
            "description": "Committed completion cutoff when this subscription began; older retained jobs require explicit replay."
          }
        }
      },
      "CompletionDelivery": {
        "type": "object",
        "required": [
          "id",
          "job_id",
          "status",
          "attempts"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable delivery ID retained across retries and explicit replay; receivers deduplicate it."
          },
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "attempts": {
            "type": "integer"
          },
          "reason": {
            "type": "string",
            "description": "Sanitized delivery outcome; never the secret callback URL."
          }
        }
      },
      "CompletionSubscriptionList": {
        "type": "object",
        "required": [
          "items",
          "limit",
          "delivery_retention_seconds",
          "max_delivery_attempts",
          "max_callback_url_bytes"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompletionSubscription"
            }
          },
          "limit": {
            "type": "integer",
            "const": 10
          },
          "delivery_retention_seconds": {
            "type": "integer",
            "const": 604800
          },
          "max_delivery_attempts": {
            "type": "integer",
            "const": 16
          },
          "max_callback_url_bytes": {
            "type": "integer",
            "const": 4096
          }
        }
      },
      "DocumentCreateInput": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/DocumentTemplate"
          },
          {
            "type": "object",
            "required": [
              "template_id"
            ],
            "additionalProperties": false,
            "properties": {
              "template_id": {
                "type": "string",
                "minLength": 1,
                "description": "A kind:document ID from GET /templates"
              },
              "name": {
                "type": "string",
                "description": "Optional owned-copy name; defaults to the starter name"
              }
            }
          }
        ],
        "description": "Create with authored content, or copy one complete document starter. template_id is request-only; it cannot be combined with pages, master, id or document_id."
      },
      "PDFCompliance": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "mode"
        ],
        "description": "Opt-in independently validated PDF product. pdfa3b uses existing static pages. facturx requires the controlled structured invoice and cannot be combined with pages/document_id/master/dynamic_data/rows. Forms, flatten_form, annotations and hyperlinks are refused before charge. A 48 MiB final-file cap and compliance memory reserve apply. dry_run validates admission and price only; validation receipts appear only on completed status.",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "pdfa3b",
              "facturx"
            ]
          },
          "version": {
            "type": "string",
            "enum": [
              "1.09.2"
            ],
            "description": "Required for facturx, forbidden for pdfa3b."
          },
          "profile": {
            "type": "string",
            "enum": [
              "EN16931"
            ],
            "description": "Required for facturx, forbidden for pdfa3b; no profile downgrade."
          },
          "invoice": {
            "$ref": "#/components/schemas/FacturXInvoice"
          }
        }
      },
      "FacturXParty": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "street",
          "postcode",
          "city",
          "country",
          "vat_id"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "street": {
            "type": "string",
            "maxLength": 80
          },
          "postcode": {
            "type": "string",
            "maxLength": 16
          },
          "city": {
            "type": "string",
            "maxLength": 64
          },
          "country": {
            "type": "string",
            "maxLength": 2,
            "pattern": "^[A-Z]{2}$"
          },
          "vat_id": {
            "type": "string",
            "maxLength": 32
          }
        }
      },
      "FacturXLine": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "description",
          "quantity",
          "unit_price_cents",
          "vat_rate_basis_points"
        ],
        "properties": {
          "description": {
            "type": "string",
            "maxLength": 80
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000
          },
          "unit_price_cents": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000000000
          },
          "vat_rate_basis_points": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000
          }
        }
      },
      "FacturXInvoice": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "number",
          "currency",
          "seller",
          "buyer",
          "iban",
          "lines",
          "issue_date",
          "delivery_date",
          "due_date"
        ],
        "properties": {
          "number": {
            "type": "string",
            "maxLength": 64
          },
          "currency": {
            "type": "string",
            "enum": [
              "EUR"
            ]
          },
          "seller": {
            "$ref": "#/components/schemas/FacturXParty"
          },
          "buyer": {
            "$ref": "#/components/schemas/FacturXParty"
          },
          "iban": {
            "type": "string",
            "description": "Valid uppercase IBAN without spaces."
          },
          "lines": {
            "type": "array",
            "minItems": 1,
            "maxItems": 6400,
            "items": {
              "$ref": "#/components/schemas/FacturXLine"
            }
          },
          "issue_date": {
            "type": "string",
            "format": "date"
          },
          "delivery_date": {
            "type": "string",
            "format": "date"
          },
          "due_date": {
            "type": "string",
            "format": "date"
          }
        },
        "description": "Positive ordinary EUR sales invoice (type 380), C62 integer units and SEPA payment only. Cent arithmetic; half-up VAT per group, at most eight rates. No allowances, charges, exemptions, credit notes, custom layouts or arbitrary attachments. Text must be bounded UTF-8 without controls/template braces. Due date is on/after issue date. Shared table pagination/resource admission determines final page count and price."
      },
      "PDFComplianceReceipt": {
        "type": "object",
        "required": [
          "mode",
          "sha256",
          "verapdf"
        ],
        "properties": {
          "mode": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "profile": {
            "type": "string"
          },
          "sha256": {
            "type": "string"
          },
          "invoice_sha256": {
            "type": "string"
          },
          "verapdf": {
            "type": "string"
          },
          "mustang": {
            "type": "string"
          }
        },
        "description": "Available only after successful upload. SHA-256 binds the exact final PDF bytes and, for facturx, actual embedded invoice bytes. Independent pinned validator versions; PDF/A-3b is explicitly selected. This does not claim PDF/UA, XRechnung or Peppol."
      },
      "RowsReferences": {
        "type": "object",
        "maxProperties": 40,
        "description": "Request-only UTF-8 source names, 1..128 bytes. Across all scopes at most 40 declarations; all declarations including overridden validate before reads. Effective visible table sources fetch once per URL+format under SafeHTTP, 4194304 aggregate bytes and 25 seconds. JSON array objects must have only string values; CSV preserves exact quoted newlines and strings. At most 8000 rows/source and 200 fields/row. Errors never echo URLs or data. Stdio has a separate local path normalization budget; HTTP paths refuse.",
        "additionalProperties": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "url",
            "format"
          ],
          "properties": {
            "url": {
              "type": "string",
              "format": "uri",
              "maxLength": 4096,
              "description": "Absolute public HTTP(S) URL; private host/DNS/redirect addresses refuse"
            },
            "format": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          }
        }
      },
      "TextDiagnosticOrigin": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Server-created prepared structural identity; independent of generated cell IDs."
          },
          "layer_id": {
            "type": "string",
            "description": "Safe authored layer identifier; values and paths are excluded."
          },
          "table": {
            "type": "boolean"
          },
          "master": {
            "type": "boolean"
          },
          "page": {
            "type": "integer",
            "description": "Final page, 1-based."
          },
          "row": {
            "type": "integer",
            "description": "Original body row, 1-based; header and footer row zero."
          },
          "column": {
            "type": "integer",
            "description": "Column, 1-based."
          },
          "header": {
            "type": "boolean"
          },
          "master_kind": {
            "type": "string",
            "enum": [
              "first",
              "even"
            ],
            "description": "Present for replacement-master origins in diagnostics v2; keys use master_first/N or master_even/N. Default-only diagnostics remain v1."
          },
          "footer": {
            "type": "boolean",
            "description": "True for the final table footer; row is zero and header is false."
          }
        }
      },
      "DiagnosticPolicy": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer"
          },
          "max_bytes": {
            "type": "integer"
          },
          "max_entries": {
            "type": "integer"
          },
          "max_problem_locations": {
            "type": "integer"
          }
        }
      },
      "DiagnosticProblem": {
        "type": "object",
        "properties": {
          "location": {
            "$ref": "#/components/schemas/TextDiagnosticOrigin"
          },
          "fit": {
            "$ref": "#/components/schemas/TextFit"
          }
        }
      },
      "TextDiagnosticSummary": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "layer_id": {
            "type": "string"
          },
          "table": {
            "type": "boolean"
          },
          "master": {
            "type": "boolean"
          },
          "measured": {
            "type": "integer"
          },
          "shrunk": {
            "type": "integer"
          },
          "overflowed": {
            "type": "integer"
          },
          "header_cells": {
            "type": "integer"
          },
          "problems": {
            "type": "integer"
          },
          "worst": {
            "$ref": "#/components/schemas/DiagnosticProblem"
          },
          "problem_locations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiagnosticProblem"
            }
          },
          "omitted_problem_locations": {
            "type": "integer"
          },
          "master_kind": {
            "type": "string",
            "enum": [
              "first",
              "even"
            ],
            "description": "Present for replacement-master origins in diagnostics v2; keys use master_first/N or master_even/N. Default-only diagnostics remain v1."
          }
        }
      },
      "DocumentDiagnostics": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer",
            "enum": [
              1,
              2
            ]
          },
          "pages": {
            "type": "integer"
          },
          "measured": {
            "type": "integer"
          },
          "shrunk": {
            "type": "integer"
          },
          "overflowed": {
            "type": "integer"
          },
          "header_cells": {
            "type": "integer"
          },
          "problems": {
            "type": "integer"
          },
          "summaries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TextDiagnosticSummary"
            }
          },
          "omitted_summaries": {
            "type": "integer"
          },
          "omitted_measurements": {
            "type": "integer"
          },
          "omitted_problem_locations": {
            "type": "integer"
          },
          "policy": {
            "$ref": "#/components/schemas/DiagnosticPolicy"
          }
        },
        "description": "Text diagnostics v1 for default-only origins; v2 when first/even origins occur. Policy.version matches. Warning envelopes remain v1. Readers accept both; older v1-only readers cannot interpret replacement masters."
      },
      "LegacyCollapsedTextFit": {
        "type": "object",
        "description": "Historical read-side summaries. These preserve repeat/page/table totals without claiming prepared document provenance.",
        "required": [
          "id"
        ],
        "anyOf": [
          {
            "required": [
              "collapsed_clones"
            ]
          },
          {
            "required": [
              "collapsed_pages"
            ]
          },
          {
            "required": [
              "collapsed_table_cells"
            ]
          }
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "worst": {
            "$ref": "#/components/schemas/TextFit"
          },
          "problem_cells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TextFit"
            }
          },
          "note": {
            "type": "string"
          },
          "collapsed_clones": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "collapsed_pages": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "collapsed_table_cells": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "rows": {
            "type": "integer"
          },
          "measured": {
            "type": "integer"
          },
          "worst_row": {
            "type": "integer"
          },
          "worst_page": {
            "type": "integer"
          },
          "cells": {
            "type": "integer"
          },
          "header_cells": {
            "type": "integer"
          },
          "shrunk": {
            "type": "integer"
          },
          "overflowed": {
            "type": "integer"
          },
          "shrunk_rows_more": {
            "type": "integer"
          },
          "overflowed_rows_more": {
            "type": "integer"
          },
          "problem_cells_more": {
            "type": "integer"
          },
          "shrunk_rows": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "overflowed_rows": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "shrunk_pages": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "overflowed_pages": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      },
      "PDFPrint": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "cmyk"
            ]
          },
          "profile": {
            "type": "string",
            "enum": [
              "aptec-offset-coated-linearctv-2025-v1"
            ],
            "default": "aptec-offset-coated-linearctv-2025-v1"
          }
        },
        "description": "Selected static CMYK document PDF using the named APTEC coated-offset ICC profile. Omission preserves ordinary RGB output. Opaque canvas required; no HTML, PDF/A/Factur-X or interactive forms. Raster/alpha/effect pages are composited then separated and warn about rasterization/loss of searchable text. Supported square/circle/line/ink/underline/strikeout appearances are server-painted; other annotations refuse before charge."
      },
      "PDFPrintPreflight": {
        "type": "object",
        "required": [
          "pages",
          "images",
          "shadings",
          "painted_streams",
          "raster_below_300_dpi"
        ],
        "properties": {
          "pages": {
            "type": "integer",
            "minimum": 0
          },
          "images": {
            "type": "integer",
            "minimum": 0
          },
          "shadings": {
            "type": "integer",
            "minimum": 0
          },
          "painted_streams": {
            "type": "integer",
            "minimum": 0
          },
          "raster_below_300_dpi": {
            "type": "integer",
            "minimum": 0
          },
          "minimum_dpi": {
            "type": "number",
            "minimum": 0
          }
        },
        "description": "Counts from independent inspection of the actual final CMYK PDF resource graph; effective raster placement resolution is checked against the product print DPI. Low resolution is reported, not silently upsampled."
      },
      "PDFPrintReceipt": {
        "type": "object",
        "required": [
          "version",
          "profile",
          "profile_sha256",
          "sha256",
          "color_space",
          "intent",
          "black_point_compensation",
          "preflight"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "enum": [
              1
            ]
          },
          "profile": {
            "type": "string",
            "enum": [
              "aptec-offset-coated-linearctv-2025-v1"
            ]
          },
          "profile_sha256": {
            "type": "string",
            "enum": [
              "2a0a26387276046dc129d4330a7a45542b736c8640e3ec4cb74df809c5ccfb0e"
            ]
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "color_space": {
            "type": "string",
            "enum": [
              "CMYK"
            ]
          },
          "intent": {
            "type": "string",
            "enum": [
              "relative-colorimetric"
            ]
          },
          "black_point_compensation": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "preflight": {
            "$ref": "#/components/schemas/PDFPrintPreflight"
          }
        },
        "description": "Protected receipt bound to the exact uploaded and owner-downloadable final PDF bytes and immutable APTEC profile. Exposed only for the selected done attempt; omitted for ordinary/historical RGB results. This receipt makes no PDF/X certification claim."
      },
      "TextFlowBox": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "x",
          "y",
          "width",
          "height"
        ],
        "properties": {
          "x": {
            "type": "integer",
            "minimum": 0
          },
          "y": {
            "type": "integer",
            "minimum": 0
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "TextFlow": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "continuation"
        ],
        "properties": {
          "continuation": {
            "$ref": "#/components/schemas/TextFlowBox"
          }
        },
        "description": "Optional text_flow on an ordinary layer: native text continuation for one effective top-level page text per PDF/HTML document. Existing 8000 prepared runes / 200 final pages / 25s native precharge bound. Ordinary furniture stays on the first local sheet; masters repeat before the next authored page. Nested/master flows, a second continuing table, page_break, follows/internal destinations, final-page-dependent content/controllers, effects, truncation and autofit refuse before charge. Dry-run text_flows is authoritative; clients must bind it to unchanged inputs and never guess page breaks. Existing columns subdivide first and continuation boxes. Custom and palette-colored list markers are prepared once. Existing letter_spacing and paired bold runs are natively measured; colored markers retain precedence over bold parsing. Uploaded font_storage_key is admitted by ownership and prepared within existing asset bounds into an exact-file native map for coverage and measurement. An unavailable upload refuses before quote as text_flow_unavailable, without fallback. One footnote is numbered from authored reading order and its marker is measured once. Only the final piece carries its prepared note. Occupied boxes on that sheet must clear the existing footnote band; overlap refuses before quote. Note text cannot depend on final page facts. One continuing table may occupy disjoint first and continuation regions beside flow. Independent local sheets zip by index, taking the larger count. Table headers, final footer, whole-source aggregates and original row ranges are preserved. Row and text receipts share the existing transport budget before cell expansion; final-page and resource budgets remain unchanged."
      },
      "TextFlowReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "authored_page",
          "layer_id",
          "final_page",
          "source_from",
          "source_to",
          "box",
          "text",
          "wraps"
        ],
        "properties": {
          "authored_page": {
            "type": "integer",
            "minimum": 1
          },
          "layer_id": {
            "type": "string"
          },
          "final_page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          "source_from": {
            "type": "integer",
            "minimum": 0
          },
          "source_to": {
            "type": "integer",
            "minimum": 0,
            "maximum": 8000
          },
          "box": {
            "$ref": "#/components/schemas/TextFlowBox"
          },
          "text": {
            "type": "string",
            "maxLength": 8000
          },
          "wraps": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 8000
            },
            "maxItems": 8000
          },
          "kept_spaces": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Visible-rune offsets of whitespace replaced with non-breaking spaces by keep_last_words, relative to this chunk's text. Absent when unchanged."
          },
          "list_paragraphs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListParagraph"
            },
            "description": "Native list geometry on the wraps rune coordinate system; includes blank/trailing paragraphs. Absent for ordinary non-list text."
          },
          "column": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4,
            "description": "One-based column in its final sheet. Omitted means column one in legacy single-column receipts."
          },
          "marker_color": {
            "type": "string",
            "description": "Resolved native list prefix color, painted only over list_paragraphs.prefix_runes; empty by default."
          },
          "real_bold": {
            "type": "boolean",
            "description": "Native paint policy, present with nonempty bold_runs. False keeps the regular face, including uploaded fonts. Consumers must use this flag rather than infer support from a font name or weight axis."
          },
          "bold_runs": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "from",
                "to"
              ],
              "properties": {
                "from": {
                  "type": "integer",
                  "minimum": 0
                },
                "to": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "description": "Ordered nonempty half-open plain-rune intervals local to this native literal piece. Already parsed over the complete source; never parse chunk delimiters."
          },
          "footnote": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "text",
              "marker"
            ],
            "properties": {
              "text": {
                "type": "string"
              },
              "marker": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2
              }
            },
            "description": "Prepared literal note with its authored reading-order marker, present only on the final native piece. The marker is already part of measured text; clients draw the strip without appending or numbering it again."
          }
        },
        "description": "Native literal chunk with rune offsets into the canonical LF prepared source including normal list markers. Concatenated text preserves each word once. Wraps are local rune offsets into this literal from the renderer native layout. Available on dry-run and paid submission; no extra billing. Several column pieces can share one final page, filled top to bottom and then left to right. No final-sheet balancing. Prepared bold_runs use the same plain rune stream as text and wraps."
      },
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "personal",
              "team"
            ]
          },
          "name": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "editor",
              "viewer"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "kind",
          "name",
          "created_at"
        ]
      },
      "AccountMember": {
        "type": "object",
        "properties": {
          "actor_id": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "editor",
              "viewer"
            ]
          }
        },
        "required": [
          "actor_id",
          "email",
          "role"
        ]
      },
      "EmbedSession": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "actor_id": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "parent_origin": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ]
          },
          "role": {
            "type": "string",
            "enum": [
              "editor",
              "viewer"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "bootstrap_secret": {
            "type": "string",
            "description": "Only in issue response; one-use secret delivered by the customer server to its authenticated host page in memory."
          },
          "token": {
            "type": "string",
            "description": "Only in redeem response; em_... credential for the same-origin editor child."
          },
          "brand": {
            "$ref": "#/components/schemas/EmbedBrand"
          }
        },
        "required": [
          "id",
          "account_id",
          "actor_id",
          "subject",
          "parent_origin",
          "mode",
          "role",
          "expires_at",
          "brand"
        ]
      },
      "Principal": {
        "type": "object",
        "properties": {
          "actor_id": {
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "editor",
              "viewer"
            ]
          },
          "credential_kind": {
            "type": "string",
            "enum": [
              "browser",
              "oauth",
              "api_key",
              "embed"
            ]
          },
          "credential_id": {
            "type": "string"
          },
          "credential_mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ]
          },
          "trusted_subject": {
            "type": "string",
            "description": "Only for an embed credential; authenticated customer subject, never the X-End-User analytics header."
          },
          "capabilities": {
            "$ref": "#/components/schemas/PrincipalCapabilities"
          },
          "brand": {
            "$ref": "#/components/schemas/EmbedBrand",
            "description": "Only on authenticated embed principals."
          }
        },
        "required": [
          "actor_id",
          "account_id",
          "role",
          "credential_kind",
          "credential_mode",
          "capabilities"
        ]
      },
      "PrincipalCapabilities": {
        "type": "object",
        "properties": {
          "read": {
            "type": "boolean"
          },
          "edit": {
            "type": "boolean"
          },
          "render": {
            "type": "boolean"
          },
          "manage_account": {
            "type": "boolean"
          },
          "publish": {
            "type": "boolean"
          }
        },
        "required": [
          "read",
          "edit",
          "render",
          "manage_account",
          "publish"
        ]
      },
      "RenderWatermark": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "maxLength": 8000
          }
        },
        "description": "Request-only literal UTF-8 stamp. Blank or unreadable final labels refuse before charge. Adds to required test-key marking; price unchanged. Never saved in the design or draft data."
      },
      "ListParagraph": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "rune_offset",
          "prefix_runes",
          "reserve_px",
          "continued",
          "rtl"
        ],
        "properties": {
          "rune_offset": {
            "type": "integer",
            "minimum": 0,
            "description": "Paragraph start in the same final parsed rune stream as wraps, including blank paragraphs."
          },
          "prefix_runes": {
            "type": "integer",
            "minimum": 0,
            "description": "Drawn marker/indent prefix length; zero for a midparagraph flow continuation."
          },
          "reserve_px": {
            "type": "number",
            "description": "Native physical continuation reserve in layout pixels: positive left, negative right, zero centered or unconstrained. Never infer RTL from this sign."
          },
          "continued": {
            "type": "boolean",
            "description": "Keeps an earlier paragraph marker reserve without drawing that marker again."
          },
          "rtl": {
            "type": "boolean",
            "description": "Original native resolved paragraph direction, including empty and continued paragraphs."
          }
        },
        "description": "Measured list paragraph geometry. Bind it and wraps to unchanged render inputs; ordinary non-list text omits this array. Literal list newlines normalize CRLF/CR to LF before formatting."
      },
      "PDFPassword": {
        "type": "string",
        "writeOnly": true,
        "minLength": 1,
        "description": "Request-only PDF open password (AES-256); never returned or saved in designs. Must remain unchanged under the pinned PDF Unicode opening profile and fit 127 UTF-8 bytes; spaces, controls, normalization changes and longer inputs refuse before charge. PDF only, incompatible with PDF/A and Factur-X. Owner password is generated independently. Price unchanged. Internal plaintext is used only for authenticated page previews; only encrypted PDF bytes are delivered."
      },
      "DocumentVariableDefinition": {
        "additionalProperties": false,
        "properties": {
          "format": {
            "description": "Existing variable display format vocabulary, unchanged.",
            "type": "object"
          },
          "mode": {
            "default": "text",
            "enum": [
              "text",
              "template",
              "formula"
            ],
            "type": "string"
          },
          "name": {
            "description": "Existing variable reference grammar; names are unique within this list.",
            "maxLength": 128,
            "type": "string"
          },
          "source": {
            "maxLength": 8000,
            "type": "string"
          }
        },
        "required": [
          "name",
          "source"
        ],
        "type": "object"
      },
      "DeliverTo": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "put_url"
        ],
        "description": "Request-only presigned HTTPS PUT capability. Presign with the output Content-Type. No userinfo, fragment, private address, proxy or redirects. DNS is rechecked at the pinned dial. Never returned, logged, queued or saved in a design. Async renders and batches only, including token-scoped guest batches.",
        "properties": {
          "put_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 4096,
            "writeOnly": true,
            "description": "Byte limit matches maxLength; HTTPS on any port; must address a public server."
          }
        }
      },
      "DeliveryReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status"
        ],
        "description": "Present only when deliver_to was given. A delivery failure does not refund or change the render.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "delivered",
              "failed"
            ]
          },
          "reason": {
            "type": "string",
            "enum": [
              "address",
              "transport",
              "http",
              "source",
              "render",
              "archive",
              "expired"
            ]
          },
          "http_status": {
            "type": "integer",
            "minimum": 100,
            "maximum": 599,
            "description": "Remote status code, only with reason http."
          },
          "notice": {
            "type": "string",
            "const": "The file remains available at Rendry; a delivery failure does not refund the render."
          }
        }
      },
      "GuestBatchTaskAccepted": {
        "type": "object",
        "properties": {
          "guest_token": {
            "type": "string"
          },
          "rows_total": {
            "type": "integer"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "status_url": {
            "type": "string"
          },
          "delivery": {
            "$ref": "#/components/schemas/DeliveryReceipt"
          }
        }
      },
      "EmbedBrandRequest": {
        "type": "object",
        "additionalProperties": false,
        "nullable": true,
        "description": "Optional per-session editor chrome. Empty fields preserve the default identity. Never added to templates or render requests.",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "Trimmed company name; nonempty input must contain visible text and no control characters. Bound by repository.AccountNameMaxLen."
          },
          "logo_url": {
            "type": "string",
            "description": "HTTPS PNG, JPEG or WebP image without URL credentials or fragment. Fetched once after authorization through SSRF-safe transport; snapshot bounded by models.MaxUploadedAssetBytes. Redirects obey the same URL policy. The remote URL is never returned."
          },
          "accent": {
            "type": "string",
            "description": "Opaque models.ParseColor syntax, normalized to hex. Unrounded WCAG contrast must meet EmbedBrandMinContrast on the generated --g2-panel ground; colors identity text and the attribution mark only."
          }
        }
      },
      "EmbedBrand": {
        "type": "object",
        "additionalProperties": false,
        "description": "Authenticated session identity; contains no remote source URL or private logo bytes. Empty brand retains Document editor. Rendry attribution always remains.",
        "properties": {
          "name": {
            "type": "string"
          },
          "logo_url": {
            "type": "string",
            "enum": [
              "/api/v1/embed/brand/logo"
            ],
            "description": "Local authenticated snapshot endpoint. Fetch with bearer authorization into a Blob; never put a bearer token in an image URL."
          },
          "accent": {
            "type": "string"
          }
        }
      },
      "PDFImportReply": {
        "type": "object",
        "required": [
          "preset",
          "background_asset",
          "background_layer_id",
          "warnings"
        ],
        "properties": {
          "preset": {
            "$ref": "#/components/schemas/Preset"
          },
          "background_asset": {
            "type": "object",
            "required": [
              "id",
              "url",
              "storage_key"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "storage_key": {
                "type": "string"
              }
            }
          },
          "background_layer_id": {
            "type": "string",
            "description": "Editor-session lock instruction; never persisted in the preset."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "CreateUploadRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "filename",
          "size"
        ],
        "properties": {
          "filename": {
            "type": "string",
            "description": "Filename without path separators. Unicode names are supported."
          },
          "size": {
            "type": "integer",
            "description": "Exact file size in bytes, within the uploaded-asset limit."
          },
          "content_type": {
            "type": "string",
            "description": "PNG, JPEG, WebP or TTF/OTF MIME type; guessed from the filename when omitted."
          }
        }
      },
      "UploadSession": {
        "type": "object",
        "required": [
          "upload_url",
          "method",
          "expires_at",
          "max_bytes",
          "curl"
        ],
        "properties": {
          "upload_url": {
            "type": "string",
            "format": "uri",
            "description": "One-use bearer URL on this API. Keep it secret; send the local file with PUT."
          },
          "method": {
            "type": "string",
            "enum": [
              "PUT"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "max_bytes": {
            "type": "integer"
          },
          "curl": {
            "type": "string"
          }
        }
      },
      "UploadedAsset": {
        "type": "object",
        "required": [
          "id",
          "url",
          "storage_key",
          "file_name",
          "content_type",
          "size"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "storage_key": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "content_type": {
            "type": "string"
          },
          "size": {
            "type": "integer"
          }
        }
      },
      "GenerateImageRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "prompt"
        ],
        "description": "Describe the subject; Rendry adds versioned style, composition and background rules. Identical requests reuse owned assets free. Limits mirror generate_asset and the shared AI image constants.",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "Subject description. Rendry normalizes NFC and whitespace before enforcing x-normalized-max-length; a raw JSON string can be longer when normalization shortens it.",
            "x-normalized-max-length": 1000
          },
          "style_refs": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "string"
            },
            "description": "Owned storage_keys or public HTTPS image URLs whose style to follow; images are sent privately to the provider."
          },
          "aspect": {
            "type": "string",
            "enum": [
              "1:1",
              "3:2",
              "2:3",
              "4:3",
              "3:4",
              "16:9",
              "9:16"
            ],
            "default": "1:1"
          },
          "background": {
            "type": "string",
            "enum": [
              "as_prompted",
              "white",
              "transparent"
            ],
            "description": "Omit to use the saved background when style_id is provided, otherwise as_prompted. An explicit value overrides the saved background."
          },
          "n": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4,
            "default": 1
          },
          "variation": {
            "type": "integer",
            "minimum": 0,
            "default": 0,
            "description": "Change this value to request new art for otherwise identical inputs."
          },
          "filename": {
            "type": "string",
            "description": "Optional asset filename; each delivered image gets an indexed PNG name."
          },
          "style_id": {
            "type": "string",
            "description": "Saved ai_style; excludes style_refs. Uses the saved references and pinned prompt rules; omitted background uses the saved background."
          }
        }
      },
      "AIImageOutput": {
        "type": "object",
        "required": [
          "asset_id",
          "url",
          "storage_key",
          "width",
          "height",
          "cached"
        ],
        "properties": {
          "asset_id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "storage_key": {
            "type": "string"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "cached": {
            "type": "boolean"
          }
        },
        "description": "An owned AI asset. Test placeholders have empty asset_id and storage_key and a public placeholder URL."
      },
      "AIImageFailure": {
        "type": "object",
        "required": [
          "index",
          "reason",
          "message"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "reason": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "Image index and safe failure or refusal details; money explains whether refunds are complete."
      },
      "GenerateImageReply": {
        "type": "object",
        "required": [
          "images",
          "credits_charged",
          "balance",
          "rules_version",
          "cached"
        ],
        "description": "Delivered images, actual charge and current balance. Partial success may include failed or refused entries. An identical retry returns saved assets without a new charge. Test keys return free placeholders without storing or calling the provider.",
        "properties": {
          "images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AIImageOutput"
            }
          },
          "credits_charged": {
            "type": [
              "number",
              "null"
            ],
            "description": "Confirmed net charge after refunds. Null when a paid outcome or refund acknowledgement could not be confirmed; partial delivery can also have an unknown charge. Never interpret null as free."
          },
          "balance": {
            "type": [
              "number",
              "null"
            ],
            "description": "Null when the current balance could not be read."
          },
          "rules_version": {
            "type": "integer"
          },
          "cached": {
            "type": "boolean"
          },
          "placeholder": {
            "type": "boolean"
          },
          "money": {
            "type": "string"
          },
          "refund_pending": {
            "type": "boolean",
            "description": "True when a charged image failed and its refund is left to automatic recovery; money states the same in prose."
          },
          "failed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AIImageFailure"
            }
          },
          "refused": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AIImageFailure"
            }
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "image_base64": {
            "type": "string",
            "description": "Inline preview bytes, base64 encoded; present when a preview is available."
          },
          "mime_type": {
            "type": "string"
          },
          "autofixed_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "autofix_note": {
            "type": "string"
          }
        }
      },
      "AIStyleRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action"
        ],
        "description": "Free saved art styles. save requires name and style_refs; list accepts only action; delete and upgrade require only style_id. Same name (case-insensitive within account and end-user subject) updates references and background but preserves rules_version. Omitted background on save is as_prompted. upgrade explicitly selects current rules; new images may differ and cost new generations. URLs and asset IDs are not accepted as saved references.",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "save",
              "list",
              "delete",
              "upgrade"
            ]
          },
          "style_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Trimmed, nonblank name without control characters."
          },
          "style_refs": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "type": "string"
            },
            "description": "Distinct owned image storage_keys from list_assets, never URLs or asset IDs."
          },
          "background": {
            "type": "string",
            "enum": [
              "as_prompted",
              "white",
              "transparent"
            ]
          }
        }
      },
      "AIStyleReference": {
        "type": "object",
        "required": [
          "asset_id"
        ],
        "properties": {
          "asset_id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "storage_key": {
            "type": "string"
          },
          "missing": {
            "type": "boolean",
            "description": "True when the saved reference no longer exists. No URL or storage_key is exposed for a missing reference."
          }
        }
      },
      "AIStyle": {
        "type": "object",
        "required": [
          "id",
          "name",
          "reference_asset_ids",
          "background",
          "rules_version",
          "created_at",
          "updated_at",
          "references",
          "upgrade_available"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "reference_asset_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "background": {
            "type": "string",
            "enum": [
              "as_prompted",
              "white",
              "transparent"
            ]
          },
          "rules_version": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "references": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AIStyleReference"
            }
          },
          "upgrade_available": {
            "type": "boolean"
          }
        }
      },
      "AIStyleReply": {
        "type": "object",
        "properties": {
          "style": {
            "$ref": "#/components/schemas/AIStyle"
          },
          "styles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AIStyle"
            }
          },
          "deleted": {
            "type": "boolean"
          },
          "style_id": {
            "type": "string",
            "format": "uuid"
          },
          "message": {
            "type": "string",
            "description": "Upgrade explains that new images will differ and cost new generations."
          },
          "autofixed_fields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Argument key repairs applied by the shared dispatcher."
          },
          "autofix_note": {
            "type": "string",
            "description": "Explains reported argument repairs."
          }
        }
      },
      "PrepareArtRequest": {
        "type": "object",
        "properties": {
          "preset_id": {
            "type": "string"
          },
          "rows": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "object",
              "properties": {
                "dynamic_data": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                "filename": {
                  "type": "string"
                },
                "rows": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  },
                  "description": "This item's rows for its repeat groups and tables (rows_key)"
                }
              },
              "additionalProperties": false
            },
            "minItems": 1
          },
          "dry_run": {
            "type": "boolean",
            "default": false
          },
          "job_id": {
            "type": "string",
            "format": "uuid"
          },
          "table": {
            "type": "string",
            "description": "A CSV or pasted spreadsheet table, parsed by the same server parser as batch rendering. Alternative to rows."
          },
          "mapping": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Table column to preset variable; empty targets are ignored. Omit to use the server mapping suggestion."
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "$ref": "#/components/schemas/PrepareArtRowsRequest"
          },
          {
            "$ref": "#/components/schemas/PrepareArtJobRequest"
          },
          {
            "$ref": "#/components/schemas/PrepareArtTableRequest"
          }
        ],
        "description": "Send preset_id and rows, or preset_id and table/mapping, to quote or start; job_id alone reads durable progress. Row indexes start at zero. Dry runs create no image/job rows, charge nothing and call no provider."
      },
      "ArtPromptQuote": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "existing",
              "to_make"
            ]
          }
        },
        "required": [
          "prompt",
          "rows",
          "status"
        ]
      },
      "ArtQuote": {
        "type": "object",
        "properties": {
          "distinct": {
            "type": "integer",
            "minimum": 0
          },
          "existing": {
            "type": "integer",
            "minimum": 0
          },
          "to_make": {
            "type": "integer",
            "minimum": 0
          },
          "price_credits": {
            "type": "number",
            "minimum": 0,
            "description": "Total quote for uncached distinct images; cached images are free."
          },
          "limit_check": {
            "type": "object",
            "properties": {
              "fits": {
                "type": "boolean"
              },
              "reason": {
                "type": "string"
              },
              "kind": {
                "type": "string",
                "description": "Admission reason for localization: daily, subject_daily, concurrent, subject_concurrent, slots or budget. Present when fits is false; reason remains the fallback explanation."
              },
              "limit": {
                "type": "integer",
                "minimum": 0,
                "description": "Admission limit for the named kind; omitted for the server provider budget."
              },
              "used": {
                "type": "integer",
                "minimum": 0,
                "description": "Current usage for the named admission limit; omitted for the server provider budget."
              },
              "resets_at": {
                "type": "string",
                "format": "date-time",
                "description": "Next UTC daily reset for daily, subject_daily and budget refusals; other limits clear when running work finishes or asset slots are freed."
              }
            },
            "required": [
              "fits"
            ]
          },
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ArtPromptQuote"
            }
          },
          "autofixed_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "autofix_note": {
            "type": "string"
          },
          "balance": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "Current account balance read from the credit ledger; null only if billing could not be read."
          },
          "credits_charged": {
            "type": "number",
            "minimum": 0,
            "description": "Credits charged so far for this request or job, after refunds; dry runs and job admission charge nothing."
          },
          "unit_price_credits": {
            "type": "number",
            "minimum": 0,
            "description": "The shared per-image price used for this quote."
          }
        },
        "required": [
          "distinct",
          "existing",
          "to_make",
          "price_credits",
          "limit_check",
          "prompts",
          "balance",
          "credits_charged",
          "unit_price_credits"
        ]
      },
      "ArtJobStarted": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid"
          },
          "to_make": {
            "type": "integer",
            "minimum": 0
          },
          "price_credits": {
            "type": "number",
            "minimum": 0,
            "description": "Total quote for uncached distinct images; cached images are free."
          },
          "autofixed_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "autofix_note": {
            "type": "string"
          },
          "balance": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "Current account balance read from the credit ledger; null only if billing could not be read."
          },
          "credits_charged": {
            "type": "number",
            "minimum": 0,
            "description": "Credits charged so far for this request or job, after refunds; dry runs and job admission charge nothing."
          }
        },
        "required": [
          "job_id",
          "to_make",
          "price_credits",
          "balance",
          "credits_charged"
        ]
      },
      "ArtJobProgress": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "done",
              "failed",
              "interrupted"
            ]
          },
          "made": {
            "type": "integer",
            "minimum": 0
          },
          "cached": {
            "type": "integer",
            "minimum": 0
          },
          "failed": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "prompt": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                },
                "refunded": {
                  "type": "boolean"
                }
              },
              "required": [
                "prompt",
                "reason",
                "refunded"
              ]
            }
          },
          "assets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "prompt": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "storage_key": {
                  "type": "string"
                }
              },
              "required": [
                "prompt",
                "url",
                "storage_key"
              ]
            }
          },
          "credits_charged": {
            "type": "number",
            "minimum": 0,
            "description": "Credits charged so far for this request or job, after refunds; dry runs and job admission charge nothing."
          },
          "message": {
            "type": "string"
          },
          "autofixed_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "autofix_note": {
            "type": "string"
          },
          "balance": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "Current account balance read from the credit ledger; null only if billing could not be read."
          }
        },
        "required": [
          "job_id",
          "status",
          "made",
          "cached",
          "failed",
          "assets",
          "credits_charged",
          "balance"
        ]
      },
      "ArtTestPlaceholder": {
        "type": "object",
        "properties": {
          "placeholder": {
            "type": "boolean"
          },
          "to_make": {
            "type": "integer",
            "minimum": 0
          },
          "price_credits": {
            "type": "number",
            "minimum": 0,
            "description": "Total quote for uncached distinct images; cached images are free."
          },
          "message": {
            "type": "string"
          },
          "autofixed_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "autofix_note": {
            "type": "string"
          },
          "balance": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "Current account balance read from the credit ledger; null only if billing could not be read."
          },
          "credits_charged": {
            "type": "number",
            "minimum": 0,
            "description": "Credits charged so far for this request or job, after refunds; dry runs and job admission charge nothing."
          }
        },
        "required": [
          "placeholder",
          "to_make",
          "price_credits",
          "message",
          "balance",
          "credits_charged"
        ]
      },
      "PrepareArtReply": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ArtQuote"
          },
          {
            "$ref": "#/components/schemas/ArtJobStarted"
          },
          {
            "$ref": "#/components/schemas/ArtJobProgress"
          },
          {
            "$ref": "#/components/schemas/ArtTestPlaceholder"
          }
        ]
      },
      "ImageGenerate": {
        "type": "object",
        "properties": {
          "style_id": {
            "type": "string",
            "format": "uuid"
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000,
            "description": "Template placeholders use the text resolver, including row.field inside image repeat groups. The resolved description is checked again at prepare and render."
          },
          "aspect": {
            "type": "string",
            "enum": [
              "1:1",
              "3:2",
              "2:3",
              "4:3",
              "3:4",
              "16:9",
              "9:16"
            ],
            "default": "1:1"
          }
        },
        "required": [
          "style_id",
          "prompt"
        ],
        "additionalProperties": false,
        "description": "Image layers only. A saved style is required to keep a series consistent and pin its rules. Rendering reads prepared art; it never generates. A supplied nonempty dynamic_key URL wins. Missing art refuses before a charge with art_missing and the exact prepare_art call for preset rows, or resolved generate_asset arguments for inline layouts and document-specific context. Test renders use the placeholder on a cache miss."
      },
      "PrepareArtRowsRequest": {
        "type": "object",
        "properties": {
          "preset_id": {
            "type": "string"
          },
          "rows": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "object",
              "properties": {
                "dynamic_data": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                "filename": {
                  "type": "string"
                },
                "rows": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  },
                  "description": "This item's rows for its repeat groups and tables (rows_key)"
                }
              },
              "additionalProperties": false
            },
            "minItems": 1
          },
          "dry_run": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "preset_id",
          "rows"
        ],
        "additionalProperties": false
      },
      "PrepareArtJobRequest": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "job_id"
        ],
        "additionalProperties": false
      },
      "PrepareArtTableRequest": {
        "type": "object",
        "properties": {
          "preset_id": {
            "type": "string"
          },
          "table": {
            "type": "string",
            "description": "A CSV or pasted spreadsheet table, parsed by the same server parser as batch rendering. Alternative to rows."
          },
          "mapping": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Table column to preset variable; empty targets are ignored. Omit to use the server mapping suggestion."
          },
          "dry_run": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "preset_id",
          "table"
        ],
        "additionalProperties": false
      },
      "AssetUse": {
        "type": "object",
        "description": "A design whose current content draws a file.",
        "required": [
          "kind",
          "id",
          "name"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "preset",
              "document"
            ]
          },
          "id": {
            "type": "string",
            "description": "The preset group id, or the document id."
          },
          "name": {
            "type": "string"
          }
        }
      },
      "AssetInUseRefusal": {
        "type": "object",
        "description": "The refusal of a delete of a file templates still draw (error `asset_in_use`). The same body is the JSON text of the MCP delete_asset tool error.",
        "required": [
          "error",
          "message",
          "asset_id",
          "used_by",
          "more"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "asset_in_use"
            ]
          },
          "message": {
            "type": "string",
            "description": "What was refused and what to do, in English."
          },
          "asset_id": {
            "type": "string"
          },
          "used_by": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AssetUse"
            }
          },
          "more": {
            "type": "integer",
            "minimum": 0,
            "description": "Uses not listed in used_by."
          }
        }
      }
    },
    "parameters": {
      "EndUserAnalytics": {
        "name": "X-End-User",
        "in": "header",
        "required": false,
        "description": "Analytics correlation only; never authorizes files or accounts. One safe ASCII value up to 64 bytes. Invalid values return 400. Persisted embedded subject takes precedence. Allowed by CORS.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[A-Za-z0-9_.:@-]{1,64}$"
        }
      },
      "AccountSelector": {
        "name": "X-Rendry-Account",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "description": "Browser/OAuth current member account selector. API keys/embed credentials are bound to their persisted account and reject another account. Omitting this header selects the browser actor personal account."
      }
    }
  },
  "paths": {
    "/assets": {
      "get": {
        "summary": "Your images and fonts",
        "description": "AI images carry ai: true and short provenance. can_delete says whether THIS caller may delete the file: an API key or MCP/OAuth connector may remove agent-created uploads, cutouts and AI images (ai_api), while editor-created AI images (ai_web) stay person-owned. The owner signed in on the web may remove any file.",
        "responses": {
          "200": {
            "description": "Assets, newest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/Asset"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "can_delete": {
                            "type": "boolean",
                            "description": "Whether THIS caller may delete the file: a session may delete anything, a key only what was created through the API"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          }
        },
        "operationId": "listAssets",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      },
      "post": {
        "summary": "Upload an image or a TTF/OTF font (multipart)",
        "description": "The upload door of the web UI and of the stdio MCP server's upload_asset {path}: the file travels as multipart form data, outside any JSON, so a photo never has to be written out as base64. Images PNG, JPEG or WebP up to 5 MB — the content decides the type, not the declared one; fonts TTF or OTF, whose family name comes back as font_family for text layers. Spends an asset slot.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stored",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssetUploaded"
                }
              }
            }
          },
          "400": {
            "description": "`error` is a machine code — file_required, file_too_large (with size and limit in MB), unsupported_file_type, file_not_image or invalid_font_file — and `message` the sentence."
          },
          "401": {
            "description": "Missing/invalid credentials"
          },
          "403": {
            "description": "Every asset slot is taken: the body is the limit refusal (error, used, limit, freeable, upgrade_url)"
          }
        },
        "operationId": "uploadAsset",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/assets/import": {
      "post": {
        "summary": "Import an asset (image or TTF/OTF font) from base64 or a public URL",
        "description": "JSON alternative to the multipart POST /assets. Body: {filename, data_base64|url}. Images ≤5MB (inline base64 is additionally bounded by the 2MB request body; for larger files use url, or POST multipart to /assets). Fonts TTF/OTF. Returns the stored asset; its url is a path under /api/v1/files/… that only the owner's key or session can fetch — user assets are private, the renderer reads them internally, so the url works in a layer but is not a link to hand out. Note: MCP tool calls apply a stricter 96KB cap on data_base64 — inline base64 there costs the calling model output tokens.",
        "responses": {
          "201": {
            "description": "Asset created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Asset"
                }
              }
            }
          },
          "400": {
            "description": "The upload door's codes: `file_required` (empty file), `unsupported_file_type`, `file_not_image`, `invalid_font_file`, `file_too_large` (with `size` and `limit` in MB); `url_rejected`, `download_failed`; `unknown_field` (a key this door does not read) or `invalid_input`. 503 `service_unavailable` when storage fails.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Asset quota exceeded"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "filename": {
                    "type": "string"
                  },
                  "data_base64": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  }
                },
                "required": [
                  "filename"
                ]
              }
            }
          }
        },
        "operationId": "importAsset",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/assets/{id}": {
      "delete": {
        "summary": "Delete an uploaded asset",
        "description": "Frees an asset slot. A file that the current version of one of the account's presets, or one of its saved documents, still draws — as a layer url, an image fill, a font_storage_key or a sample value — is refused with 409 `asset_in_use` and nothing is deleted; older preset versions do not count, and a public link changes nothing. With an API key or an MCP/OAuth connector token only files created through the API can be deleted: a file uploaded by the user in the web UI is an original that may exist nowhere else, and deletion is permanent.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "403": {
            "description": "Uploaded through the web UI — not deletable with an API key or a connector token"
          },
          "404": {
            "description": "No such asset in this account"
          },
          "409": {
            "description": "`asset_in_use`: templates still draw the file. `used_by` names them ({kind, id, name}; a preset is named by its group id, the id GET /presets/{id} opens), at most a capped number, and `more` counts the rest — uses outside an embedded subject's scope are counted, never named. Remove the file from those templates, then delete it again. Nothing was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssetInUseRefusal"
                }
              }
            }
          }
        },
        "operationId": "deleteAsset"
      }
    },
    "/batch-tasks": {
      "post": {
        "summary": "Queue a batch of up to 200 renders from a table",
        "description": "One template x a table of rows, rendered asynchronously. Use this instead of looping /render/batch when the set is bigger than 10: the quota is checked for the WHOLE batch up front, rows go through the shared render queue, and the result is one archive. Poll /batch-tasks/{id} for progress and fetch /batch-tasks/{id}/archive when it is done. Optional deliver_to uploads the stored final output by presigned HTTPS PUT; presign with the output Content-Type. A batch uploads one ZIP after all rows are terminal, byte-identical to its archive download and omitting failed rows; all-failed batches upload nothing (reason render). Delivery never changes the render charge. Retryable transport errors, 5xx and 429 use a bounded attempt count inside one persisted result-transfer deadline; pending requests expire within result retention. Poll delivery status; failed receipts use a fixed reason catalogue and the notice: The file remains available at Rendry; a delivery failure does not refund the render. See capabilities.limits.deliver_to for current budgets.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "preset_id",
                  "table"
                ],
                "properties": {
                  "preset_id": {
                    "type": "string"
                  },
                  "table": {
                    "type": "string",
                    "description": "CSV or TSV with a header row; up to 200 data rows"
                  },
                  "mapping": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "column -> template variable; omit to use the mapping from /batch-tasks/preview"
                  },
                  "rows": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      }
                    },
                    "description": "Row sources for the WHOLE run — the arrays a repeat group or a table's rows_key consumes. A pasted cell is a string, so arrays travel here and not in the table; for a different basket per file, loop over render_image"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "png",
                      "jpeg",
                      "webp",
                      "pdf",
                      "html"
                    ],
                    "description": "Overrides the template's canvas.output_format for every file of the run; omit to keep it. pdf/html render the DOCUMENT profile and are priced per page, an image by canvas area."
                  },
                  "quality": {
                    "type": "integer"
                  },
                  "max_width": {
                    "type": "integer"
                  },
                  "watermark": {
                    "$ref": "#/components/schemas/RenderWatermark"
                  },
                  "pdf_password": {
                    "$ref": "#/components/schemas/PDFPassword"
                  },
                  "deliver_to": {
                    "$ref": "#/components/schemas/DeliverTo"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "400": {
            "description": "Refused before anything is charged. `error` is a machine code (batch_table_empty, batch_table_no_rows, batch_table_ragged_row, batch_too_many_rows, batch_table_too_big, batch_table_unparseable, batch_mapping_mismatch, batch_row_invalid, batch_output_invalid), its numbers ride beside it (row, rows, limit, cells, columns, unknown_columns, unknown_variables, variables, detail; a row whose variables do not resolve adds `diagnostics`), and `message` is the English sentence. `invalid_request` when the body is not a JSON object; `unknown_field` (with `fields`) for a key this door does not read — a near miss is renamed instead and reported in `autofixes`."
          },
          "402": {
            "description": "Not enough credits for the whole batch"
          },
          "503": {
            "description": "`service_unavailable`: the template could not be read, or `billing_unavailable`: the balance could not be checked (our side); retry. Nothing was created or charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "API key scope does not allow rendering"
          },
          "202": {
            "description": "Queued. The rows render in the background; poll status_url.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchTaskAccepted"
                }
              }
            }
          }
        },
        "operationId": "createBatchTask",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ]
      }
    },
    "/batch-tasks/preview": {
      "post": {
        "summary": "Parse a table and propose a column mapping",
        "description": "Dry run before /batch-tasks: shows how the columns map to template variables. Creates nothing and costs nothing. variables are the columns the table is expected to carry — what a caller supplies; for a template that computes some of its values, inputs (InputDescriptor) names what it computes from them. A computed value is never an expected column and is never reported unmatched, but a column named after one maps onto it as an explicit override. deliver_to is refused before any charge: deliver_to is available on async renders and batches only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "preset_id",
                  "table"
                ],
                "properties": {
                  "preset_id": {
                    "type": "string"
                  },
                  "table": {
                    "type": "string"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "png",
                      "jpeg",
                      "webp",
                      "pdf",
                      "html"
                    ],
                    "description": "Output format override, the same field /batch-tasks takes. Pass the one you will create the batch with, or max_cost_credits quotes a different price than the batch charges (a pdf page is priced per page, an image by canvas area)."
                  },
                  "quality": {
                    "type": "integer",
                    "description": "As on /batch-tasks: resolved with format and max_width exactly as the batch resolves them, so a value the batch refuses is refused here too (batch_output_invalid)."
                  },
                  "max_width": {
                    "type": "integer",
                    "description": "As on /batch-tasks; see quality."
                  },
                  "mapping": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "When sent, checked and every row judged under it exactly as /batch-tasks judges them, so a body the batch would refuse is refused here with the batch's answer (batch_mapping_mismatch, batch_row_invalid). Without it the preview proposes one and judges no rows. The reply proposes its own either way (suggested_mapping)."
                  },
                  "rows": {
                    "type": "object",
                    "description": "Fed to that row judgement as /batch-tasks feeds it; the quote itself is priced by the template's page, as the batch's balance check is."
                  },
                  "watermark": {
                    "$ref": "#/components/schemas/RenderWatermark"
                  },
                  "pdf_password": {
                    "$ref": "#/components/schemas/PDFPassword"
                  },
                  "deliver_to": {
                    "$ref": "#/components/schemas/DeliverTo"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "503": {
            "description": "`service_unavailable`: the template could not be read (our side); retry. Never `preset_not_found` for an outage.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "400": {
            "description": "The refusals /batch-tasks gives before its price, with the same body: the table (batch_table_*), an output option (batch_output_invalid), a sent mapping (batch_mapping_mismatch) or a row under it (batch_row_invalid). A quote is never given for a batch /batch-tasks would refuse.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "422": {
            "description": "`batch_render_too_big`: the render needs more memory than a worker has — the same refusal /batch-tasks gives, before any quote.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "200": {
            "description": "Proposed mapping and the price of the run",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchTaskPreview"
                }
              }
            }
          }
        },
        "operationId": "previewBatchTask",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ]
      }
    },
    "/batch-tasks/{id}": {
      "get": {
        "summary": "Batch task progress",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Status, per-row results and counts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchTaskStatus"
                }
              }
            }
          }
        },
        "operationId": "getBatchTask",
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ]
      }
    },
    "/batch-tasks/{id}/archive": {
      "get": {
        "summary": "Download the finished batch as a ZIP archive",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "ZIP archive of the rendered images"
          }
        },
        "operationId": "downloadBatchArchive",
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ]
      }
    },
    "/capabilities": {
      "get": {
        "summary": "Service capabilities",
        "description": "Layer types, available fonts, canvas limits, max layers. The whole reference by default; ?sections= narrows it to the named sections, the same names get_capabilities takes.",
        "security": [],
        "parameters": [
          {
            "name": "sections",
            "in": "query",
            "required": false,
            "description": "Section names, repeated or comma-separated. Omit for the whole reference. An unknown name is reported in sections_note with the list of valid ones.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          }
        },
        "operationId": "getCapabilities"
      }
    },
    "/components": {
      "get": {
        "summary": "Component library",
        "description": "Ready-made blocks that can be dropped into any preset with POST /presets/{id}/components.",
        "responses": {
          "200": {
            "description": "Components"
          },
          "401": {
            "description": "Missing/invalid API key"
          }
        },
        "operationId": "getComponents",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/design-guide": {
      "get": {
        "summary": "Design playbook (public)",
        "description": "Composition rails, palettes, type scale and proven recipes, as markdown. Public, like /capabilities: read it before designing from scratch. Whole by default; ?section= returns one section, including the ones that are not part of the always-served text (finishes).",
        "security": [],
        "parameters": [
          {
            "name": "section",
            "in": "query",
            "required": false,
            "description": "One section by name, e.g. process, recipes, depth, finishes, documents, donts — or a recipe id. Synonyms and partial names resolve; an unknown name answers 400 with the full list of names.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Unknown section: the body lists every name the door answers to",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GuideSectionRefusal"
                }
              }
            }
          }
        },
        "operationId": "getDesignGuide"
      }
    },
    "/documents": {
      "get": {
        "summary": "List document templates",
        "description": "Light rows (DocumentOverview): name, page COUNT and a sketch of the first page. The pages themselves come from GET /documents/{id}.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DocumentOverview"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          }
        },
        "operationId": "listDocuments",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      },
      "post": {
        "summary": "Save a document (ordered pages; a preset_id page is copied in)",
        "description": "Up to 20 pages, each {preset_id} or its own {canvas, layers, modifications, …}. The reply is the STORED document: a page sent as preset_id comes back as the copied canvas and layers, so the reply carries no preset_id. Alternatively pass {template_id, name?} for a kind:document starter from GET /templates. Its complete pages, shared master and samples are copied into an owned document; no catalogue dependency is saved.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentCreateInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentTemplate"
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "403": {
            "description": "A read-only API key, or `document_limit_exceeded`: the account holds the most documents it may keep. The body carries used, limit, freeable (the oldest documents, {id, name}) and free_with (delete_document; DELETE /documents/{id} over REST). The cap is fixed, not a plan's.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "operationId": "createDocument",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/documents/{id}": {
      "get": {
        "summary": "Get one document template",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentTemplate"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "getDocument"
      },
      "put": {
        "summary": "Update a document template",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentTemplate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentTemplate"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "updateDocument"
      },
      "delete": {
        "summary": "Delete a document template",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "deleteDocument"
      }
    },
    "/files/{path}": {
      "get": {
        "summary": "Fetch a rendered file, a preview or a stored asset",
        "description": "Every result, preview and asset URL passes through this API proxy. Historical render/template-preview links are public. New paid document attempt keys require the authenticated owning account, match its current completed attempt and are private/no-store; obsolete shared or attempt keys are refused. User assets require their owner or the renderer internal token. ?dl=<name> sets the download file name.",
        "security": [
          {},
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          },
          {
            "embed": []
          }
        ],
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The storage key, e.g. 8c84e597-…png or user_assets/{user}/{file}.png"
          },
          {
            "name": "dl",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Download file name for the Content-Disposition header"
          },
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "The file (image/*, application/pdf or text/html)",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Not a valid file key"
          },
          "401": {
            "description": "A user asset asked for without the owner's key or session (`authentication required for user assets`)"
          },
          "403": {
            "description": "A user asset of another account (`access denied`)"
          },
          "404": {
            "description": "No such file"
          }
        },
        "operationId": "getFile"
      }
    },
    "/generations": {
      "get": {
        "summary": "This account's renders, newest first",
        "description": "Every render job of the account as a feed: the file's url (a path under /files, see GET /files/{path}), its status, the template that made it, dimensions, format, the page count of a document and the channel it came from. Cursor paging: pass the previous reply's next_cursor as `before`; an empty next_cursor is the end of the feed. A malformed cursor is not refused — the feed starts over.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 40
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "The next_cursor of the previous page"
          },
          {
            "name": "channel",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ui",
                "api",
                "agent"
              ]
            },
            "description": "ui: the editor; api: REST and batch doors; agent: MCP. Omit for all"
          },
          {
            "name": "failed",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "failed=1 shows only jobs that ended in error"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "One page of the feed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerationsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid credentials"
          }
        },
        "operationId": "listGenerations"
      }
    },
    "/images/extract-object": {
      "post": {
        "summary": "Cut one object out of a photo",
        "description": "Targets a single object by text prompt or by a point on it. Costs 1 credit, like /images/remove-background, refunded when the cutout fails. Hidden from the MCP tools/list on a build where the service is not configured; this door then answers that the feature is off.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "storage_key": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string",
                    "description": "Short English concept: \"coffee cup\", \"the dog\""
                  },
                  "point": {
                    "type": "object",
                    "properties": {
                      "x": {
                        "type": "integer"
                      },
                      "y": {
                        "type": "integer"
                      }
                    }
                  },
                  "filename": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cutout saved to assets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cutout"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "402": {
            "description": "Not enough credits: the body carries error, balance, required and packages_url."
          },
          "429": {
            "description": "Too many renders at once — concurrency limit, not a monthly quota. Retry in a moment.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          },
          "400": {
            "description": "`invalid_input`, `url_rejected`, `download_failed`, `file_too_large`; 422 `unprocessable` when nothing matched the prompt or point (the credit is refunded)."
          }
        },
        "operationId": "extractObject",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/images/palette": {
      "post": {
        "summary": "Dominant colours of a photo",
        "description": "Six dominant colours plus a role suggestion (background / support / accent) — use it to theme a layout around an image.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "storage_key": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Palette",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhotoPalette"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "400": {
            "description": "`unknown_field`, `invalid_input`, `url_rejected` (the url is not a public http(s) address that resolves), `download_failed` (with `upstream_status` when the address answered), `file_too_large`. A storage_key outside this account is 404 `not_found`."
          }
        },
        "operationId": "getImagePalette",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/images/remove-background": {
      "post": {
        "summary": "Cut the background out of a photo",
        "description": "Returns a transparent PNG saved to your assets (an asset slot; when every slot is taken the oldest previous cutout is evicted to make room). Costs 1 credit, refunded when the cutout fails.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Public https image URL"
                  },
                  "storage_key": {
                    "type": "string",
                    "description": "storage_key of your own uploaded image (from GET /assets)"
                  },
                  "filename": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cutout saved to assets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cutout"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "402": {
            "description": "Not enough credits: the body carries error, balance, required and packages_url."
          },
          "429": {
            "description": "Too many renders at once — concurrency limit, not a monthly quota. Retry in a moment.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          },
          "400": {
            "description": "`unknown_field`, `invalid_input`, `url_rejected` (the url is not a public http(s) address that resolves), `download_failed` (with `upstream_status` when the address answered), `file_too_large`. A storage_key outside this account is 404 `not_found`."
          }
        },
        "operationId": "removeBackground",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/images/search": {
      "get": {
        "summary": "Search licensed stock photos",
        "description": "Returns image_url, dimensions and author per photo, all distinct. Costs no credits, but IS rationed: a daily ration per account, shared by every agent and session on it, because the provider pool is shared by every user of this server — the reply carries searches_left and the MCP tool description states the number. Repeating a query you already ran today NORMALLY spends no ration, whatever detail and start you pass: the day's list is kept in memory per process, so a repeat after a deploy or on another replica does spend one, and looking closer at a photo of a kept list is free. Hotlink the returned URL directly in a layer.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "English, 2-4 broad nouns. Words are AND-matched: 5+ usually returns nothing"
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10
            }
          },
          {
            "name": "orientation",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "landscape",
                "portrait",
                "squarish"
              ]
            }
          },
          {
            "name": "detail",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "thumb",
                "large"
              ]
            },
            "description": "Inline preview size. thumb (default) is a ~200px thumbnail; large returns fewer photos at a size where a logo on a shirt is readable — use it before a photo becomes the sample of a brand template"
          },
          {
            "name": "start",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10
            },
            "description": "Photo number the page starts at (default 1), in the same numbering the thumbnails carry: start=7 with detail=large shows photo 7 big. A number past the end of the list is refused and the refusal says how many photos there are"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Photos"
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "400": {
            "description": "Missing query"
          }
        },
        "operationId": "searchImages"
      }
    },
    "/mcp": {
      "post": {
        "summary": "Remote MCP endpoint (streamable HTTP)",
        "description": "Model Context Protocol over stateless HTTP: POST JSON-RPC 2.0 messages (initialize, tools/list, tools/call). Tools (full list via tools/list): gallery (list_templates, preview_template, create_preset_from_template), design CRUD from raw JSON DSL with strict field validation (get_preset, create_preset, update_preset with layer_patches, delete_preset), preview_preset (paid previews for iteration), get_capabilities, render_image (returns the image inline), list_presets, get_render_status, get_usage. Zero-to-image flow for agents: list_templates → create_preset_from_template → render_image. Agent guide: https://rendry.io/llms-full.txt",
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          },
          "401": {
            "description": "Missing/invalid API key"
          }
        },
        "operationId": "callMcp",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/presets": {
      "get": {
        "summary": "List your templates",
        "description": "One row per template, newest first. Read the ids carefully: a row's `id` is the LATEST VERSION and changes on every save; `preset_group_id` is the template — the value POST /presets returns as preset_id and the one every render, patch, share and delete-group door takes.",
        "responses": {
          "200": {
            "description": "Templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PresetOverview"
                  }
                }
              }
            }
          }
        },
        "operationId": "listPresets",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      },
      "post": {
        "summary": "Create a template from JSON DSL",
        "description": "Full DSL reference: https://rendry.io/docs. Canvas up to 6144x6144, up to 40 layers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PresetInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. preset_id is the template's GROUP id (what the render doors take); version_id is the version row.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PresetWriteResult"
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          }
        },
        "operationId": "createPreset",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/presets/{id}": {
      "get": {
        "summary": "Get full template (canvas + layers)",
        "description": "Layers reveal {variable} placeholders and dynamic image keys — everything render_image accepts in dynamic_data.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "The stored template. With a group id the latest version comes back; ?exact=true returns exactly the version whose id was passed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Preset"
                }
              }
            }
          },
          "404": {
            "description": "`preset_not_found` — absent, deleted or another account's, alike."
          }
        },
        "operationId": "getPreset"
      },
      "patch": {
        "summary": "Patch a preset by layer id",
        "description": "Partial edit: layer_patches are merged by layer id, everything else is left alone. Saves a new version and does NOT consume a template slot. Unknown fields are rejected with did-you-mean hints. preview: true returns the rendered image in the same response.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "canvas": {
                    "$ref": "#/components/schemas/Canvas"
                  },
                  "layers": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "Full replacement of the layer tree"
                  },
                  "layer_patches": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "Partial patches merged by layer id"
                  },
                  "preview": {
                    "type": "boolean",
                    "description": "Also return the rendered preview inline, charged the preview price (0.1 credit) like POST /render/preview; the file is capped at 640 px on the long side. Saving the new version itself costs nothing."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New version saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PresetPatchResult"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "404": {
            "description": "`preset_not_found` — absent, deleted or another account's, alike."
          }
        },
        "operationId": "updatePreset"
      },
      "delete": {
        "summary": "Delete one preset version",
        "description": "Removes ONE version. Note for integrations: list_presets-style ids point at the latest version, so deleting by that id rolls the template back to its previous version instead of removing it. To remove the template with its whole history AND free a template slot, use DELETE /presets/{id}/group.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "404": {
            "description": "`preset_not_found` — absent, deleted or another account's, alike."
          }
        },
        "operationId": "deletePreset"
      }
    },
    "/presets/{id}/components": {
      "post": {
        "summary": "Insert a ready-made block into a preset",
        "description": "Drops a CTA button, price burst, sale ribbon, rating row and the like into the design as one group layer. See GET /components.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "component_id": {
                    "type": "string"
                  },
                  "x": {
                    "type": "integer"
                  },
                  "y": {
                    "type": "integer"
                  },
                  "scale": {
                    "type": "number"
                  },
                  "overrides": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Values for the block's {variables}"
                  }
                },
                "required": [
                  "component_id",
                  "x",
                  "y"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Component inserted, new version saved"
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "400": {
            "description": "`unknown_field` (a key the tool does not read; a near miss is renamed and reported in `autofixed_fields`) or `invalid_input`. 404 is `component_not_found` or `preset_not_found`; 409 `conflict` when a component variable collides with a template/formula definition."
          }
        },
        "operationId": "addPresetComponents"
      }
    },
    "/presets/{id}/current": {
      "put": {
        "summary": "Save over the latest version of a template",
        "description": "Edits the newest version in place instead of creating another one. Does not consume a template slot. The body MUST name `id`, the version the client believes is the latest (the `id` of the GET /presets row or of GET /presets/{id}); without it the door answers 400, and when that version is no longer the latest it answers 409 preset_changed_elsewhere and writes nothing — somebody saved from another tab, an agent or the API in between, and silently writing over their work is the one thing this door refuses to do.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PresetInput"
                  },
                  {
                    "type": "object",
                    "required": [
                      "id"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The version being written over — the latest version's id as the client read it"
                      },
                      "preset_group_id": {
                        "type": "string",
                        "description": "The template; when present it must match the path id"
                      }
                    }
                  }
                ],
                "description": "Full preset DSL, as in POST /presets, plus the version id"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved over the latest version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PresetWriteResult"
                }
              }
            }
          },
          "400": {
            "description": "`id` missing (\"id of the version being updated is required\"), an unknown field or invalid DSL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The version named by `id` is no longer the latest: nothing was written",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionConflict"
                }
              }
            }
          }
        },
        "operationId": "setCurrentPreset"
      }
    },
    "/presets/{id}/group": {
      "delete": {
        "summary": "Delete a preset (all versions) and free a template slot",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          },
          "401": {
            "description": "Missing/invalid credentials"
          },
          "404": {
            "description": "`error` `preset_not_found`: no such preset in this account (never existed, already deleted, or another account's); nothing was deleted"
          }
        },
        "operationId": "deletePresetGroup"
      }
    },
    "/presets/{id}/share": {
      "post": {
        "summary": "Publish a template as a public link",
        "description": "Returns a stable URL that renders the template for anyone, no key required. The most expensive decision available: a published link cannot be recalled from the internet, only disabled for future requests. Spending is bounded: repeat hits are served from cache and cost nothing, while NEW combinations of query values are capped at 200 renders a day per link for a small canvas (fewer for costlier canvases — the cap is set in credits, not pictures). The exact number for this link comes back as daily_render_budget. Past it the public URL answers 429 with error url_link_budget_exhausted, charges nothing, and keeps serving every variant already in cache. For a template that computes some of its values the reply also carries variables (the query parameters a visitor's page passes) and inputs (InputDescriptor: what the template computes from them); a query parameter named after a computed value overrides it.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "requestBody": {
          "required": false,
          "description": "Optional. No body, null or {} opens the link; opening a link that is already live returns the SAME url (rotated:false) — it is never replaced as a side effect.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "true or absent opens the link; false closes it — the public URL stops working immediately and the reply is {\"enabled\": false}"
                  },
                  "rotate": {
                    "type": "boolean",
                    "description": "true issues a NEW url and kills the previous one (rotated:true in the reply); every place the old link was pasted stops working"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The link's state: {enabled:true, url, rotated, daily_render_budget, …} when open, {enabled:false} when closed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareLink"
                }
              }
            }
          },
          "403": {
            "description": "API key scope does not allow publishing"
          },
          "404": {
            "description": "`preset_not_found`. A key this door does not read is refused 400 `unknown_field` (a near miss is renamed and reported in `autofixes`)."
          }
        },
        "operationId": "publishPreset",
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ]
      },
      "get": {
        "summary": "Show the existing public link without issuing a new one",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Current public URL, if any — {enabled: false} when there is none",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareLink"
                }
              }
            }
          }
        },
        "operationId": "getPresetShare",
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ]
      }
    },
    "/presets/{id}/theme": {
      "post": {
        "summary": "Recolour a preset and swap its font pair",
        "description": "Applies a palette (or the palette of a photo) to the whole design in one call.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "palette": {
                    "type": "object",
                    "description": "Explicit palette (background/support/accent/text)"
                  },
                  "from_url": {
                    "type": "string",
                    "description": "Take the palette from this photo instead"
                  },
                  "storage_key": {
                    "type": "string",
                    "description": "Or the user's own image: its storage_key from GET /assets (a link to a file in the account is closed to the server's fetcher)"
                  },
                  "font_pair": {
                    "type": "string",
                    "description": "Heading/body font pair name"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Theme applied, new version saved"
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "400": {
            "description": "`unknown_field` (a key the tool does not read; a near miss is renamed and reported in `autofixed_fields`), `invalid_input` (palette or font pair), `url_rejected` / `download_failed` for from_url. 404 `preset_not_found`."
          }
        },
        "operationId": "setPresetTheme"
      }
    },
    "/presets/{id}/versions": {
      "get": {
        "summary": "Version history of a preset",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Versions, newest first"
          },
          "401": {
            "description": "Missing/invalid API key"
          }
        },
        "operationId": "listPresetVersions"
      }
    },
    "/render/async": {
      "post": {
        "summary": "Render an image asynchronously",
        "description": "Enqueues the render and returns 202 immediately. Poll /render/status/{job_id} or pass webhook_url. Optional deliver_to uploads the stored final output by presigned HTTPS PUT; presign with the output Content-Type. A batch uploads one ZIP after all rows are terminal, byte-identical to its archive download and omitting failed rows; all-failed batches upload nothing (reason render). Delivery never changes the render charge. Retryable transport errors, 5xx and 429 use a bounded attempt count inside one persisted result-transfer deadline; pending requests expire within result retention. Poll delivery status; failed receipts use a fixed reason catalogue and the notice: The file remains available at Rendry; a delivery failure does not refund the render. See capabilities.limits.deliver_to for current budgets.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenderRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AsyncRenderResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request cannot be queued; nothing was charged: `invalid_request` (the body is not a JSON object), `unknown_field` (a key this door does not read; `fields` names each with a did-you-mean — a near miss is renamed instead and reported in `autofixes`), `variables_unresolved` (with `diagnostics`), `invalid_webhook_url` (a webhook_url the worker would refuse to call, with `reason` beside it), or `invalid_input`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "402": {
            "description": "Not enough credits: the body carries error, balance, required and packages_url."
          },
          "404": {
            "description": "`preset_not_found` — absent, deleted or another account's, alike.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Too many renders at once — concurrency limit, not a monthly quota. Retry in a moment.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          }
        },
        "operationId": "renderAsync",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/render/batch": {
      "post": {
        "summary": "Render up to 10 images in one call",
        "description": "One template x many data sets. Each item is charged as one render (1-3 credits by canvas area; pdf/html 2 a page) and the run stops at the first item the balance cannot pay for. For hundreds of rows use POST /batch-tasks (a table, one archive); for thousands loop this endpoint or queue /render/async with a webhook. Optional deliver_to uploads the stored final output by presigned HTTPS PUT; presign with the output Content-Type. A batch uploads one ZIP after all rows are terminal, byte-identical to its archive download and omitting failed rows; all-failed batches upload nothing (reason render). Delivery never changes the render charge. Retryable transport errors, 5xx and 429 use a bounded attempt count inside one persisted result-transfer deadline; pending requests expire within result retention. Poll delivery status; failed receipts use a fixed reason catalogue and the notice: The file remains available at Rendry; a delivery failure does not refund the render. See capabilities.limits.deliver_to for current budgets.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "preset_id": {
                    "type": "string"
                  },
                  "items": {
                    "type": "array",
                    "maxItems": 10,
                    "items": {
                      "type": "object",
                      "properties": {
                        "dynamic_data": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "filename": {
                          "type": "string"
                        },
                        "rows": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "string"
                              }
                            }
                          },
                          "description": "This item's rows for its repeat groups and tables (rows_key)"
                        }
                      }
                    }
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "png",
                      "jpeg",
                      "webp",
                      "pdf",
                      "html"
                    ],
                    "description": "For the whole batch. pdf and html render the document profile at 2 credits a page"
                  },
                  "quality": {
                    "type": "integer"
                  },
                  "max_width": {
                    "type": "integer"
                  },
                  "watermark": {
                    "$ref": "#/components/schemas/RenderWatermark"
                  },
                  "pdf_password": {
                    "$ref": "#/components/schemas/PDFPassword"
                  },
                  "deliver_to": {
                    "$ref": "#/components/schemas/DeliverTo"
                  }
                },
                "required": [
                  "preset_id",
                  "items"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch finished, per-item status inside. An item that was refused carries the same refusal object a single render answers (`error`, `message`, `diagnostics`, …) beside its `index` and `status` (error, insufficient_credits, quota_exceeded). When the credits run out the batch stops, and every item it did not attempt is listed with `status` not_attempted and a `reason`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchRenderResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "402": {
            "description": "Not enough credits: the body carries error, balance, required and packages_url."
          },
          "404": {
            "description": "`preset_not_found`: the whole call is refused before any item is rendered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Too many renders at once — concurrency limit, not a monthly quota. Retry in a moment.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          },
          "400": {
            "description": "Refusal before anything is charged: `unknown_field` (a key the tool does not read, items included; a near miss is renamed instead and reported in `autofixed_fields`), `invalid_request`, or `invalid_input`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "operationId": "renderBatch",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/render/document": {
      "post": {
        "summary": "Render pages as ONE multi-page file: PDF or self-contained HTML",
        "description": "ASYNC. Pages = ordered presets (inline pages[] or a saved document_id). 2 credits include the first 20 final pages; add 1 credit for each additional begun 20-page block, plus the compute surcharge above the standard-page floor of a page drawn by a whole-page raster render (backdrop_blur, or in html blend_mode). The quote uses the final prepared page count. Charged once up front; failed jobs refund automatically. Up to 20 authored pages and 200 final pages, including table continuations. Account pending document limits refuse with 429 document_queue_full before charge. The caller decides how content splits into pages. Text stays searchable vector; layers outside the document profile (shadows, blurs, blend modes) are rasterized and reported in the job warnings. Optional deliver_to uploads the stored final output by presigned HTTPS PUT; presign with the output Content-Type. A batch uploads one ZIP after all rows are terminal, byte-identical to its archive download and omitting failed rows; all-failed batches upload nothing (reason render). Delivery never changes the render charge. Retryable transport errors, 5xx and 429 use a bounded attempt count inside one persisted result-transfer deadline; pending requests expire within result retention. Poll delivery status; failed receipts use a fixed reason catalogue and the notice: The file remains available at Rendry; a delivery failure does not refund the render. See capabilities.limits.deliver_to for current budgets.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AsyncRenderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error; nothing was charged. `variables_unresolved` names the `page` and carries `diagnostics`; a webhook_url the worker would refuse to call answers `error` `invalid_webhook_url` with `reason` beside it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "402": {
            "description": "Insufficient credits"
          },
          "403": {
            "description": "`error` is `api_key_scope_insufficient` (a read-only key) or `api_key_preset_not_allowed` (a preset outside the key's allow-list; `preset_id` and `tool` ride beside it)"
          },
          "404": {
            "description": "`document_not_found`, or `preset_not_found` for a page's preset (with `page` and `preset_id`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "422": {
            "description": "Page over canvas limits or unsupported format"
          },
          "200": {
            "description": "dry_run: true — the quote. status is dry_run; cost, page_count, warnings and losses say what the render would charge and what would be rasterized. No job, no file, nothing charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AsyncRenderResponse"
                }
              }
            }
          }
        },
        "operationId": "renderDocument",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/render/preview": {
      "post": {
        "summary": "Render a preview (0.1 credit per call)",
        "description": "Renders through the same preview_preset implementation as MCP and returns a capped JPEG preview as image_base64 plus mime_type and layout warnings. Preview pricing and file limits match MCP. Pass preset_id for a saved template, or canvas+layers for an unsaved inline design. Inline keep_draft defaults to true and retains a reusable draft without consuming a template slot; false never caches a draft and omits draft_id. Explicit keep_draft in saved mode, null and non-boolean values are rejected before charging. The preview request does not overwrite the authored final output format. Dynamic data overrides sample modifications; rows override sample_rows. deliver_to is refused before any charge: deliver_to is available on async renders and batches only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "preset_id": {
                    "type": "string",
                    "description": "Saved preset. Mutually exclusive with canvas+layers"
                  },
                  "canvas": {
                    "$ref": "#/components/schemas/Canvas",
                    "description": "Inline draft canvas (same schema as POST /presets)"
                  },
                  "layers": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "Inline draft layers"
                  },
                  "dynamic_data": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "modifications": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Sample values for an inline draft"
                  },
                  "size": {
                    "type": "string",
                    "enum": [
                      "thumb",
                      "normal",
                      "large"
                    ],
                    "description": "Inline image size (default normal). Any other value is refused with 400 `invalid_preview_size` before anything is rendered or charged."
                  },
                  "region": {
                    "type": "object",
                    "properties": {
                      "x": {
                        "type": "integer"
                      },
                      "y": {
                        "type": "integer"
                      },
                      "width": {
                        "type": "integer"
                      },
                      "height": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "x",
                      "y",
                      "width",
                      "height"
                    ],
                    "description": "Read one box of the page instead of the whole sheet, in CANVAS pixels (the coordinates your layers already use). THIS is the endpoint for it: the page is composed at its own resolution, the box is cut out of it and only then capped at 640 px on its long side, so a box no larger than that comes back 1:1 and small type on a 2480 px print sheet is finally legible. The reply carries region and scale (multiply canvas pixels by scale to land on the pixels you are looking at). Same price as any preview. Cannot be combined with debug_overlay, max_width or canvas.finish_profile; a box outside the canvas, or with zero area, is refused with the canvas size in the message."
                  },
                  "debug_overlay": {
                    "type": "boolean",
                    "description": "Layer frames retain DSL coordinate labels and map through geometry to the displayed PNG; the thirds grid is in display coordinates."
                  },
                  "keep_draft": {
                    "type": "boolean",
                    "default": true,
                    "description": "Inline mode only. Omission/true retains the reusable draft; false skips caching and omits draft_id. Forbidden with preset_id, including false. Null is invalid."
                  },
                  "derived": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "Inline derived colors, as in the preset DSL."
                  },
                  "sample_rows": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      }
                    },
                    "description": "Inline sample rows for repeat groups."
                  },
                  "rows": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      }
                    },
                    "description": "Runtime repeat rows; overrides sample_rows."
                  },
                  "palettes": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "description": "Inline colours from data, as in the preset DSL."
                  },
                  "watermark": {
                    "$ref": "#/components/schemas/RenderWatermark"
                  },
                  "deliver_to": {
                    "$ref": "#/components/schemas/DeliverTo"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preview rendered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "width": {
                      "type": "integer"
                    },
                    "height": {
                      "type": "integer"
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "image_base64": {
                      "type": "string"
                    },
                    "mime_type": {
                      "type": "string"
                    },
                    "geometry": {
                      "$ref": "#/components/schemas/RenderGeometry"
                    },
                    "draft_id": {
                      "type": "string",
                      "description": "Reusable inline draft handle; omitted when keep_draft is false or in saved mode."
                    },
                    "draft_expires_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "UTC expiry assigned when the reusable draft is cached; present exactly when draft_id is present. This deadline is separate from the preview image retention."
                    },
                    "cost": {
                      "$ref": "#/components/schemas/CreditCost"
                    },
                    "text_fit": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TextFit"
                      },
                      "description": "What the preview MEASURED for every text layer, when the render reports measurements"
                    },
                    "chart_fit": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      },
                      "description": "Measured geometry of every chart layer; sent only when the design has one"
                    },
                    "region": {
                      "type": "object",
                      "properties": {
                        "x": {
                          "type": "integer"
                        },
                        "y": {
                          "type": "integer"
                        },
                        "width": {
                          "type": "integer"
                        },
                        "height": {
                          "type": "integer"
                        }
                      },
                      "description": "With region — the box that was cut out, in canvas pixels"
                    },
                    "scale": {
                      "type": "number",
                      "description": "With region — canvas pixels × scale = pixels of the returned picture"
                    },
                    "note": {
                      "type": "string",
                      "description": "The price of this call and what to call for the final"
                    },
                    "look_at_it": {
                      "type": "string",
                      "description": "What to check on the picture before iterating"
                    },
                    "save_hint": {
                      "type": "string",
                      "description": "Inline mode — how to turn the draft into a template without resending it"
                    },
                    "warnings_note": {
                      "type": "string",
                      "description": "What the warnings list covers"
                    },
                    "autofixed_fields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Fields renamed on the way in"
                    },
                    "autofix_note": {
                      "type": "string"
                    },
                    "debug_overlay": {
                      "type": "string",
                      "description": "With debug_overlay: true — what the frames and grid on the picture mean"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Persisted result/draft access deadline when the preview owns an expiring artifact."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "402": {
            "description": "Not enough credits: the body carries error, balance, required and packages_url."
          },
          "400": {
            "description": "Invalid design or arguments; nothing was charged: DSL problems (`invalid_input`), `unknown_field`, `variables_unresolved` (with `diagnostics`), a `size` outside thumb, normal, large (`invalid_preview_size`). 404 `preset_not_found` for a preset the caller cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "More than 10 requests a second from this account; Retry-After says when",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          }
        },
        "operationId": "renderPreview",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/render/status/{id}": {
      "get": {
        "summary": "Get render job status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RenderJobStatus"
                }
              }
            }
          },
          "404": {
            "description": "Job not found — the same answer for an id that does not exist and for another account's job"
          }
        },
        "operationId": "getRenderStatus"
      }
    },
    "/render/sync": {
      "post": {
        "summary": "Render an image synchronously",
        "description": "Renders the template with dynamic_data substituted. Waits up to 25s (typical: 1-3s). Returns result_url of the finished PNG. Body flag \"preview\": true renders at preview price (0.1 credit) and caps the file at 640 px on the long side. deliver_to is refused before any charge: deliver_to is available on async renders and batches only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rendered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyncRenderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Refusal before anything is charged: `invalid_request` (the body is not a JSON object), `unknown_field` (a key this door does not read; `fields` names each with a did-you-mean — a near miss is renamed instead and reported in `autofixes`), `variables_unresolved` (with `diagnostics`), or `invalid_input` (`message` names the field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "402": {
            "description": "Not enough credits: the body carries error, balance, required and packages_url."
          },
          "404": {
            "description": "`preset_not_found` (or `draft_not_found` for a draft_id) — absent, deleted or another account's, alike.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "408": {
            "description": "Render timeout"
          },
          "409": {
            "description": "`conflict`: the draft has already been rendered, or is rendering now — a draft renders once."
          },
          "422": {
            "description": "Render failed (`message` explains why)"
          },
          "429": {
            "description": "Too many renders at once — concurrency limit, not a monthly quota. Retry in a moment.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          }
        },
        "operationId": "renderSync",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/templates": {
      "get": {
        "summary": "Public template gallery",
        "description": "133 ready-made designs (images and paginated PDF documents) with input variables, sample data and a composition (layer count per type). kind=document entries carry authored_pages and copy through POST /documents {template_id}; image entries copy through POST /templates/{id}/clone. No authentication required.",
        "security": [],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by category: sport, shop, after-purchase, events, data, documents, media, social, greetings, cards, awards"
          }
        ],
        "responses": {
          "200": {
            "description": "Templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TemplateIndex"
                  }
                }
              }
            }
          }
        },
        "operationId": "listTemplates"
      }
    },
    "/templates/{id}": {
      "get": {
        "summary": "Full template JSON (canvas + layers)",
        "description": "Full image template or complete document starter. Image content can be saved with POST /presets; kind:document starter pages/master/samples use POST /documents or save_document {template_id}. Document IDs cannot be cloned through image actions.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template DSL"
          },
          "404": {
            "description": "Template not found"
          }
        },
        "operationId": "getTemplate"
      }
    },
    "/templates/{id}/clone": {
      "post": {
        "summary": "Clone a gallery template into the account",
        "description": "Copies a gallery template into your presets together with its sample data and returns a renderable preset_id. Consumes a template slot.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Name for the new preset"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preset created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClonedPreset"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "400": {
            "description": "`unknown_field` (a key the tool does not read; a near miss is renamed and reported in `autofixed_fields`) or `invalid_input`."
          },
          "403": {
            "description": "`preset_limit_exceeded`: template slots exhausted — delete a preset or upgrade. The same refusal, with the same fields (used, limit, freeable, upgrade_url), as POST /presets."
          },
          "404": {
            "description": "`template_not_found`."
          }
        },
        "operationId": "cloneTemplate"
      }
    },
    "/user/limits": {
      "get": {
        "summary": "Plan and quota usage",
        "description": "Current plan, credit balance, template and asset slots used vs limits. Works with an API key — agents check the balance here, because credits are what a render fails on.",
        "responses": {
          "200": {
            "description": "Usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserLimits"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid credentials"
          }
        },
        "operationId": "getUserLimits",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ]
      }
    },
    "/user/usage": {
      "get": {
        "summary": "Plan, quota used and reset date",
        "responses": {
          "200": {
            "description": "Usage"
          },
          "401": {
            "description": "Missing/invalid API key"
          }
        },
        "operationId": "getUserUsage",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ]
      }
    },
    "/u/{token}": {
      "servers": [
        {
          "url": "https://rendry.io",
          "description": "The public link lives at the root of the site, not under /api/v1: it is written by hand into <meta property=\"og:image\">"
        }
      ],
      "get": {
        "summary": "Render a published template by its public link (no key)",
        "description": "The URL POST /presets/{id}/share issued. Anyone may fetch it; template variables travel as query parameters (the share reply's `example` shows the template's own) and every new combination is rendered once, then served from cache. Spending is bounded by the link's daily_render_budget of NEW pictures a day; past it the door answers 429 url_link_budget_exhausted, charges nothing and keeps serving cached variants. Rate-limited by IP.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The token part of the issued url, with its .png suffix"
          }
        ],
        "responses": {
          "200": {
            "description": "The rendered picture",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "A variable value the template refuses (the error names it)"
          },
          "404": {
            "description": "No template behind this token, or its link was disabled"
          },
          "429": {
            "description": "The link's daily budget of new pictures is spent (`url_link_budget_exhausted`), or too many requests from this address; cached variants keep working",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          },
          "503": {
            "description": "The render or the budget check is unavailable right now"
          }
        },
        "operationId": "getPublicRender"
      }
    },
    "/user/api-keys": {
      "get": {
        "summary": "List this account's API keys",
        "security": [
          {
            "session": []
          }
        ],
        "description": "For the signed-in owner, in a browser session. An API key cannot list, issue or revoke keys: it is refused with 401. A connector (MCP/OAuth) token is refused on every account-management door with 403 `browser_session_required`: a connector does MCP work, it does not manage keys. Each key is listed with its scope; the key itself is shown only as its first 12 characters. The resolved account may be selected with X-Rendry-Account; only an owner or admin browser session may administer its keys. The mode and actor are reported in each reply.",
        "responses": {
          "200": {
            "description": "Array of APIKey",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/APIKey"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not signed in, or an API key was used"
          },
          "403": {
            "description": "`error` is `browser_session_required`: a connector (MCP/OAuth) token was used"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "operationId": "listApiKeys"
      },
      "post": {
        "summary": "Issue an API key with a scope",
        "description": "For the signed-in owner, in a browser session (an API key is refused with 401). A connector (MCP/OAuth) token is refused on every account-management door with 403 `browser_session_required`: a connector does MCP work, it does not manage keys. The response carries the whole key once; it is not stored and cannot be shown again. `scope` decides what the key may do (see the APIKey schema). A request that names no scope gets a `full` key, as every key did before scopes could be chosen; an unknown scope is refused and nothing is issued. The resolved account may be selected with X-Rendry-Account; only an owner or admin browser session may administer its keys. The mode and actor are reported in each reply.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Seen only by the owner, to tell keys apart when revoking. Stored without leading and trailing whitespace; one of whitespace alone is refused.",
                    "maxLength": 255
                  },
                  "scope": {
                    "type": "string",
                    "enum": [
                      "read",
                      "render",
                      "full"
                    ],
                    "default": "full"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "live",
                      "test"
                    ],
                    "default": "live",
                    "description": "Immutable execution mode, persisted on the issued key. Test rendering is watermarked and does not debit credits."
                  },
                  "actor_id": {
                    "type": "string",
                    "description": "Current member who owns this credential; defaults to the issuing browser actor. Member removal invalidates their keys."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Issued. An APIKey whose key_value is the whole key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIKey"
                }
              }
            }
          },
          "400": {
            "description": "The body is not JSON, `error` is `api_key_name_required` (the name is empty or only whitespace), `error` is `api_key_name_too_long` (the name is longer than `limit` characters), or `error` is `invalid_api_key_scope`: the scope is not one of read, render, full (they ride in `allowed`); `unknown_field` for a key this door does not read (a near miss is renamed and reported in `autofixes`). Nothing was issued."
          },
          "401": {
            "description": "Not signed in, or an API key was used"
          },
          "403": {
            "description": "`error` is `browser_session_required`: a connector (MCP/OAuth) token was used"
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "operationId": "createApiKey"
      }
    },
    "/user/api-keys/{id}": {
      "delete": {
        "summary": "Revoke an API key",
        "security": [
          {
            "session": []
          }
        ],
        "description": "For the signed-in owner, in a browser session. Requests with the key stop working at once. A connector (MCP/OAuth) token is refused on every account-management door with 403 `browser_session_required`: a connector does MCP work, it does not manage keys.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked"
          },
          "401": {
            "description": "Not signed in, or an API key was used"
          },
          "403": {
            "description": "`error` is `browser_session_required`: a connector (MCP/OAuth) token was used"
          },
          "404": {
            "description": "`error` is `api_key_not_found`: this account has no key with that id — it never existed, was revoked already, or belongs to another account. Nothing was changed."
          }
        },
        "operationId": "deleteApiKey"
      }
    },
    "/user/account/deletion": {
      "get": {
        "summary": "What deleting this account would cost",
        "security": [
          {
            "session": []
          }
        ],
        "description": "For the signed-in owner, in a browser. Answers which confirmation this account uses (`confirm_with`: `password` when the owner has ever set one, otherwise `email`), the e-mail on the account, the credit balance that will be forfeited, and the retention window in days. NOT AVAILABLE TO AGENTS: an API key or an MCP/OAuth connector token is refused with `account_deletion_needs_session`, and there is no MCP tool for this.",
        "responses": {
          "200": {
            "description": "confirm_with, email, credits_forfeited, retention_days"
          },
          "401": {
            "description": "Not signed in; `error` is `unauthorized`"
          },
          "403": {
            "description": "`error` is `account_deletion_needs_session`: the request came with an API key or a connector token. Only the owner's browser session may do this."
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "operationId": "getAccountDeletion"
      },
      "post": {
        "summary": "Close this account and schedule its deletion",
        "security": [
          {
            "session": []
          }
        ],
        "description": "Closes the account at once: sign-in stops, every issued token stops, every API key is revoked, queued render jobs are failed and refunded, and the remaining credits are forfeited. The data itself is erased after the retention window (`retention_days`), and until then support can restore the account. Payment and credit-ledger records are kept as accounting records, anonymised. NOT AVAILABLE TO AGENTS — see the GET above.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "password": {
                    "type": "string",
                    "description": "The current password. Required when GET answered confirm_with=password."
                  },
                  "email": {
                    "type": "string",
                    "description": "The account's own e-mail, typed back. Required when GET answered confirm_with=email (an account created through SSO has no password of its own)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Closed. Returns closed_at, deletion_date, retention_days, credits_forfeited, keys_revoked."
          },
          "400": {
            "description": "The body is not JSON"
          },
          "401": {
            "description": "Not signed in; `error` is `unauthorized`"
          },
          "403": {
            "description": "`error` is a machine code: `account_deletion_needs_session` (an API key or a connector token was used) or `account_deletion_not_confirmed` (the password or e-mail did not match — nothing was changed)."
          },
          "429": {
            "description": "More than 5 attempts a minute from one address"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "operationId": "deleteAccount"
      }
    },
    "/render/completions": {
      "get": {
        "operationId": "listRenderCompletions",
        "summary": "Poll successful render completions",
        "description": "Read-only account-scoped completion events, deduplicated by stable job ID. Newest-first by default, continue older history with before=next_cursor. To consume new events in commit order, use after=0 then after=the last item cursor; continue each full page before advancing. Older jobs that finish later appear as new events. Exact charges come from recorded debits. Events survive for the same retention as job status records. This is a polling feed; consumers deduplicate IDs after retries.",
        "parameters": [
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]+$"
            },
            "description": "Exclusive forward cursor; mutually exclusive with before."
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]+$"
            },
            "description": "Exclusive history cursor; mutually exclusive with after."
          },
          {
            "name": "job_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Restrict to this completed job in the authenticated account."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 100
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RenderCompletion"
                      }
                    },
                    "next_cursor": {
                      "type": "string",
                      "description": "Last item cursor when the page is full; absent at the end."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or page limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "No template in this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/presets/{id}/inputs": {
      "get": {
        "operationId": "getPresetInputs",
        "summary": "Describe native integration mapping fields",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Stable template group ID."
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationInputs"
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or page limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "No template in this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/documents/{id}/inputs": {
      "get": {
        "operationId": "getDocumentInputs",
        "summary": "Describe native integration mapping fields",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Document template ID."
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationInputs"
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or page limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "No template in this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/render/subscriptions": {
      "get": {
        "operationId": "listCompletionSubscriptions",
        "summary": "List owned render-finished subscriptions",
        "description": "Read scope is sufficient. Responses omit secret target URLs and publish the enforced delivery bounds. Subscriptions belong to the account and issuing API key; revocation or account closure cascades subscriptions and prevents new deliveries. Existing receipts are removed transactionally; an identifier-only receipt racing retirement is removed by a bounded orphan sweep.",
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ],
        "responses": {
          "200": {
            "description": "Owned subscription metadata and current delivery policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompletionSubscriptionList"
                }
              }
            }
          },
          "401": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "503": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      },
      "post": {
        "operationId": "subscribeRenderFinished",
        "summary": "Subscribe a callback to future successful completions",
        "description": "Requires a render or full API key. Creation is serialized with account completions; only events after start_cursor enqueue deliveries. Repeating the same URL with the same issuing key returns the same subscription. Notifications contain id, delivery_id, job_id, cursor and event=render.finished; retrieve authoritative output from GET /render/completions?job_id. Delivery is at least once, with bounded persisted retry and receipt retention. An already in-flight request can finish after unsubscribe/revocation. Responses never return target_url.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "target_url"
                ],
                "properties": {
                  "target_url": {
                    "type": "string",
                    "format": "uri",
                    "pattern": "^https?://",
                    "description": "Public HTTP(S) destination; maximum 4096 UTF-8 bytes. Private addresses fail at creation; DNS and redirect destinations are checked on each delivery."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created subscription or same-key same-destination existing subscription",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompletionSubscription"
                }
              }
            }
          },
          "400": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "503": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/render/subscriptions/{id}": {
      "delete": {
        "operationId": "unsubscribeRenderFinished",
        "summary": "Remove a completion subscription and its queued deliveries",
        "description": "Requires render or full scope (or an owner session). Unknown and foreign subscriptions both return 404. An attempt already on the network can finish; no new lease or retry survives removal.",
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Owned completion subscription ID."
          },
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "responses": {
          "204": {
            "description": "Removed subscription and delivery receipts."
          },
          "401": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "503": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/render/subscriptions/{id}/replay": {
      "post": {
        "operationId": "replayRenderFinished",
        "summary": "Explicitly replay one owned retained completion",
        "description": "Requires render or full scope. Both the requesting key and issuing key must be permitted to see the completed job. A replay retains its delivery ID and resets the retry window; no account history is automatically replayed. A currently leased delivery returns 409. Job record retention still bounds replay availability.",
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          },
          {
            "connector": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Owned completion subscription ID."
          },
          {
            "$ref": "#/components/parameters/EndUserAnalytics"
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "job_id"
                ],
                "properties": {
                  "job_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued replay receipt.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompletionDelivery"
                }
              }
            }
          },
          "400": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "503": {
            "description": "Coded refusal; no callback URL is included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/accounts": {
      "get": {
        "operationId": "listAccounts",
        "summary": "List current browser memberships",
        "description": "",
        "responses": {
          "200": {
            "description": "List current browser memberships",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Account"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      },
      "post": {
        "operationId": "createAccount",
        "summary": "Create a team account",
        "description": "",
        "responses": {
          "201": {
            "description": "Create a team account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/accounts/{account}/members": {
      "get": {
        "operationId": "listAccountMembers",
        "summary": "List team members",
        "description": "Owner or admin browser authority for this account; member identifiers are an existing actor UUID or a registered email address.",
        "responses": {
          "200": {
            "description": "List team members",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AccountMember"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/accounts/{account}/members/{actor}": {
      "put": {
        "operationId": "setAccountMember",
        "summary": "Add or change a registered member role",
        "description": "Owner or admin required. The last owner cannot be removed or demoted. The actor path accepts an existing actor UUID or registered email address. This endpoint does not send an invitation.",
        "responses": {
          "204": {
            "description": "Add or change a registered member role"
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "editor",
                      "viewer"
                    ]
                  }
                },
                "required": [
                  "role"
                ]
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "actor",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      },
      "delete": {
        "operationId": "removeAccountMember",
        "summary": "Remove a member without deleting account resources",
        "description": "Owner or admin required. Templates and balance remain in the account; the removed member and their keys immediately lose authority.",
        "responses": {
          "204": {
            "description": "Remove a member without deleting account resources"
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "actor",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/embed/origins": {
      "get": {
        "operationId": "listEmbedOrigins",
        "summary": "List registered exact parent origins",
        "description": "",
        "responses": {
          "200": {
            "description": "List registered exact parent origins",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      },
      "put": {
        "operationId": "setEmbedOrigin",
        "summary": "Enable or disable an exact parent origin",
        "description": "Owner or admin browser session. HTTPS exact scheme/host/port; HTTP only on loopback/localhost for development. No wildcard, path, query, fragment or userinfo. Disabling an origin revokes its sessions.",
        "responses": {
          "204": {
            "description": "Enable or disable an exact parent origin"
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string"
                  },
                  "enabled": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "origin",
                  "enabled"
                ]
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/embed/sessions": {
      "post": {
        "operationId": "issueEmbedSession",
        "summary": "Issue a one-use editor bootstrap session",
        "description": "Call from the customer server with a full server API key and an already registered exact parent origin. Derive subject from your authenticated end user. The response includes bootstrap_secret once and expires_at; mode inherits the persisted key. Never expose the server API key to the host page. The session is subject scoped; caller headers cannot forge this identity.",
        "responses": {
          "201": {
            "description": "Issue a one-use editor bootstrap session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmbedSession"
                }
              }
            }
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "502": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subject": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "parent_origin": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "editor",
                      "viewer"
                    ],
                    "default": "editor"
                  },
                  "brand": {
                    "$ref": "#/components/schemas/EmbedBrandRequest"
                  }
                },
                "required": [
                  "subject",
                  "parent_origin"
                ]
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/embed/sessions/{session}": {
      "delete": {
        "operationId": "revokeEmbedSession",
        "summary": "Revoke an editor session",
        "description": "",
        "responses": {
          "204": {
            "description": "Revoke an editor session"
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "name": "session",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/embed/sessions/{session}/editor": {
      "get": {
        "operationId": "getEmbedEditor",
        "summary": "Open the origin-restricted editor wrapper",
        "description": "No secret or credential in this URL. Public HTML includes only session ID, exact parent origin and expiry; CSP frame-ancestors binds that origin. The customer host must deliver bootstrap_secret by the matching postMessage handshake. This wrapper opens the real editor after redemption.",
        "responses": {
          "200": {
            "description": "Open the origin-restricted editor wrapper",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "session",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/embed/sessions/{session}/redeem": {
      "post": {
        "operationId": "redeemEmbedSession",
        "summary": "Redeem a one-use bootstrap secret",
        "description": "Used by the origin-restricted wrapper after exact-origin/source/nonce handshake. Redeem once; expired, revoked or already redeemed sessions are refused. Replies are no-store. Customer applications normally use the browser mount helper.",
        "responses": {
          "200": {
            "description": "Redeem a one-use bootstrap secret",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmbedSession"
                }
              }
            }
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bootstrap_secret": {
                    "type": "string"
                  }
                },
                "required": [
                  "bootstrap_secret"
                ]
              }
            }
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "session",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/principal": {
      "get": {
        "operationId": "getPrincipal",
        "summary": "Read the current credential authority",
        "description": "Account, member role, credential kind/mode and trusted subject resolved from current persisted authority. Selection cannot widen key or embed authority.",
        "responses": {
          "200": {
            "description": "Read the current credential authority",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Principal"
                }
              }
            }
          },
          "400": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "409": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ]
      }
    },
    "/batch-tasks/guest": {
      "post": {
        "operationId": "createGuestBatch",
        "tags": [
          "Batch tasks"
        ],
        "summary": "Run a gallery template batch without an account",
        "security": [],
        "description": "Optional deliver_to sends one ZIP after every row is terminal. Presign HTTPS PUT with application/zip. The private target expires with the original guest batch. Delivery never changes charges; failed delivery includes the DeliveryReceipt no-refund notice.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "template_id",
                  "table"
                ],
                "properties": {
                  "template_id": {
                    "type": "string"
                  },
                  "table": {
                    "type": "string"
                  },
                  "mapping": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "deliver_to": {
                    "$ref": "#/components/schemas/DeliverTo"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Batch registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GuestBatchTaskAccepted"
                }
              }
            }
          }
        }
      }
    },
    "/batch-tasks/guest/preview": {
      "post": {
        "operationId": "previewGuestBatch",
        "tags": [
          "Batch tasks"
        ],
        "summary": "Preview guest batch mapping",
        "security": [],
        "description": "No work is queued. deliver_to is refused: deliver_to is available on async renders and batches only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "template_id",
                  "table"
                ],
                "properties": {
                  "template_id": {
                    "type": "string"
                  },
                  "table": {
                    "type": "string"
                  },
                  "mapping": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "deliver_to": {
                    "$ref": "#/components/schemas/DeliverTo"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mapping preview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchTaskPreview"
                }
              }
            }
          }
        }
      }
    },
    "/batch-tasks/guest/{token}": {
      "get": {
        "operationId": "getGuestBatch",
        "tags": [
          "Batch tasks"
        ],
        "summary": "Guest batch status including optional delivery receipt",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The original guest_token capability."
          }
        ],
        "responses": {
          "200": {
            "description": "Token-scoped batch status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchTaskStatus"
                }
              }
            }
          }
        }
      }
    },
    "/batch-tasks/guest/{token}/archive": {
      "get": {
        "operationId": "downloadGuestBatchArchive",
        "tags": [
          "Batch tasks"
        ],
        "summary": "Guest-token authorized ZIP download",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The original guest_token capability."
          }
        ],
        "responses": {
          "200": {
            "description": "Same ZIP bytes and entries as customer delivery",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/embed/brand/logo": {
      "get": {
        "operationId": "getEmbedBrandLogo",
        "summary": "Read the current embed session brand logo",
        "description": "Current embed principal only, including viewer. No session selector. Live expiry, revocation and ownership are rechecked. Returns no-store and nosniff. Missing logo is not_found; non-embed is principal_access_denied.",
        "security": [
          {
            "embed": []
          }
        ],
        "responses": {
          "200": {
            "description": "Private snapshotted image",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "no-store"
                  ]
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "nosniff"
                  ]
                }
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Typed refusal with a stable error code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/import/pdf": {
      "post": {
        "operationId": "importPdfPage",
        "tags": [
          "Assets"
        ],
        "summary": "Import one PDF page as an unsaved template",
        "description": "Free authoring operation, requiring upload and new-template authority. Consumes one asset slot and moves no credits. Source PDF is temporary. Supports ordinary unrotated pages without text clipping, patterns or soft masks; no OCR or PDF font extraction. Returns a text-free background image and one regular black text layer per bbox-layout block, matched to installed system fonts. Review approximate fonts/placement, then save through POST /presets. The background lock is editor-session only. Refusals occur before storage. See docs/pdf-import.md for coded errors.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "page": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 1,
                    "description": "One-based selected page."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsaved ordinary template and stored background PNG",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PDFImportReply"
                }
              }
            }
          },
          "400": {
            "description": "PDF import refuses missing or multiple sources, non-PDF/unreadable/encrypted input, invalid page/geometry, unsupported artwork, excess layers/text/background size, and template brace tokens. Machine codes use the pdf_import_ prefix except invalid_pdf, pdf_encrypted and pdf_page_out_of_range; existing file_too_large applies to input."
          },
          "401": {
            "description": "Missing/invalid credentials"
          },
          "403": {
            "description": "Authoring scope or preset allowlist refusal, or existing asset quota refusal."
          },
          "503": {
            "description": "pdf_import_unavailable or pdf_import_timeout; no native diagnostics are exposed."
          }
        }
      }
    },
    "/uploads": {
      "post": {
        "operationId": "createUpload",
        "summary": "Create a one-use local-file upload session",
        "description": "Requires full scope and an available asset slot. The returned URL expires at expires_at; send exactly size bytes. Test keys may upload original files without a charge or watermark. The PUT reply contains the stored asset; no second tool call is needed.",
        "tags": [
          "Assets"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUploadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One-use upload session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadSession"
                }
              }
            }
          },
          "400": {
            "description": "Invalid filename, size or content type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope or no asset slots",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "503": {
            "description": "Upload session creation unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/uploads/{token}": {
      "put": {
        "operationId": "putUpload",
        "summary": "Store a local file using an upload session",
        "description": "No authentication header is required: the path token is the credential. Account and subject come only from the session. Send exactly the declared byte count. Content-Type may be omitted; when supplied it must match the declared type. A consumed session remains used on every failure: create a new upload before trying again. Unknown, expired, used and erased-account tokens return the same refusal. The public_link IP policy applies.",
        "tags": [
          "Assets"
        ],
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "PNG bytes; the session must declare image/png."
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "JPEG bytes; the session must declare image/jpeg."
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "WebP bytes; the session must declare image/webp."
              }
            },
            "font/ttf": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "TTF font bytes; the session must declare font/ttf."
              }
            },
            "font/otf": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "OTF font bytes; the session must declare font/otf."
              }
            },
            "application/x-font-ttf": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "TTF font bytes; the session must declare application/x-font-ttf."
              }
            },
            "application/x-font-opentype": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "OTF font bytes; the session must declare application/x-font-opentype."
              }
            },
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "Font bytes only, for a session explicitly declared with content_type application/octet-stream. For images use the image MIME type or omit Content-Type."
              }
            }
          },
          "description": "Send original file bytes with the session's declared content_type, or omit Content-Type. application/octet-stream is accepted only for font sessions explicitly declared with that type; it is not a generic image-upload header."
        },
        "responses": {
          "201": {
            "description": "Stored asset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadedAsset"
                }
              }
            }
          },
          "400": {
            "description": "Short body or invalid file or content type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "No asset slots remain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Upload session not found; create a new upload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "413": {
            "description": "Body larger than the declared size",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "IP request rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "503": {
            "description": "Storage or metadata unavailable; create a new upload before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/images/generate": {
      "post": {
        "operationId": "generateImage",
        "summary": "Make AI images and save them to owned assets",
        "description": "Mirrors generate_asset. Price and current feature availability come from get_capabilities.ai_images.price_credits. Each new image has its own charge and failure refund. Owned cached images are free; variation asks for new art. Full-scope live keys and browser/OAuth sessions may generate; embed sessions are refused. Test keys get validated, free placeholders even when the paid service is disabled.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountSelector"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateImageRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Owned AI images or free test-key placeholders; see failed/refused for partial outcomes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateImageReply"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input, unknown fields or a failed reference download; nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; required, balance, packages_url and money explain the refusal.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Full scope required, account authority refused, unverified email or asset slots exhausted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "A style reference is not owned by the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds the route body limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Account or subject concurrency or daily limit; resets_at says when to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "500": {
            "description": "Storage, billing or recovery unavailable; money describes any uncertain charge.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "503": {
            "description": "Feature disabled or daily server provider budget exhausted; nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "502": {
            "description": "No images delivered. Generation failures carry images, failed/refused and money; infrastructure failures use the common refusal envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GenerateImageReply"
                    },
                    {
                      "$ref": "#/components/schemas/Refusal"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/ai-styles": {
      "post": {
        "operationId": "aiStyle",
        "summary": "Save, list, delete or upgrade a saved art style",
        "description": "Requires full scope. Styles are private to the account and end-user subject. No credits are charged. Saving again by name never changes pinned rules; upgrade does. Deleting a style retains its reference assets. Use the saved id as generate_asset style_id instead of style_refs; an explicit generation background overrides the saved background. A missing reference or unavailable rules version refuses before charging.",
        "tags": [
          "Assets"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AIStyleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Action result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AIStyleReply"
                }
              }
            }
          },
          "400": {
            "description": "Invalid action, name, arguments or references",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Full scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Style not found for this account and subject",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "503": {
            "description": "Style storage unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/art/prepare": {
      "post": {
        "operationId": "prepareArt",
        "summary": "Quote or prepare a preset's art, or read an art job",
        "description": "Requires full scope; embed principals are refused. dry_run works with test keys, but a real test-key run makes no images and says test renders use placeholders. Real jobs run in the API, applying shared image limits, slots and server budget before charging each image through generate_asset's core. Poll job_id; failed images report refunds. An interrupted job says to call prepare_art again; completed art is reused free. Every render surface only reads cached art and refuses missing art before any render charge.",
        "tags": [
          "Rendering"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrepareArtRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote, admitted job, progress or free test-key response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepareArtReply"
                }
              }
            }
          },
          "400": {
            "description": "Invalid arguments, prompt or row",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "403": {
            "description": "Full scope required, embed principal refused or asset slots full",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "404": {
            "description": "Preset, style or job not found for this account and subject",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "429": {
            "description": "Image daily or concurrent limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          },
          "503": {
            "description": "Feature disabled, provider budget exhausted or storage unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-rendry-service-policy": {
    "rates": {
      "rest_render": {
        "requests": 10,
        "window_seconds": 1,
        "burst": 10,
        "scope": "account",
        "consistency": "api_process"
      },
      "mcp_request": {
        "requests": 10,
        "window_seconds": 1,
        "burst": 10,
        "scope": "account",
        "consistency": "api_process"
      },
      "ui_request": {
        "requests": 10,
        "window_seconds": 1,
        "burst": 10,
        "scope": "account",
        "consistency": "api_process"
      },
      "public_link": {
        "requests": 60,
        "window_seconds": 60,
        "burst": 60,
        "scope": "ip",
        "consistency": "api_process"
      },
      "embed_frame": {
        "requests": 10,
        "window_seconds": 60,
        "burst": 10,
        "scope": "ip",
        "consistency": "api_process"
      },
      "embed_redeem": {
        "requests": 10,
        "window_seconds": 60,
        "burst": 10,
        "scope": "ip",
        "consistency": "api_process"
      }
    },
    "sync_concurrency": {
      "account": 4,
      "subject": 2,
      "consistency": "api_process",
      "scope": "synchronous_render"
    },
    "document_queue": {
      "pending_per_account": 4,
      "long_pending_per_account": 1,
      "long_above_pages": 20,
      "consistency": "postgres_transaction",
      "scope": "account; queued and processing documents"
    },
    "retention": {
      "authenticated_days": 365,
      "guest_hours": 72,
      "url_cache_days": 30,
      "starts_at": "authenticated: completion; guest: batch creation"
    },
    "end_user": {
      "header": "X-End-User",
      "max_bytes": 64,
      "pattern": "^[A-Za-z0-9_.:@-]{1,64}$",
      "authority": "analytics only; trusted embedded subject takes precedence"
    },
    "notes": [
      "REST, MCP and UI request buckets are separate; each account bucket is shared by members, keys and embedded subjects",
      "API keys bypass only the UI bucket; authenticated embedded sessions use it",
      "Sync concurrency is per API process; queued document admission is separately reserved in PostgreSQL",
      "Retention is the source policy; deployment of storage lifecycle rules requires a separate operator action"
    ]
  }
}
