openapi: 3.1.0
info:
  title: JamFrame API
  version: 1.0.0
  summary: Render images, carousels, PDFs and short videos from your templates.
  description: |
    The JamFrame REST API turns a template you designed in the JamFrame
    editor into finished files: a PNG, JPEG or WebP image, a multi-page
    carousel, a PDF, or an MP4 video of the animated pages. Send the
    template id and the values to fill in; get back a URL (or base64) for
    each file.

    Every request is authenticated with a per-workspace API key, created
    from the **API Keys** page in the web app.

    ## Authentication

    Send your key in the `Authorization` header as a bearer token:

    ```
    Authorization: Bearer jf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ```

    The key is bound to a single workspace; you don't need to pass a
    workspace id separately. Keys are shown exactly once when you create
    them: store them in a secrets manager, and rotate them by revoking and
    recreating.

    ## Rendering in three steps

    1. Find the template: `GET /designs` lists the workspace's templates.
    2. See what you can fill in: `GET /designs/{id}` returns the template's
       `parameters` (layer keys and `{{placeholders}}`) and page count.
    3. Render it: `POST /render` with the template id and `modifications`.

    Templates from the **template library** (the ready-made designs in the
    editor's Templates tab) can be rendered the same way: pass the library
    template's id as `templateId`, and `GET /designs/{id}` returns its
    parameters too. Credits are charged to your workspace, and the render
    log records the library template's id.

    ## File links

    Rendered files are private. With `response.type: "url"` (the default)
    each file comes back as a link that works for `expiresIn` seconds, a
    top-level field of the render request: 300 (5 minutes) by default, at
    most 604800 (7 days). `expiresAt`, next to `content`, says until when.
    A value outside that range is a `400 VALIDATION_ERROR`.

    - A render job keeps its `expiresIn`: every `GET /render-jobs/{id}`
      answers fresh links that work for that long from then, and the
      `render.*` webhook events and the `webhookUrl` callback carry links
      signed when they are sent.
    - `GET /renders` and `GET /renders/{id}` answer fresh links that work
      for 5 minutes.
    - Files are deleted **8 days** after the render, so a link never
      outlives its file.
    - **Need a permanent link?** Use a Dynamic URL (below): it renders the
      image when it is opened, serves it from the render cache afterwards,
      and works for as long as you keep it on.

    ## Signed and dynamic URLs

    Two ways to render from a plain link, with no API key in the page, for
    an `<img src>`, an email or an `og:image`:

    - **Signed URLs**: `POST /signed-urls` turns one render request into a
      tamper-proof link that renders it when opened (and serves it from the
      render cache afterwards, free). See `GET /r/s/{token}`.
    - **Dynamic URLs**: a template's public link, switched on in the app's
      Integrations, API & Forms dialog, that renders from its query parameters:
      `/r/d/{publicId}.png?headline=Hello`. It has a credit cap, a cache
      time and an expiry. See `GET /r/d/{file}`.

    Both answer with the file's bytes. A render costs credits as usual; a
    request served from the render cache costs nothing.

    ## Smart Resize

    One template renders at any size. `response.size` lays every page out
    at another size: a size saved on the template in the editor's
    **Resize** tab (its id, listed in `GET /designs/{id}` as `sizes`, with
    any manual adjustments), a size name (`story`, `square`, `portrait`,
    `landscape`, `widescreen`, `thumbnail`, `pin`, or a preset id such as
    `instagram-story` or `og-image`), `"WIDTHxHEIGHT"`, or `original`.
    A size the template hasn't saved is laid out automatically: backgrounds
    and photos fill the new canvas, edge decorations stay on their edge,
    and the content is scaled and re-centred. `response.sizes` renders
    several sizes in one call; `content` is then one entry per size,
    `[{ size, url | urls }]`. Credits are 1 per page per size.

    ### Modification keys

    | Key | Effect |
    | --- | --- |
    | `title` | Sets every layer whose parameter key is `title`, and every `{{title}}` placeholder in text. Text layers take new text, image layers an image URL, QR layers the encoded value, shape layers a fill colour. |
    | `page2@title` | The same, on page 2 only (pages are numbered from 1). |
    | `title.color` | Overrides one style property of the `title` layers. |
    | `page2@title.color` | Both: a style override on page 2 only. |

    Style properties by layer type:

    - any layer: `hidden`, `x`, `y`, `width`, `height`, `rotation`,
      `blendMode` (`normal`, `multiply`, `screen`, `overlay`, `darken`,
      `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`,
      `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`),
      `shadowColor` (a CSS colour; a layer has a shadow when it is set),
      `shadowX`, `shadowY` (offset in px), `shadowBlur` (px, 0 or more).
      Text gets the shadow on its letters, other layers one that follows
      their shape.
    - text: `color`, `fontSize`, `fontFamily`, `fontWeight`, `italic`,
      `underline`, `align`, `lineHeight`, `letterSpacing`, `textTransform`,
      `shrinkToFit` (boolean: shrink the text, letter spacing included, until
      it fits its box instead of being cut off; never larger than `fontSize`;
      ignored on layers that grow with their text), `minFontSize` (the
      smallest size `shrinkToFit` may use, in px, greater than 0; default 40%
      of `fontSize`, at least 8), `backgroundColor` (fills the text's box),
      `verticalAlign` (`top`, `middle` or `bottom` in its box),
      `direction` (`auto`, `rtl` or `ltr`: the reading direction; `auto`,
      the default, takes each line's from its first letter, so Hebrew and
      Arabic read right to left; set `rtl` for a Hebrew line that starts
      with a Latin word),
      `textStrokeWidth` (an outline around the letters in px, 0 or more; 0
      is none; centred on their edges and drawn under the fill, so filled
      letters show half of it around them, transparent ones are hollow),
      `textStrokeColor` (default `#000000`)
    - image: `opacity`, `borderRadius`, `flipX`, `flipY`, `fit` (`contain` shows the whole picture; `cover` fills the frame and crops)
    - image and video: a mask, `mask` (a preset outline over the box: `star`,
      `triangle`, `diamond`, `circle`, `pentagon`, `hexagon`, `octagon`,
      `quarterCircle`, `roundedRectangle`, or `none`) or `maskAsset` (the id
      of an SVG in your brand library, used as the mask; `null` removes
      it), with `maskMode` (`alpha`: the SVG's shape shows the picture, the
      default; `luminance`: white shows, black hides). Masks never take a
      URL. The layer's border and shadow follow the mask.
    - image and video: colour effects, `effect` (`grayscale`, `sepia`,
      `vintage`, `warm`, `cool`, `fade`, `dramatic`, `noir`, `vivid`,
      `soft`, or `none`), then adjustments added to it: `blur` (px, 0–100),
      `brightness`, `contrast`, `saturation`, `temperature` (−100 to 100; 0
      leaves the picture as it is), `vibrance`, `whites`, `blacks` (0–100)
    - image: the crop, as fractions of the picture's own size: `cropX`,
      `cropY` (0–1), `cropWidth`, `cropHeight` (above 0, up to 1; left +
      width and top + height at most 1). A crop is kept when you send a new
      picture: one of the same aspect is framed the same; another aspect is
      placed by `fit` (`cover` fills the box around the crop's centre,
      `contain` shows the whole cropped part)
    - shape: `fill`, `stroke`, `strokeWidth`, `cornerRadius` (rectangles:
      corner radius in px, 0 or more, capped at half the shorter side),
      `strokeStyle` (`solid`, `dashed` or `dotted`)
    - qr: `foreground`, `background`
    - video: `fit` (`contain` or `cover`), `startAt` (seconds into the
      clip, 0 or more), `loop` (boolean), `opacity`, `borderRadius`
    - text, image, qr and video layers also take a border, drawn inside the
      box: `borderWidth` (px, 0 or more; 0 is none), `borderColor`,
      `borderStyle` (`solid`, `dashed` or `dotted`)

    A video layer's plain value replaces its clip URL. Video layers are
    always muted; a video's sound is the template's audio track:

    | Key | Effect |
    | --- | --- |
    | `audio` | Replaces the audio track's URL (mp3, m4a, wav or ogg). On a template without a track it adds one at full volume; `null` removes the track. |
    | `audio.volume` | The track's volume, from 0 to 1. |

    Subtitles burned into an MP4 are the template's subtitle track:

    | Key | Effect |
    | --- | --- |
    | `subtitles` | Replaces the cues: SRT or WebVTT text (up to 500 kB), a cue array `[{ "start": 1, "end": 3.2, "text": "…" }]` (seconds on the video's timeline, up to 5000 cues), or the `https` URL of an `.srt` / `.vtt` file (at most 1 MB). Styling tags are stripped. `null` or `""` removes them. |
    | `subtitles.style.<field>` | Restyles them: `fontFamily`, `fontWeight`, `fontSize`, `italic`, `lineHeight`, `textTransform` (`none`, `uppercase`), `color`, `background` (`""` for no box), `boxPadding`, `boxRadius`, `outlineColor`, `outlineWidth`, `position` (`bottom`, `middle`, `top`), `margin`, `maxWidth` (0.2–1 of the width), `maxLines` (1–3), `align`, `highlight` (`none`, `word`: the word being spoken takes `highlightColor`), `highlightColor`. |

    A layer's animation (`timing`) and a page's transition can't be changed
    through `modifications`.

    Numeric properties accept numbers or strings such as `"48px"`; boolean
    properties accept `true`/`false` (or `"true"`, `1`, `"1"`). `null`
    clears a value. Keys that match nothing in the template don't fail the
    render: they come back in `warnings` so you can catch typos.

    ### AI layers and translation

    A text or image layer can be filled by AI when it renders (set up in
    the editor's AI section). Its prompt's `{{placeholders}}` are filled
    from the render's values first, and results are cached per workspace:
    a repeat with the same prompt and values costs no AI credits.

    | Key | Effect |
    | --- | --- |
    | `headline.prompt` | The prompt of the `headline` layers (any text or image layer with a parameter key takes one). `""` turns their AI off. |
    | `headline.tone`, `headline.maxWords` | Text layers: the tone of voice, and at most this many words (1–300). |
    | `photo.style`, `photo.reference` | Image layers: the visual style, and an image URL to edit instead of generating from scratch. The picture is made at the aspect ratio of the layer's box. |
    | `headline` | A plain value skips the AI for those layers: the value is used as is. |

    Top-level `"translate": true` with `"lang": "es"` (any BCP 47 tag)
    translates every text layer's final text, prompt layers included
    (usually in one AI call); placeholders, links and numbers are kept as
    they are. `"ai": { "onError": "fallback" }` renders the layers' saved
    text and images when the AI fails, instead of failing the render.

    Per render (all pages and sizes): at most 50 different text prompts,
    10 different image prompts, 3000 characters per prompt once its
    placeholders are filled, and 50,000 characters of text to translate;
    more is a `400`.

    AI runs only in authenticated renders (API keys, the app, MCP, render
    jobs). Signed and dynamic URLs and template forms render the layers'
    saved text and images, and treat AI keys as unknown. AI credits are a
    separate pool (see `GET /ai/status`): 1 per 500 words written or
    translated, 4 per image, charged once per render and only when it
    succeeds; `data.aiCredits` says how many. An AI failure fails the
    render with its `AI_*` code and charges nothing.

    ## Videos and render jobs

    `response.format: "mp4"` renders the template's pages as one video:
    each page is a scene shown for its duration (set per page in the
    editor, 5 seconds by default), with the layers' animations, video
    layers, the template's audio track and its subtitles. H.264 at 30 fps.
    Scenes of a different size from the first page are scaled to fit and
    letterboxed.

    A page can have a **transition** into the next scene (crossfade, fade
    through black, slides, wipes, zoom, circle; set in the editor). A
    transition overlaps its two scenes, so the video is shorter than the
    pages added up by each transition's duration: two 4 s pages with a
    0.5 s crossfade make a 7.5 s video. The video's length is the MP4's,
    and that's what's billed.

    How long a video can be depends on the plan: 30 seconds on Free, 60 on
    Starter, Plus and Professional. Long videos are rendered in chunks side
    by side and can take longer than the 90 seconds a synchronous request
    waits, so send them with `"async": true` (or poll the job a synchronous
    request hands back).

    `"response": { "format": "mp4", "subtitles": "srt" }` (or `"vtt"`) also
    returns the subtitles as a file next to the video, in `data.subtitles`.

    Videos run as **render jobs**, and so does any render sent with
    `"async": true`:

    - With `"async": true` the API answers at once with
      `202 { "data": { "jobId": "…", "status": "queued" } }`. Poll
      `GET /render-jobs/{id}` until `status` is `succeeded` or `failed`.
    - An MP4 request without `async` waits up to 90 seconds for its job and
      answers `200` with the usual render body (plus `duration`), or
      `202` as above if the video isn't ready yet.
    - Add `"webhookUrl"` to have the finished job POSTed to you
      (`{ "event": "render.completed", "job": { … } }`), and subscribe to the
      `render.completed` and `render.failed` webhook events for every job
      in the workspace.

    Images and PDFs stay synchronous unless you send `"async": true`.

    ## Credits

    A render costs **1 credit per image or PDF page**: a single image is
    1 credit, a 5-slide carousel 5 credits, a 3-page PDF 3 credits. A
    video costs **1 credit per second** of output, rounded up (a 12.5 s
    video costs 13 credits; a transition, which overlaps two scenes, takes
    its duration off the video and the bill). Subtitles and their sidecar
    file cost nothing extra. Credits are charged only after the render
    succeeds; a failed render (or render job) costs nothing. Listing and
    reading templates, listing renders, reading render jobs, and managing
    webhooks are free.

    If the organization's plan can't cover a render, it is refused up front
    with `402 QUOTA_EXCEEDED` (or `402 WORKSPACE_QUOTA_EXCEEDED` when an
    organization admin has capped this workspace's share).

    AI features spend **AI credits**, a separate pool per billing period
    with its own price list (for example 5 per AI image, 1 per 500
    characters of voiceover, 10 per second of AI video at 720p); a failed AI call
    is refunded. `GET /ai/status` shows the price list and what is left;
    an exhausted pool answers `402 AI_CREDITS_EXCEEDED`.

    ## Errors

    All non-2xx responses use a single envelope:

    ```json
    { "error": "QUOTA_EXCEEDED", "message": "...", "detail": { ... } }
    ```

    The `error` code is stable and machine-readable; the `message` is safe
    to show to end users; the optional `detail` object carries structured
    context (for example the remaining credits for `QUOTA_EXCEEDED`).

    ## Rate limits

    Requests are limited per **organization**, per minute, by plan: 100 on
    Free and Starter, 200 on Plus and Professional. All of an
    organization's API keys share the budget. Every authenticated response
    carries the IETF rate-limit headers (draft 7), so clients can throttle
    themselves:

    - `RateLimit: limit=100, remaining=87, reset=42`: requests allowed per
      window, requests left in this one, and seconds until it resets.
    - `RateLimit-Policy: 100;w=60`: the limit and the window in seconds.

    The older separate `RateLimit-Limit` / `RateLimit-Remaining` /
    `RateLimit-Reset` and `X-RateLimit-*` headers are not sent. Exceeding
    the limit returns `429 RATE_LIMITED` with a `Retry-After` header (in
    seconds). Some endpoints have extra limits per workspace (design
    generation, Figma imports, background removal).

    ## Outbound webhooks

    Instead of polling, register a webhook subscription and JamFrame will
    POST signed JSON to your URL when events happen in your workspace.

    ### Event types

    - `design.created`: a template was created in the workspace.
    - `design.updated`: a template was saved.
    - `design.deleted`: a template was deleted.
    - `render.completed`: a render job (an MP4, or an `"async": true`
      render) succeeded.
    - `render.failed`: a render job failed. No credits were charged.
    - `social.post.published`: a social post went out on one of its
      accounts (with its permalink).
    - `social.post.failed`: a social post failed on one of its accounts,
      after its retries (with the reason).
    - `workflow.run.completed`: a workflow run finished with at least one
      row through (`succeeded` or `partial`, or canceled).
    - `workflow.run.failed`: a workflow run failed (no row went through,
      or the source could not be read).

    A `design.*` event's `data` is the template summary (the `Design`
    schema); a `render.*` event's `data` is the render job (the `RenderJob`
    schema); a `social.post.*` event fires once per account of the post and
    its `data` is `{ post, target }` (the `SocialPostEvent` schema); a
    `workflow.run.*` event's `data` is the run (the `WorkflowRun` schema)
    plus `workflowName`.

    ### Subscribe and unsubscribe

    ```bash
    # Create a subscription (returns the signing secret ONCE)
    curl -X POST https://api.jamframe.com/v1/webhooks/subscriptions \
      -H "Authorization: Bearer jf_live_..." \
      -H "Content-Type: application/json" \
      -d '{ "url": "https://hooks.zapier.com/...", "events": ["design.created"] }'

    # Delete a subscription (also what Zapier and Make call when a Zap is deleted)
    curl -X DELETE https://api.jamframe.com/v1/webhooks/subscriptions/{id} \
      -H "Authorization: Bearer jf_live_..."
    ```

    ### Delivery headers

    | Header | Value |
    | --- | --- |
    | `X-Webhook-Event` | The event type, e.g. `design.updated`. |
    | `X-Webhook-Delivery` | Delivery id: unique per subscription and event, unchanged across retries. Use it as your idempotency key. |
    | `X-Webhook-Timestamp` | Unix seconds when this attempt was signed. |
    | `X-Webhook-Signature` | `t=<unixSeconds>,v1=<hexHmacSha256>` |
    | `User-Agent` | `JamFrame-Webhook/1` |

    ### Signature verification

    `v1` is the HMAC-SHA256 of `${t}.${rawRequestBody}`, keyed with the
    subscription's signing secret. Verify against the **raw** body (re-
    serialising the JSON changes the bytes) and reject requests where
    `|now - t| > 300` seconds to defeat replays.

    ```js
    const crypto = require("node:crypto");
    function verify(rawBody, signatureHeader, secret) {
      const parts = Object.fromEntries(
        signatureHeader.split(",").map((p) => p.split("=")),
      );
      const expected = crypto
        .createHmac("sha256", secret)
        .update(`${parts.t}.${rawBody}`)
        .digest("hex");
      const ok = crypto.timingSafeEqual(
        Buffer.from(expected, "hex"),
        Buffer.from(parts.v1, "hex"),
      );
      const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
      return ok && fresh;
    }
    ```

    ### Retries, idempotency, suspension

    - Deliveries are **at-least-once**: deduplicate on `X-Webhook-Delivery`.
    - Any 2xx is success. Anything else (including redirects, which are
      not followed) and timeouts (10 seconds) are retried with backoff:
      1m, 5m, 30m, 2h, 12h, 24h. After the 7th failed attempt the
      delivery is marked `failed`.
    - HTTP `410 Gone` is treated as the REST Hooks "unsubscribe" signal:
      the subscription is deleted, so you can subscribe the same URL again.
    - After 20 consecutive failures a subscription is `suspended`.
      Re-activate it from the **Webhooks** page in the web app after
      fixing your endpoint.
    - A subscription delivers as the person who created it: when they
      stop being an editor of the workspace (removed, left, demoted, grant
      lowered) it becomes `revoked`, for good, even if they get access
      back. Create a new one.

servers:
  - url: https://api.jamframe.com/v1
    description: Production
  - url: http://localhost:3100/v1
    description: Local development

security:
  - bearerAuth: []

tags:
  - name: Auth
    description: |
      Test-authentication endpoint used by integrations (e.g. Zapier) to
      verify an API key and display a human-readable label for the
      connected workspace.
  - name: Render
    description: |
      Render a template into images, a carousel, a PDF or an MP4 video, at
      its own size or any other (Smart Resize: `response.size` and
      `response.sizes`). Each render costs 1 credit per image or PDF page,
      or 1 credit per second of video. Videos and `async` renders run as
      render jobs (`GET /render-jobs/{id}`). `GET /renders` lists past
      renders with their files. If video rendering is turned off, an MP4
      request answers `503 VIDEO_UNAVAILABLE` at once and charges nothing.
  - name: Signed URLs
    description: |
      Sign a render request into a public URL that renders it when opened.
      The URLs themselves are served at `/r/s/...` (see **Public URLs**).
  - name: Public URLs
    description: |
      Anonymous image and PDF URLs, served from the app's origin (not under
      `/api/v1`): signed URLs and dynamic URLs. They answer with the file's
      bytes; errors are a small JSON body (`PublicUrlError`). Limits per
      minute: 120 requests per IP and 1200 per URL; renders (cache misses)
      20 per IP, 30 per URL and 120 per workspace.
  - name: Public forms
    description: |
      A template's public self-serve form (`/f/<publicId>` in the app),
      made in the app's Integrations, API & Forms dialog: anyone with the
      link fills it in, sees a live preview and downloads the result. No
      authentication: the public id is the credential, and renders spend the form owner's
      credits within the form's credit cap. Served from the app's origin
      under `/api/public/forms` (not under `/api/v1`). Cloudflare Turnstile
      is required on render and on a visit's first upload when the server
      has it configured (a production server without it refuses both with
      `503 CAPTCHA_UNAVAILABLE`). Limits per minute: 120 requests per IP;
      renders 10 per IP, 30 per form and 120 per workspace; uploads 20 per
      IP (100 an hour) and 30 per form (300 an hour). Errors are
      `PublicFormError`. See docs/forms.md.
  - name: Designs
    description: |
      A **design** is a template authored in the JamFrame editor: one or
      more pages (a carousel, or a post plus a story) whose layers can be
      filled in through the API. Designs are made and edited in the web
      app; through the API you can also generate one with AI
      (`POST /designs/generate`), have a workflow create one, or import
      frames from Figma (**Figma import**).
  - name: Figma import
    description: |
      Create templates from Figma frames: the endpoints behind the Figma
      plugin (see `docs/figma-plugin.md` in the repository). The one way to
      create designs through the API; they are then rendered like any other.
      Both methods answer CORS for any origin (the plugin's iframe has a
      `null` origin; the credential is the bearer key, never a cookie).
  - name: Social
    description: |
      Post renders to connected social accounts (Instagram, Facebook
      Pages, LinkedIn profiles and pages, X, TikTok, YouTube, Pinterest,
      Bluesky, and Buffer channels): render a
      template and post it in one call, or post an earlier render or media
      URLs; now, scheduled in a time zone, or as a draft. Accounts are
      connected in the app. Posting costs no credits; renders cost the
      usual credits.
      Analytics (`/social/analytics/*`) reports how posts are doing:
      impressions, reach, likes, comments, shares, saves and clicks.
  - name: Workflows
    description: |
      Automations that read rows (Google Sheets, a CSV or XLSX file at a
      URL, an Airtable view, a Google Drive folder, or an incoming webhook's
      payload), filter and sort them, render a template per row (normal
      render credits) and deliver each render (its URL, an outgoing
      webhook, Slack, social posts, written back to the sheet, uploaded to
      Drive). Triggers: Run Now, a schedule, an incoming webhook, or new
      rows. Only `active` workflows fire on their own. Runs are
      asynchronous: start one, then poll it for each row's outcome. Plan
      limits apply to runs a month, workflows, steps per workflow, runs at
      once and rows per run (402 `PLAN_LIMIT_EXCEEDED`). See
      docs/workflows.md.
  - name: AI
    description: |
      Whether AI features are available on this server (`live`, `mock` on a
      development server without an AI key, or `off`), the models behind
      each task, the AI credit price list, and the organization's AI
      credits for the billing period. AI errors use the `AI_*` codes:
      `AI_UNAVAILABLE` (503), `AI_CONTENT_REFUSED` (422), `AI_TIMEOUT`
      (504), `AI_RATE_LIMITED` (429), `AI_BAD_OUTPUT` (502),
      `AI_BAD_REQUEST` (422), `AI_UPSTREAM_ERROR` (502) and
      `AI_CREDITS_EXCEEDED` (402). `POST /designs/generate` designs a new
      template with the design agent (15–30 AI credits).
      `POST /images/remove-background` cuts a picture out on a transparent
      background (1 AI credit) and `POST /ai/transcribe` turns speech into
      subtitle cues for `modifications.subtitles` (1 AI credit a minute).
  - name: Webhooks
    description: |
      Outbound webhooks deliver workspace events (`design.created`,
      `design.updated`, `design.deleted`, `render.completed`,
      `render.failed`, `social.post.published`, `social.post.failed`,
      `workflow.run.completed`, `workflow.run.failed`) to
      a URL you supply.
      Subscriptions are scoped to the API key's workspace; payloads are
      signed with HMAC-SHA256 (see "Outbound webhooks" in the
      introduction for verification and retry semantics).

x-tagGroups:
  - name: Rendering
    tags: [Render, Signed URLs, Public URLs, Public forms]
  - name: Templates
    tags: [Designs, AI, Figma import]
  - name: Automation
    tags: [Workflows, Social, Webhooks]
  - name: Account
    tags: [Auth]

paths:
  /auth:
    post:
      tags: [Auth]
      operationId: testAuth
      summary: Test API key
      description: |
        Verifies the bearer API key and returns a human-readable
        `username` for the connected workspace. Intended as Zapier's
        "Test Auth" / connection-label endpoint: a 2xx response confirms
        the key is valid and the returned `username` is safe to show in
        the integration UI.
      responses:
        '200':
          description: API key is valid.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AuthResult' }
              examples:
                default:
                  value: { workspaceId: ws_abc123, username: Jane Doe }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /render:
    post:
      tags: [Render]
      operationId: renderTemplate
      summary: Render a template
      description: |
        Renders a template from the API key's workspace, or a template
        from the template library (by its id), with your values and returns
        the files. Library templates are charged to your workspace like your
        own, and the render log records the library template's id.

        - **Images** (`png`, `jpeg`, `webp`) give one file per page, so a
          multi-page template is a carousel. `content` is a single string
          when one file is produced and an array (in page order) when
          several are.
        - **PDF** gives one file containing every rendered page, so
          `content` is always a single string.
        - **MP4** gives one video with every rendered page as a scene, so
          `content` is a single URL, and `duration` gives its length in
          seconds (scene transitions overlap their scenes, so it can be
          less than the pages added up). At most 30 seconds on Free, 60 on
          Starter, Plus and Professional. With `response.subtitles`,
          `subtitles` is the URL of the subtitle file. If video rendering is
          turned off, an MP4 request is refused at once with
          `503 VIDEO_UNAVAILABLE`: nothing is queued or charged.

        Use `response.includePages` to render only some pages; at most 20
        pages can be rendered per request.

        **Smart Resize.** `response.size` renders every page at another
        size: a size saved on the template (its id), a size name such as
        `story` or `instagram-story`, `"WIDTHxHEIGHT"` (16 to 10000 px) or
        `original`; an unknown size is a `400` that lists the template's
        sizes. It works with every format, MP4 included (one size per
        video). `response.sizes` (up to 10) renders each size in one
        synchronous call and answers `content` as one entry per size, in
        the order asked: `{ size, name, width, height, pages, url }` for a
        single file (one page, or a PDF) or `urls` for a carousel. `sizes`
        can't be combined with `size`, `mp4`, `async` or `base64`; a size
        listed twice (also under another name, like `story` and
        `1080x1920`) is a `400`, and so is a call over 30 pages in all
        (pages × sizes). Cost: 1 credit per page per size.

        **Limits on what a render loads and makes.** Image and video URLs
        (in the template or in `modifications`) must be public `http(s)`
        addresses, `data:` URLs or the template library's own files: a
        private, loopback or link-local host (`localhost`, `10.x`,
        `169.254.169.254`, a `//host` path…) is a `400`, and a host name
        that resolves to such an address fails the render with a `422`
        (no credits charged). Each page's output is at most 36 megapixels
        (width × height × `scale`²), a `400` above that.

        With `response.type: "url"` (the default) each file is stored and
        `content` holds links to the files that work for `expiresIn`
        seconds (default 300, at most 604800 = 7 days); `expiresAt` says
        until when. The files are deleted 8 days after the render: for a
        permanent image link, use a Dynamic URL. With `"base64"` nothing is
        stored and `content` holds the raw base64 bytes (no `data:`
        prefix); base64 is only available for synchronous image and PDF
        renders, and takes no `expiresIn`.

        **Render jobs.** MP4 renders and requests with `"async": true` run
        as render jobs. With `"async": true` the answer is `202` with the
        job id at once (and a `Location` header pointing at the job). An
        MP4 request without `async` waits up to 90 seconds and then answers
        `200` with the render, or `202` with the job id if it is still
        running. Either way, `GET /render-jobs/{id}` reports progress and
        the result (with fresh links on every read, for the request's
        `expiresIn`), and `webhookUrl` (render jobs only) receives
        `{ "event", "job" }` when the job ends. A request that can't
        succeed (an unknown template, an invalid modification or subtitle
        file, a video over the plan's limit, not enough credits) is refused
        before anything is queued, with the same errors as a synchronous
        render.

        **AI layers and translation** (see the introduction): `.prompt`,
        `.tone`, `.maxWords`, `.style` and `.reference` keys, and top-level
        `translate` + `lang` and `ai.onError`. AI results are made once per
        request (every size, page and video frame shares them), cached per
        workspace, and charged in AI credits only when the render succeeds
        (`data.aiCredits`, 0 when everything came from the cache). An AI
        failure answers its `AI_*` code (`402 AI_CREDITS_EXCEEDED`, `422
        AI_CONTENT_REFUSED`, `503 AI_UNAVAILABLE`, …) and charges nothing,
        unless `"ai": { "onError": "fallback" }` asks for the saved text and
        images instead.

        **Print-ready and smaller PDFs (experimental).** With
        `"format": "pdf"`, `response.cmyk` converts the PDF's colours to
        CMYK for print with an ICC profile (text and shapes stay vector; the
        file is labelled PDF/X-4 when it qualifies), and `response.compress`
        makes the file smaller (images downsampled to a resolution, photos
        stored as JPEG). Both are off by default. They are experimental:
        their options and output may still change. They cost nothing extra.

        Cost: 1 credit per image or PDF page, or 1 credit per second of
        video (rounded up), charged only after a successful render.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RenderRequest' }
            examples:
              aiLayers:
                summary: AI layers, translated
                value:
                  templateId: clx8m2k3p0001abcd1234efgh
                  modifications:
                    product: Cold brew
                    headline.prompt: Write a 6-word headline about {{product}}
                    photo.prompt: A glass of {{product}} on a marble table, morning light
                    photo.style: photo
                  translate: true
                  lang: es
                  ai:
                    onError: fallback
              singleImage:
                summary: A single PNG
                value:
                  templateId: clx8m2k3p0001abcd1234efgh
                  modifications:
                    title: Summer sale ends Sunday
                    subtitle: Up to 50% off everything
                    photo: https://example.com/images/beach.jpg
                    title.color: '#FF4D4F'
                  response:
                    type: url
                    format: png
                    scale: 2
              longLink:
                summary: A PNG whose link works for 7 days
                value:
                  templateId: clx8m2k3p0001abcd1234efgh
                  modifications:
                    title: Summer sale ends Sunday
                  response:
                    format: png
                  expiresIn: 604800
              carousel:
                summary: A carousel with per-slide text
                value:
                  templateId: clx8m2k3p0002abcd1234efgh
                  modifications:
                    brand: Acme Coffee
                    title: 5 ways to brew better coffee
                    page2@title: 1. Grind just before brewing
                    page3@title: 2. Weigh your beans
                    page3@title.fontSize: 56
                  response:
                    format: jpeg
                    quality: 90
              pdf:
                summary: A two-page PDF
                value:
                  templateId: clx8m2k3p0003abcd1234efgh
                  modifications:
                    customer_name: Jane Doe
                  response:
                    format: pdf
                    includePages: [1, 2]
              printPdf:
                summary: A print-ready CMYK PDF, compressed (experimental)
                value:
                  templateId: clx8m2k3p0003abcd1234efgh
                  modifications:
                    customer_name: Jane Doe
                  response:
                    format: pdf
                    cmyk:
                      profile: fogra39
                    compress:
                      preset: printer
              video:
                summary: An MP4 video (waits up to 90 s)
                value:
                  templateId: clx8m2k3p0004abcd1234efgh
                  modifications:
                    title: New season, new menu
                    clip: https://example.com/videos/kitchen.mp4
                    audio: https://example.com/audio/upbeat.mp3
                    audio.volume: 0.6
                  response:
                    format: mp4
              story:
                summary: 'Smart Resize: the design as a 1080×1920 story'
                value:
                  templateId: clx8m2k3p0001abcd1234efgh
                  modifications:
                    title: Summer sale ends Sunday
                  response:
                    format: png
                    size: story
              everySize:
                summary: 'Smart Resize: several sizes in one call'
                value:
                  templateId: clx8m2k3p0001abcd1234efgh
                  modifications:
                    title: Summer sale ends Sunday
                  response:
                    format: png
                    sizes: [original, story, square, 1200x630]
              videoSubtitles:
                summary: An MP4 with subtitles from an SRT file, restyled, plus a .vtt copy
                value:
                  templateId: clx8m2k3p0004abcd1234efgh
                  modifications:
                    title: New season, new menu
                    subtitles: https://example.com/captions/new-menu.srt
                    subtitles.style.position: top
                    subtitles.style.highlight: word
                  response:
                    format: mp4
                    subtitles: vtt
              videoCues:
                summary: An MP4 with subtitles given as cues
                value:
                  templateId: clx8m2k3p0004abcd1234efgh
                  modifications:
                    subtitles:
                      - { start: 0.4, end: 3.2, text: Meet our new menu }
                      - { start: 3.5, end: 6.8, text: Every dish made fresh today }
                  response:
                    format: mp4
              asyncVideo:
                summary: An MP4 video as a render job, with a callback
                value:
                  templateId: clx8m2k3p0004abcd1234efgh
                  async: true
                  webhookUrl: https://hooks.example.com/jamframe/render-done
                  modifications:
                    title: New season, new menu
                  response:
                    format: mp4
      responses:
        '200':
          description: Rendered. Credits have been charged.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RenderResponse' }
              examples:
                singleImage:
                  summary: A single PNG
                  value:
                    data:
                      content: https://cdn.jamframe.com/renders/ws_abc123/5f0c6b0e-7d1a-4e8b-9c55-0d8f5f0a1b2c.png?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                      expiresAt: '2026-11-09T12:05:00.000Z'
                      type: url
                      format: png
                      pages: [1]
                      credits: 1
                      renderId: clx8n0q1r0004abcd1234efgh
                      responseTime: 1840
                carousel:
                  summary: A three-slide carousel
                  value:
                    data:
                      content:
                        - https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-4d5e-4f60-8a7b-1c2d3e4f5a6b-p1.jpg?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                        - https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-4d5e-4f60-8a7b-1c2d3e4f5a6b-p2.jpg?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                        - https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-4d5e-4f60-8a7b-1c2d3e4f5a6b-p3.jpg?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                      expiresAt: '2026-11-09T12:05:00.000Z'
                      type: url
                      format: jpeg
                      pages: [1, 2, 3]
                      credits: 3
                      renderId: clx8n0q1r0005abcd1234efgh
                      responseTime: 4210
                everySize:
                  summary: Several sizes (response.sizes)
                  value:
                    data:
                      content:
                        - size: original
                          name: Original
                          width: 1080
                          height: 1350
                          pages: [1]
                          url: https://cdn.jamframe.com/renders/ws_abc123/7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a-s1.png?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                        - size: story
                          name: Story / Reel
                          width: 1080
                          height: 1920
                          pages: [1]
                          url: https://cdn.jamframe.com/renders/ws_abc123/7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a-s2.png?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                        - size: square
                          name: Square
                          width: 1080
                          height: 1080
                          pages: [1]
                          url: https://cdn.jamframe.com/renders/ws_abc123/7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a-s3.png?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                        - size: 1200x630
                          name: 1200×630
                          width: 1200
                          height: 630
                          pages: [1]
                          url: https://cdn.jamframe.com/renders/ws_abc123/7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a-s4.png?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                      expiresAt: '2026-11-09T12:05:00.000Z'
                      type: url
                      format: png
                      pages: [1]
                      credits: 4
                      renderId: clx8n0q1r0007abcd1234efgh
                      responseTime: 5120
                withAi:
                  summary: A render with AI layers (6 AI credits; a repeat costs 0)
                  value:
                    data:
                      content: https://cdn.jamframe.com/renders/ws_abc123/1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a.png?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                      expiresAt: '2026-11-09T12:05:00.000Z'
                      type: url
                      format: png
                      pages: [1]
                      credits: 1
                      renderId: clx8n0q1r0009abcd1234efgh
                      responseTime: 6240
                      aiCredits: 6
                withWarning:
                  summary: An unknown key is reported, not fatal
                  value:
                    data:
                      content: https://cdn.jamframe.com/renders/ws_abc123/0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e.png?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                      expiresAt: '2026-11-09T12:05:00.000Z'
                      type: url
                      format: png
                      pages: [1]
                      credits: 1
                      renderId: clx8n0q1r0006abcd1234efgh
                      responseTime: 1650
                    warnings:
                      - 'Unknown modification keys (no matching layer or {{placeholder}}): titel'
                video:
                  summary: An MP4 video
                  value:
                    data:
                      content: https://cdn.jamframe.com/renders/ws_abc123/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f.mp4?Expires=1794225900&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                      expiresAt: '2026-11-09T12:05:00.000Z'
                      type: url
                      format: mp4
                      pages: [1, 2]
                      credits: 13
                      renderId: clx8n0q1r0007abcd1234efgh
                      responseTime: 14230
                      duration: 13
        '202':
          description: |
            Queued as a render job: an `async` request, or an MP4 still
            rendering after 90 seconds. Poll `GET /render-jobs/{jobId}`, or
            wait for the `webhookUrl` callback or the `render.*` webhook
            events. Credits are charged when the job succeeds.
          headers:
            Location:
              description: Path of the render job, e.g. `/v1/render-jobs/clx8n0q1r0008abcd1234efgh`.
              schema: { type: string }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RenderJobAccepted' }
              examples:
                queued:
                  value:
                    data: { jobId: clx8n0q1r0008abcd1234efgh, status: queued }
        '400':
          description: |
            The request body was invalid (see `ValidationError` for the
            common cases; also a video longer than the plan allows, text in
            `modifications.subtitles` (or the file it points to) that isn't
            SRT or WebVTT, `response.subtitles` without `mp4`, `base64` with
            an MP4 or `async` render, a `webhookUrl` on a synchronous
            render, or `expiresIn` outside 1–604800 or sent with `base64`),
            or `webhookUrl` failed validation
            (`WEBHOOK_URL_INVALID`: not http(s), or a private or loopback
            address).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              examples:
                badBody:
                  value:
                    error: VALIDATION_ERROR
                    message: Invalid render request
                    detail:
                      issues:
                        - code: invalid_type
                          path: [templateId]
                          message: 'Invalid input: expected string, received undefined'
                tooLong:
                  value:
                    error: VALIDATION_ERROR
                    message: 'A video can be at most 60 seconds long on the free plan; the rendered pages add up to 70.5 seconds. Render fewer pages (includePages) or shorten them in the editor.'
                    detail: { seconds: 70.5, max: 60, planCode: free }
                badSubtitles:
                  value:
                    error: VALIDATION_ERROR
                    message: '"subtitles": SRT cue 2: expected a timing line (00:00:01,000 --> 00:00:03,500), found "00:00:03,000 -> 00:00:05,000"'
                badExpiresIn:
                  summary: A link time over 7 days
                  value:
                    error: VALIDATION_ERROR
                    message: 'expiresIn is how long the file links work, in whole seconds: from 1 to 604800 (7 days), default 300. For a link that never expires, use a Dynamic URL.'
                    detail: { field: expiresIn, min: 1, max: 604800, default: 300 }
                badWebhookUrl:
                  value:
                    error: WEBHOOK_URL_INVALID
                    message: 'webhookUrl: url must not target a private host'
                    detail: { field: webhookUrl, reason: url must not target a private host }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422':
          description: An image or video in the template or in `modifications`, the audio track, or the subtitle file a `subtitles` URL points to could not be loaded (not public, not the right kind of file, or unreachable). No credits are charged.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              examples:
                image:
                  value:
                    error: VALIDATION_ERROR
                    message: 'Image failed to load: https://example.com/missing.jpg. Check that the URL is public and points to an image. No credits were charged.'
                video:
                  value:
                    error: VALIDATION_ERROR
                    message: 'Video failed to load: https://example.com/missing.mp4. Check that the URL is public and points to a video. No credits were charged.'
                audio:
                  value:
                    error: VALIDATION_ERROR
                    message: 'Audio failed to load: https://example.com/missing.mp3 (the server answered HTTP 404). No credits were charged.'
                aiRefused:
                  summary: The AI provider refused a prompt (AI_BAD_REQUEST is also a 422)
                  value:
                    error: AI_CONTENT_REFUSED
                    message: The AI provider refused this request because of its content policy. No credits were charged.
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/RenderFailed' }
        '502':
          description: An AI layer or the translation failed upstream (`AI_BAD_OUTPUT`, `AI_UPSTREAM_ERROR`). No credits were charged; retrying is safe.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              examples:
                badOutput:
                  value:
                    error: AI_BAD_OUTPUT
                    message: The AI did not return a usable result. No credits were charged.
                    detail: { model: anthropic/claude-haiku-5.5 }
        '503':
          description: |
            The render needs AI and AI is not available on this server
            (`AI_UNAVAILABLE`). Send `"ai": { "onError": "fallback" }` to
            render the saved text and images instead. Or MP4 video is
            turned off on this server (`VIDEO_UNAVAILABLE`): render png,
            jpeg, webp or pdf. No credits were charged.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              examples:
                unavailable:
                  value:
                    error: AI_UNAVAILABLE
                    message: AI features are not available on this server. No credits were charged.
                    detail: { reason: off }
                videoUnavailable:
                  value:
                    error: VIDEO_UNAVAILABLE
                    message: 'MP4 video is turned off on this server. Render png, jpeg, webp or pdf instead. No credits were charged.'
        '504':
          description: An AI layer or the translation took too long (`AI_TIMEOUT`). No credits were charged.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }

  /render-jobs/{id}:
    get:
      tags: [Render]
      operationId: getRenderJob
      summary: Get a render job
      description: |
        A render job of the API key's workspace: an MP4 render, or a render
        sent with `"async": true`. Poll it (once a second is plenty) until
        `status` is `succeeded`, then read the files from `result`, the
        same object a synchronous render returns as `data`. A `failed` job
        carries the error a synchronous render would have answered, in
        `error`, and costs nothing.

        Every read answers fresh file links that work for the request's
        `expiresIn` (default 300 seconds) from then, until `expiresAt`, for
        as long as the files exist: they are deleted 8 days after the
        render.

        While a video renders, `progress` goes from 0 to 1 (frames
        captured out of the total).
      parameters:
        - in: path
          name: id
          required: true
          description: The `jobId` from the `202` answer of `POST /render`.
          schema: { type: string, maxLength: 64 }
      responses:
        '200':
          description: The render job.
          content:
            application/json:
              schema:
                type: object
                required: [job]
                properties:
                  job: { $ref: '#/components/schemas/RenderJob' }
              examples:
                running:
                  value:
                    job:
                      id: clx8n0q1r0008abcd1234efgh
                      status: running
                      progress: 0.42
                      format: mp4
                      templateId: clx8m2k3p0004abcd1234efgh
                      createdAt: '2026-11-09T12:36:24.161Z'
                      startedAt: '2026-11-09T12:36:24.165Z'
                      finishedAt: null
                      result: null
                      error: null
                succeeded:
                  value:
                    job:
                      id: clx8n0q1r0008abcd1234efgh
                      status: succeeded
                      progress: 1
                      format: mp4
                      templateId: clx8m2k3p0004abcd1234efgh
                      createdAt: '2026-11-09T12:36:24.161Z'
                      startedAt: '2026-11-09T12:36:24.165Z'
                      finishedAt: '2026-11-09T12:36:38.786Z'
                      result:
                        content: https://cdn.jamframe.com/renders/ws_abc123/c724edf3-728c-4b57-8c31-4c2c0348ae6d.mp4?Expires=1794228100&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                        expiresAt: '2026-11-09T12:41:40.000Z'
                        type: url
                        format: mp4
                        pages: [1, 2]
                        credits: 13
                        renderId: clx8n0q1r0009abcd1234efgh
                        responseTime: 14604
                        duration: 13
                      error: null
                failed:
                  value:
                    job:
                      id: clx8n0q1r0010abcd1234efgh
                      status: failed
                      progress: 0
                      format: mp4
                      templateId: clx8m2k3p0004abcd1234efgh
                      createdAt: '2026-11-09T12:37:57.100Z'
                      startedAt: '2026-11-09T12:37:57.105Z'
                      finishedAt: '2026-11-09T12:37:57.264Z'
                      result: null
                      error:
                        error: VALIDATION_ERROR
                        message: 'Video failed to load: https://example.com/missing.mp4. Check that the URL is public and points to a video. No credits were charged.'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404':
          description: No render job with this id in the API key's workspace.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example:
                error: NOT_FOUND
                message: Render job clx8n0q1r0008abcd1234efgh not found in this workspace
        '429': { $ref: '#/components/responses/RateLimited' }

  /renders:
    get:
      tags: [Render]
      operationId: listRenders
      summary: List renders
      description: |
        Returns the workspace's renders, newest first: those made through
        this API, the web app's test render, and integrations such as
        Zapier and Make. Failed renders are listed too, with the reason;
        they cost no credits.

        Each item lists its stored files in `outputs`, as fresh links that
        work for 5 minutes (`expiresAt`). Files are deleted 8 days after the
        render, so links to older renders no longer work. Renders requested
        with `response.type: "base64"` stored nothing, so their `outputs`
        is empty.

        `totals` reports the current billing period's credit usage, so a
        client can show how many credits are left without another call.
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - in: query
          name: status
          schema:
            type: string
            enum: [succeeded, failed]
          description: Only renders with this status. Any other value is a `400 VALIDATION_ERROR`.
        - in: query
          name: designId
          schema: { type: string, maxLength: 64 }
          description: Only renders of this design (template).
      responses:
        '200':
          description: A page of renders.
          content:
            application/json:
              schema:
                type: object
                required: [renders, pagination, totals]
                properties:
                  renders:
                    type: array
                    items: { $ref: '#/components/schemas/RenderItem' }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                  totals: { $ref: '#/components/schemas/RenderTotals' }
              examples:
                default:
                  value:
                    renders:
                      - id: clx8n0q1r0005abcd1234efgh
                        createdAt: '2026-11-08T14:21:05.000Z'
                        designId: clx8m2k3p0002abcd1234efgh
                        designName: Coffee tips carousel
                        source: api
                        format: jpeg
                        pages: 2
                        credits: 2
                        status: succeeded
                        durationMs: 4210
                        outputs:
                          - url: https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-4d5e-4f60-8a7b-1c2d3e4f5a6b-p1.jpg?Expires=1794215100&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                            page: 1
                            expiresAt: '2026-11-09T09:05:00.000Z'
                          - url: https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-4d5e-4f60-8a7b-1c2d3e4f5a6b-p2.jpg?Expires=1794215100&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                            page: 2
                            expiresAt: '2026-11-09T09:05:00.000Z'
                        error: null
                        cached: false
                      - id: clx8n0q1r0006abcd1234efgh
                        createdAt: '2026-11-08T14:20:58.000Z'
                        designId: clx8m2k3p0001abcd1234efgh
                        designName: Blog OG image
                        source: dynamic-url
                        format: png
                        pages: 1
                        credits: 0
                        status: succeeded
                        durationMs: 6
                        outputs:
                          - url: https://cdn.jamframe.com/url-renders/ws_abc123/0d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a.png?Expires=1794215100&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                            page: 1
                            expiresAt: '2026-11-09T09:05:00.000Z'
                        error: null
                        cached: true
                      - id: clx8n0q1r0004abcd1234efgh
                        createdAt: '2026-11-08T14:20:41.000Z'
                        designId: null
                        designName: null
                        source: editor
                        format: png
                        pages: 1
                        credits: 0
                        status: failed
                        durationMs: 30012
                        outputs: []
                        error: 'Navigation timeout of 30000 ms exceeded'
                        cached: false
                    pagination:
                      nextCursor: clx8n0q1r0004abcd1234efgh
                      hasMore: true
                    totals:
                      periodStart: '2026-11-01T00:00:00.000Z'
                      periodEnd: '2026-12-01T00:00:00.000Z'
                      creditsUsed: 342
                      creditsQuota: 1000
                      creditsRemaining: 658
                      workspaceCreditsUsed: 120
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /renders/{id}:
    get:
      tags: [Render]
      operationId: getRender
      summary: Get a render
      description: |
        One render of the API key's workspace, the same item `GET /renders`
        lists: its status, credits, and stored files in `outputs` (fresh
        links that work for 5 minutes). Use it to look up a `renderId` from
        a render response, a render job's `result`, or a `render.completed`
        webhook.

        Returns `404 NOT_FOUND` when no render has this id in the key's
        workspace.
      parameters:
        - in: path
          name: id
          required: true
          description: The render id (`renderId` in a render response).
          schema: { type: string, maxLength: 64 }
      responses:
        '200':
          description: The render.
          content:
            application/json:
              schema:
                type: object
                required: [render]
                properties:
                  render: { $ref: '#/components/schemas/RenderItem' }
              examples:
                carousel:
                  value:
                    render:
                      id: clx8n0q1r0005abcd1234efgh
                      createdAt: '2026-11-08T14:21:05.000Z'
                      designId: clx8m2k3p0002abcd1234efgh
                      designName: Coffee tips carousel
                      source: api
                      format: jpeg
                      pages: 2
                      credits: 2
                      status: succeeded
                      durationMs: 4210
                      outputs:
                        - url: https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-4d5e-4f60-8a7b-1c2d3e4f5a6b-p1.jpg?Expires=1794215100&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                          page: 1
                          expiresAt: '2026-11-09T09:05:00.000Z'
                        - url: https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-4d5e-4f60-8a7b-1c2d3e4f5a6b-p2.jpg?Expires=1794215100&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                          page: 2
                          expiresAt: '2026-11-09T09:05:00.000Z'
                      error: null
                      cached: false
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404':
          description: No render with this id in the API key's workspace.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example:
                error: NOT_FOUND
                message: Render clx8n0q1r0005abcd1234efgh not found in this workspace
        '429': { $ref: '#/components/responses/RateLimited' }

  /signed-urls:
    post:
      tags: [Signed URLs]
      operationId: createSignedUrl
      summary: Create a signed URL
      description: |
        Signs a render request into a public URL. Nothing is rendered or
        charged now: opening the URL renders the template (1 credit per
        image, or per PDF page) and answers with the file itself, so it
        works as an `<img src>`, in emails and as an `og:image`. Later
        requests for the same URL are served from the render cache for
        `cacheSeconds` (default 30 days) at no cost, as long as the
        template hasn't been saved since.

        The request is validated as a render would be: an unknown template
        is a `404`, an invalid modification a `400`; keys that match
        nothing come back in `warnings`. The template can be one of the
        workspace's or a template-library template.

        Images (`png`, `jpeg`, `webp`) show one page: page 1, or the one
        page in `response.includePages`. A PDF has every page, or those in
        `includePages`. Videos, `async` and `webhookUrl` aren't available
        for signed URLs.

        The URL can't be changed without breaking its signature (HMAC-SHA256
        under a per-workspace secret): any edit answers `403`. Once
        `expiresIn` has passed it answers `410`. To revoke every signed URL
        at once, call `POST /signed-urls/rotate-key`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SignedUrlRequest' }
            examples:
              ogImage:
                summary: An Open Graph image, valid for 30 days
                value:
                  templateId: clx8m2k3p0001abcd1234efgh
                  modifications:
                    title: How we cut render times in half
                    author: Jane Doe
                    title.color: '#FFD400'
                  response: { format: png }
                  expiresIn: 2592000
      responses:
        '200':
          description: The signed URL. Nothing has been charged.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SignedUrlResponse' }
              examples:
                default:
                  value:
                    data:
                      url: https://api.jamframe.com/r/s/cJa3HMV6TZzf.zPcqxCsIwFAXQXwnXNcjTpi3JLJ2cKn5ASR5JbJpIEVIo_XdxcT2cHR8Y2KXqpktTISIKvrZbfvHW-xYSDHPptbo2ndIkscDsCDy5FDPDYOTseGUnauAsypszO8j_ONuSygqD0zDcFBEk5mhn_tEj-sxOPMc7juML.kDVEKgTbbJVl2AuLI64vRg.png
                      templateId: clx8m2k3p0001abcd1234efgh
                      format: png
                      expiresAt: '2026-12-09T15:01:30.000Z'
        '400':
          description: |
            Invalid request: see `ValidationError`, plus `mp4`, `async`,
            `webhookUrl` or `response.type` (not available for signed
            URLs), more than one page for an image, or a URL that would be
            too long (send fewer or shorter modifications).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              examples:
                video:
                  value: { error: VALIDATION_ERROR, message: 'Signed URLs render images and PDFs: "mp4" is not supported' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /signed-urls/rotate-key:
    post:
      tags: [Signed URLs]
      operationId: rotateSignedUrlKey
      summary: Revoke all signed URLs
      description: |
        Replaces the workspace's URL-signing secret. Every signed URL
        created before stops working at once (`403`); URLs created after
        use the new secret. Revoking an API key does not revoke the signed
        URLs it created: rotate the key for that.
      responses:
        '200':
          description: Rotated.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [rotatedAt]
                    properties:
                      rotatedAt: { type: string, format: date-time }
              examples:
                default:
                  value: { data: { rotatedAt: '2026-11-09T15:20:00.000Z' } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /designs:
    get:
      tags: [Designs]
      operationId: listDesigns
      summary: List designs
      description: |
        Returns the templates in the API key's workspace, newest first.
        Read-only: templates are authored in the web app. Use this to
        populate a template picker, then `GET /designs/{id}` for the
        parameters of the chosen one. With `source=library` it lists the
        template-library presets instead, which any workspace can render
        by id.

        `q` narrows the list to names containing the text, ignoring case,
        for a picker's search box; it works with either `source`. Each
        design reports its page count and whether it is `animated` (a
        video template), so a picker can show which ones to render as MP4.
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: source
          in: query
          required: false
          description: "`workspace` (default): the key's own designs. `library`: the template-library presets."
          schema:
            type: string
            enum: [workspace, library]
            default: workspace
        - name: q
          in: query
          required: false
          description: |
            Only designs whose name contains this text, ignoring case
            (`coffee` matches "Coffee tips carousel"). Leading and trailing
            spaces are ignored; empty means no filter. Longer than 100
            characters is a `400 VALIDATION_ERROR`.
          schema: { type: string, maxLength: 100 }
          example: coffee
      responses:
        '200':
          description: A page of designs.
          content:
            application/json:
              schema:
                type: object
                required: [designs, pagination]
                properties:
                  designs:
                    type: array
                    items: { $ref: '#/components/schemas/Design' }
                  pagination: { $ref: '#/components/schemas/Pagination' }
              examples:
                default:
                  value:
                    designs:
                      - id: clx8m2k3p0002abcd1234efgh
                        name: Coffee tips carousel
                        orientation: square
                        pages: 3
                        animated: false
                        createdAt: '2026-11-01T09:12:44.000Z'
                        updatedAt: '2026-11-05T16:03:10.000Z'
                      - id: clx8m2k3p0004abcd1234efgh
                        name: Coffee promo reel
                        orientation: portrait
                        pages: 2
                        animated: true
                        createdAt: '2026-10-28T11:40:02.000Z'
                        updatedAt: '2026-11-03T08:15:51.000Z'
                    pagination: { nextCursor: null, hasMore: false }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /designs/{id}:
    get:
      tags: [Designs]
      operationId: getDesign
      summary: Get a design and its parameters
      description: |
        Returns one template from the API key's workspace, or from the
        template library, with its page count and every parameter a render
        can set: layers with a parameter key, and `{{placeholders}}` used in
        text. Each parameter lists the pages it appears on and its current
        value in the template as an `example`.

        Returns `404 NOT_FOUND` when the template doesn't exist or belongs
        to another workspace.
      parameters:
        - in: path
          name: id
          required: true
          description: The design (template) id.
          schema: { type: string }
      responses:
        '200':
          description: The design.
          content:
            application/json:
              schema:
                type: object
                required: [design]
                properties:
                  design: { $ref: '#/components/schemas/DesignDetail' }
              examples:
                carousel:
                  value:
                    design:
                      id: clx8m2k3p0002abcd1234efgh
                      name: Coffee tips carousel
                      orientation: square
                      pages: 3
                      animated: false
                      createdAt: '2026-11-01T09:12:44.000Z'
                      updatedAt: '2026-11-05T16:03:10.000Z'
                      parameters:
                        - key: title
                          type: text
                          pages: [1, 2, 3]
                          example: 5 ways to brew better coffee
                        - key: photo
                          type: image
                          pages: [1]
                          example: https://example.com/images/beans.jpg
                        - key: brand
                          type: variable
                          pages: [1, 3]
                          example: Acme Coffee
                      sizes:
                        - id: story
                          name: Story / Reel
                          width: 1080
                          height: 1920
                        - id: landscape
                          name: Landscape 1.91:1
                          width: 1200
                          height: 630
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /designs/generate:
    post:
      tags: [AI]
      operationId: generateDesign
      summary: Generate a design with AI
      description: |
        The design agent designs a new template from a description and
        saves it in the API key's workspace: layout, sample copy, the
        workspace's brand kit (colours, fonts, logo from the brand library,
        unless `brand` says otherwise) and parameter keys on the layers a
        render will change (`title`, `photo`, `cta`…). Render it like any
        other design with `POST /render`.

        Costs its real AI cost plus half, **15 to 30 AI credits** per
        design (usually 15), refunded when the generation fails. A design usually takes 10–40 seconds: the call waits up to
        about 25 seconds and answers `201` with the design, or `202` with a
        job to poll at `GET /designs/generate/{jobId}` (the `Location`
        header). Send `"async": true` to get the `202` at once, and a
        `webhookUrl` to be called when the job ends instead of polling.

        On a development server without an AI key (`GET /ai/status` says
        `mock`), a scripted designer answers with a placeholder layout.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DesignGenerateRequest' }
            examples:
              post:
                summary: An Instagram post with the workspace's brand kit
                value:
                  prompt: Announce our summer sale, 30% off everything this weekend. Bold and playful.
                  size: instagram-portrait
              carousel:
                summary: A five-slide LinkedIn carousel with explicit brand colours
                value:
                  prompt: Five tips for running better remote meetings
                  size: linkedin-carousel
                  pages: 5
                  brand: { colors: ['#0b1f4d', '#ff6b5b'], fonts: [Poppins, Inter] }
              async:
                summary: Answer at once and poll
                value: { prompt: A teaser video for our app launch, size: instagram-story, video: true, async: true }
      responses:
        '201':
          description: The design is ready and saved.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: '#/components/schemas/DesignGenerateJob' }
              example:
                data:
                  jobId: cmw9uoeb9000binw52g648888
                  status: succeeded
                  message: A bold coral and navy sale post with a photo slot, the headline, a subline and a "Shop now" button.
                  changes: ['Page 1: background #fff7ed', 'Added image "Photo"', 'Added text "Headline"']
                  creditsCharged: 5
                  mock: false
                  createdAt: '2026-11-10T09:12:44.000Z'
                  finishedAt: '2026-11-10T09:13:02.000Z'
                  design:
                    id: clx8m2k3p0002abcd1234efgh
                    name: Announce our summer sale, 30% off everything
                    orientation: portrait
                    pages: 1
                    animated: false
                    createdAt: '2026-11-10T09:13:02.000Z'
                    updatedAt: '2026-11-10T09:13:02.000Z'
                    parameters:
                      - { key: photo, type: image, pages: [1], example: '' }
                      - { key: title, type: text, pages: [1], example: Summer sale }
                    sizes: []
                    editorUrl: https://app.jamframe.com/designs/clx8m2k3p0002abcd1234efgh/edit
        '202':
          description: Still designing (or `async` was set). Poll the job.
          headers:
            Location:
              description: The job's URL.
              schema: { type: string }
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [jobId, status]
                    properties:
                      jobId: { type: string }
                      status: { type: string, enum: [running] }
              example: { data: { jobId: cmw9uoeb9000binw52g648888, status: running } }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '502':
          description: The AI didn't produce a usable design (`AI_BAD_OUTPUT`) or the provider failed (`AI_UPSTREAM_ERROR`). No credits were charged; retrying is safe.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example: { error: AI_BAD_OUTPUT, message: "The AI didn't produce a design: try describing it differently" }
        '503':
          description: AI is not available on this server (`AI_UNAVAILABLE`). No credits were charged.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example: { error: AI_UNAVAILABLE, message: AI features are not available on this server, detail: { reason: no_key } }

  /designs/generate/{jobId}:
    get:
      tags: [AI]
      operationId: getDesignGenerateJob
      summary: Get a design generation job
      description: |
        A generation started by `POST /designs/generate`: `running`,
        `succeeded` (with the saved design) or `failed` (with the error
        envelope; failed generations are refunded). Poll every few seconds.
        Jobs of other workspaces answer `404`.
      parameters:
        - in: path
          name: jobId
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The job.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: '#/components/schemas/DesignGenerateJob' }
              examples:
                running:
                  value: { data: { jobId: cmw9uoeb9000binw52g648888, status: running, createdAt: '2026-11-10T09:12:44.000Z', finishedAt: null } }
                failed:
                  value:
                    data:
                      jobId: cmw9uoeb9000binw52g648888
                      status: failed
                      error: { error: AI_CREDITS_EXCEEDED, message: Your AI credits for this period are used up }
                      createdAt: '2026-11-10T09:12:44.000Z'
                      finishedAt: '2026-11-10T09:12:45.000Z'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /designs/import/figma:
    get:
      tags: [Figma import]
      operationId: getFigmaImportInfo
      summary: Check a key for the Figma plugin
      description: |
        The API key's workspace and organization, and the limits an import
        must respect. The Figma plugin calls it when connecting.
      responses:
        '200':
          description: The workspace and the limits.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FigmaImportInfo' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Figma import]
      operationId: importFigma
      summary: Import Figma frames as templates
      description: |
        Turns the Figma plugin's export (frames, layers bottom to top, and
        their image/SVG files) into a template of the key's workspace: one
        page per frame (`mode: pages`, default) or one template per frame
        (`mode: separate`). Layers named `{{key}}` or `#key` in Figma carry
        a `param` and become the template's parameters.

        Send `multipart/form-data` with a `document` field (the document as
        JSON) and one file part per asset, named after the asset's `id`; or
        `application/json` with the document itself and each asset's bytes
        as base64 `data` (bodies up to 5 MB).

        Files are checked by content (PNG, JPEG, GIF, WebP, or SVG under the
        brand library's rules) and stored in the brand library, tagged
        `figma` and the template's name. Fonts are matched to the built-in
        Google Fonts, the brand library, or Google Fonts (added to the
        library unless `options.importFonts` is false), else a fallback.
        Nothing is stored unless every file passes. Each new design sends a
        `design.created` webhook.

        Limits: 20 frames, 1,000 layers a frame (5,000 in all), 300 files,
        10 MB a raster image, 5 MB an SVG, 1 MB a thumbnail, 60 MB of files
        in all, 30 imports per workspace per 10 minutes.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [document]
              properties:
                document:
                  type: string
                  description: The `FigmaImportDocument` as JSON (at most 4 MB).
              additionalProperties:
                type: string
                format: binary
                description: One file per asset, the field named after the asset id.
          application/json:
            schema: { $ref: '#/components/schemas/FigmaImportDocument' }
      responses:
        '201':
          description: The template(s) created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FigmaImportResult' }
              examples:
                post:
                  value:
                    designs:
                      - id: clx8m2k3p0004abcd1234efgh
                        name: Summer sale post
                        orientation: portrait
                        createdAt: '2026-11-10T09:12:44.000Z'
                        updatedAt: '2026-11-10T09:12:44.000Z'
                        pages: 1
                        animated: false
                        editorUrl: https://app.jamframe.com/designs/clx8m2k3p0004abcd1234efgh/edit
                        parameters:
                          - { key: photo, type: image, pages: [1], example: 'https://cdn.jamframe.com/workspaces/ws/images/a1.png' }
                          - { key: headline, type: text, pages: [1], example: Summer Sale is here }
                    fonts:
                      - { family: Poppins, status: google, usedFamily: Poppins }
                      - { family: SF Pro Display, status: fallback, usedFamily: Inter, note: 'Not a Google Font and not in the brand library: drawn in Inter.' }
                    assets: { stored: 3, bytes: 245911 }
                    warnings:
                      - frame: Instagram post
                        layer: '{{headline}}'
                        message: 'Text with several styles kept its main style (Poppins Bold 88px #111827); colour of the rest flattened'
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '413':
          description: A file, the files together, or the request is over its cap.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example: { error: VALIDATION_ERROR, message: 'A file is larger than 10 MB (field "a1")' }
        '415':
          description: The body is neither `multipart/form-data` nor `application/json`.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /webhooks/subscriptions:
    get:
      tags: [Webhooks]
      operationId: listWebhookSubscriptions
      summary: List webhook subscriptions
      description: |
        Returns every webhook subscription in the API key's workspace,
        newest first.
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of subscriptions.
          content:
            application/json:
              schema:
                type: object
                required: [subscriptions, pagination]
                properties:
                  subscriptions:
                    type: array
                    items: { $ref: '#/components/schemas/WebhookSubscription' }
                  pagination: { $ref: '#/components/schemas/Pagination' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Webhooks]
      operationId: createWebhookSubscription
      summary: Subscribe to events
      description: |
        Register a URL to receive POSTs when the specified events happen
        in this workspace. The response includes a one-time
        `signingSecret`: store it immediately, it can't be recovered
        later. URL constraints:

        - Must be `https://` in production.
        - Must not resolve to a loopback, link-local, or private address
          (re-checked after DNS on every delivery to defeat rebinding).
        - At most 20 subscriptions per workspace.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookSubscriptionInput' }
            examples:
              zapier:
                summary: Zapier REST Hooks subscribe
                value:
                  url: https://hooks.zapier.com/hooks/catch/123/abcdef/
                  events:
                    - design.created
              allEvents:
                summary: Subscribe to every event type
                value:
                  url: https://example.com/jamframe-webhook
                  events:
                    - design.created
                    - design.updated
                    - design.deleted
                    - render.completed
                    - render.failed
                    - social.post.published
                    - social.post.failed
      responses:
        '201':
          description: Subscription created. `signingSecret` is shown ONCE.
          content:
            application/json:
              schema:
                type: object
                required: [subscription, signingSecret]
                properties:
                  subscription: { $ref: '#/components/schemas/WebhookSubscription' }
                  signingSecret:
                    type: string
                    description: |
                      Raw HMAC signing secret. Returned here exactly once;
                      the server keeps its own copy for signing outbound
                      requests but never reveals it again.
                    example: wh_sec_AbCdEfGh01234567890abcdefghijKLMN
        '400': { $ref: '#/components/responses/WebhookUrlInvalid' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/WebhookLimitReached' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /webhooks/subscriptions/{id}:
    get:
      tags: [Webhooks]
      operationId: getWebhookSubscription
      summary: Get a webhook subscription
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: The subscription.
          content:
            application/json:
              schema:
                type: object
                required: [subscription]
                properties:
                  subscription: { $ref: '#/components/schemas/WebhookSubscription' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    delete:
      tags: [Webhooks]
      operationId: deleteWebhookSubscription
      summary: Unsubscribe
      description: |
        Deletes the subscription. Used by Zapier and Make as the REST
        Hooks "unsubscribe" call; calling it directly has the same
        effect. Returns `204 No Content` on success.
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '204':
          description: Deleted.
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /webhooks/subscriptions/{id}/test:
    post:
      tags: [Webhooks]
      operationId: testWebhookSubscription
      summary: Send a sample event
      description: |
        Queues a sample delivery for the requested event type so you can
        check your endpoint and pull a sample payload. The delivery goes
        through the normal dispatcher: signature, headers and retries are
        the same as for a real event. The sample uses an obviously fake
        design id (`sample_design_id`).

        If `eventType` is omitted, the first event the subscription
        listens for is used. Returns `202 Accepted` once the delivery is
        queued; the outbound POST happens asynchronously.
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                eventType: { $ref: '#/components/schemas/WebhookEventType' }
            examples:
              default:
                value: { eventType: design.created }
      responses:
        '202':
          description: Delivery queued. The dispatcher will POST it shortly.
          content:
            application/json:
              schema:
                type: object
                required: [delivery, sample]
                properties:
                  delivery:
                    type: object
                    required: [id, eventType, createdAt]
                    properties:
                      id:
                        type: string
                        description: Delivery id, sent as `X-Webhook-Delivery`.
                      eventType: { $ref: '#/components/schemas/WebhookEventType' }
                      createdAt: { type: string, format: date-time }
                  sample: { $ref: '#/components/schemas/WebhookEvent' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /webhooks/subscriptions/{id}/rotate-secret:
    post:
      tags: [Webhooks]
      operationId: rotateWebhookSubscriptionSecret
      summary: Rotate the signing secret
      description: |
        Generates a new HMAC signing secret for this subscription and
        returns it. Update your verifier immediately: deliveries signed
        after this call use the new secret, and the old one stops working
        at once.
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Rotated. `signingSecret` is shown ONCE.
          content:
            application/json:
              schema:
                type: object
                required: [subscription, signingSecret]
                properties:
                  subscription: { $ref: '#/components/schemas/WebhookSubscription' }
                  signingSecret: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /social/accounts:
    get:
      tags: [Social]
      operationId: listSocialAccounts
      summary: List connected social accounts
      description: |
        The social accounts connected to the API key's workspace. Accounts
        are connected in the app (each platform's OAuth needs a browser).
        An account with `status: needs_reconnect` can't post until it is
        reconnected there; `sandbox` accounts (development servers without
        platform keys) simulate posting.
      responses:
        '200':
          description: The accounts.
          content:
            application/json:
              schema:
                type: object
                required: [accounts]
                properties:
                  accounts:
                    type: array
                    items: { $ref: '#/components/schemas/SocialAccount' }
              example:
                accounts:
                  - id: clx9a1b2c0001abcd1234efgh
                    platform: linkedin
                    platformName: LinkedIn
                    name: Ada Lovelace
                    username: null
                    avatarUrl: https://media.licdn.com/dms/image/sample.jpg
                    status: active
                    statusReason: null
                    sandbox: false
                    reconnectBy: '2027-01-08T10:00:00.000Z'
                    createdAt: '2026-11-09T10:00:00.000Z'
                    lastPostedAt: null
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /social/posts:
    post:
      tags: [Social]
      operationId: createSocialPost
      summary: Create a social post (render and post)
      description: |
        Post to one or more connected accounts, now, at `scheduledAt`, or
        as a draft. The media is one of:

        - `templateId` + `modifications` + `response`: the template is
          rendered (as `POST /render` would) when the post goes out, and the
          render is charged as usual. Several pages become a carousel where
          the platform has one; a `pdf` posts as a LinkedIn document.
        - `renderId`: the stored files of an earlier render.
        - `mediaUrls`: image, video or PDF URLs, downloaded once now.

        Every account is checked against its platform's limits first
        (formats, counts, sizes, aspect ratios, durations, caption length).
        If any account can't take the post, nothing is created and the
        answer lists the problems per account in `detail.targets`. Drafts
        are saved anyway, with the problems in `checks`.

        Publishing is asynchronous: each account (`targets[]`) goes
        `queued` → `rendering` → `publishing` → `published` or `failed` on
        its own; one platform failing never blocks the others. Poll
        `GET /social/posts/{id}`, or subscribe to the `social.post.published`
        and `social.post.failed` webhook events. Posting itself costs no
        credits.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SocialPostInput' }
            examples:
              renderAndPost:
                summary: Render a template and post it to three accounts
                value:
                  templateId: clx8m2k3p0004abcd1234efgh
                  modifications: { title: Spring sale, price: $29 }
                  response: { format: jpeg, includePages: [1, 2, 3] }
                  accounts:
                    - clx9a1b2c0001abcd1234efgh
                    - clx9a1b2c0002abcd1234efgh
                    - id: clx9a1b2c0003abcd1234efgh
                      options: { privacyLevel: SELF_ONLY }
                  caption: 'Spring sale starts today #sale'
                  captions: { x: Spring sale today. 30% off everything. }
                  options: { linkedin: { firstComment: 'Shop: https://example.com' } }
                  scheduledAt: '2026-11-10T09:00'
                  timezone: Europe/Paris
              existingRender:
                summary: Post an earlier render now
                value:
                  renderId: clx8n0q1r0009abcd1234efgh
                  accounts: [clx9a1b2c0001abcd1234efgh]
                  caption: New template, new look
      responses:
        '201':
          description: The post was created (and queued, scheduled or saved as a draft).
          headers:
            Location:
              description: '`/v1/social/posts/{id}`'
              schema: { type: string }
          content:
            application/json:
              schema:
                type: object
                required: [post, checks]
                properties:
                  post: { $ref: '#/components/schemas/SocialPost' }
                  checks:
                    type: array
                    description: Accounts with warnings (and, for drafts, the errors to fix before posting).
                    items: { $ref: '#/components/schemas/SocialTargetIssues' }
        '400':
          description: |
            Invalid request, or accounts that can't take this media.
            `detail.targets` lists every account's errors and warnings.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example:
                error: VALIDATION_ERROR
                message: 'Acme (Instagram): Instagram accepts JPEG images; the image is PNG. Render with format "jpeg".'
                detail:
                  targets:
                    - accountId: clx9a1b2c0001abcd1234efgh
                      platform: instagram
                      accountName: Acme
                      errors:
                        - level: error
                          code: image_format
                          message: 'Instagram accepts JPEG images; the image is PNG. Render with format "jpeg".'
                      warnings: []
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404':
          description: An unknown template, render or account in this workspace.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example:
                error: NOT_FOUND
                message: 'Unknown social account(s) in this workspace: clx9a1b2c0009abcd1234efgh'
                detail: { missing: [clx9a1b2c0009abcd1234efgh] }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503': { $ref: '#/components/responses/VideoUnavailable' }
    get:
      tags: [Social]
      operationId: listSocialPosts
      summary: List social posts
      description: Newest first, with every account's status.
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - in: query
          name: status
          description: |
            `queue` (scheduled or going out), `drafts`, `published` (fully
            or partly), `attention` (failed or partly failed), `canceled`,
            or a single post status.
          schema: { type: string }
      responses:
        '200':
          description: A page of posts.
          content:
            application/json:
              schema:
                type: object
                required: [posts, pagination]
                properties:
                  posts:
                    type: array
                    items: { $ref: '#/components/schemas/SocialPost' }
                  pagination: { $ref: '#/components/schemas/Pagination' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /social/posts/{id}:
    get:
      tags: [Social]
      operationId: getSocialPost
      summary: Get a social post
      parameters:
        - $ref: '#/components/parameters/SocialPostId'
      responses:
        '200':
          description: The post, with each account's status, permalink and error.
          content:
            application/json:
              schema:
                type: object
                required: [post]
                properties:
                  post: { $ref: '#/components/schemas/SocialPost' }
              example:
                post:
                  id: clx9p0s1t0001abcd1234efgh
                  status: partial
                  caption: 'Spring sale starts today #sale'
                  captions: {}
                  options: {}
                  media:
                    - kind: image
                      contentType: image/jpeg
                      url: https://cdn.jamframe.com/renders/ws_abc123/0b1c-p1.jpg?Expires=1794229500&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                      expiresAt: '2026-11-09T13:05:00.000Z'
                      bytes: 182044
                      width: 1080
                      height: 1350
                  mediaSource: { kind: render, templateId: clx8m2k3p0004abcd1234efgh, response: { format: jpeg } }
                  renderJobId: clx8n0q1r0008abcd1234efgh
                  renderId: clx8n0q1r0009abcd1234efgh
                  scheduledAt: null
                  timezone: null
                  source: api
                  error: null
                  createdAt: '2026-11-09T12:00:00.000Z'
                  updatedAt: '2026-11-09T12:00:09.000Z'
                  finishedAt: '2026-11-09T12:00:09.000Z'
                  targets:
                    - id: clx9t0a1b0001abcd1234efgh
                      accountId: clx9a1b2c0001abcd1234efgh
                      platform: linkedin
                      accountName: Acme
                      status: published
                      caption: 'Spring sale starts today #sale'
                      permalink: https://www.linkedin.com/feed/update/urn:li:share:7000000000000000000/
                      externalId: urn:li:share:7000000000000000000
                      error: null
                      warnings: []
                      attempts: 0
                      nextAttemptAt: null
                      publishedAt: '2026-11-09T12:00:07.000Z'
                    - id: clx9t0a1b0002abcd1234efgh
                      accountId: clx9a1b2c0002abcd1234efgh
                      platform: x
                      accountName: acme
                      status: failed
                      caption: 'Spring sale starts today #sale'
                      permalink: null
                      externalId: null
                      error: { kind: permanent, code: http_403, message: 'X: You are not permitted to perform this action.' }
                      warnings: []
                      attempts: 0
                      nextAttemptAt: null
                      publishedAt: null
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /social/posts/{id}/cancel:
    post:
      tags: [Social]
      operationId: cancelSocialPost
      summary: Cancel a social post
      description: |
        Cancels a draft, a scheduled or queued post, or the accounts of a
        publishing post that haven't started. Accounts that already posted
        keep their post. A render already running finishes (and is
        charged).
      parameters:
        - $ref: '#/components/parameters/SocialPostId'
      responses:
        '200':
          description: The post after canceling.
          content:
            application/json:
              schema:
                type: object
                required: [post]
                properties:
                  post: { $ref: '#/components/schemas/SocialPost' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: The post is already finished.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example: { error: CONFLICT, message: This post is already published }
        '429': { $ref: '#/components/responses/RateLimited' }

  /social/posts/{id}/retry:
    post:
      tags: [Social]
      operationId: retrySocialPost
      summary: Retry failed accounts of a post
      description: |
        Queues the failed accounts again (all of them, or `targetId`).
        When the render failed, it runs again (and is charged when it
        succeeds). An account that needs reconnecting must be reconnected
        in the app first.
      parameters:
        - $ref: '#/components/parameters/SocialPostId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                targetId: { type: string, description: One account target to retry. }
      responses:
        '200':
          description: The post, with the accounts queued again.
          content:
            application/json:
              schema:
                type: object
                required: [post]
                properties:
                  post: { $ref: '#/components/schemas/SocialPost' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: Nothing failed, or the account was removed or needs reconnecting.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example: { error: CONFLICT, message: 'Nothing to retry: no account of this post failed' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /social/analytics/overview:
    get:
      tags: [Social]
      operationId: getSocialAnalyticsOverview
      summary: Social analytics totals
      description: |
        What the workspace's posts gained in the range (impressions or
        views, reach, likes, comments, shares, saves, clicks and engagement),
        the same for the period of equal length just before, and the change
        in percent. Covers posts made through the API or the app and the
        accounts' recent posts imported when they connected. A metric is
        `null` when the platforms in scope don't report it, never a stand-in
        0; `available` lists the ones they do. Days are in the
        organization's analytics time zone; the range is limited to the
        plan's history (`range.limited`).
      parameters:
        - $ref: '#/components/parameters/AnalyticsFrom'
        - $ref: '#/components/parameters/AnalyticsTo'
        - $ref: '#/components/parameters/AnalyticsPlatform'
        - $ref: '#/components/parameters/AnalyticsAccountId'
      responses:
        '200':
          description: Totals for the range and the period before.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SocialAnalyticsOverview' }
              example:
                range: { from: '2026-10-14', to: '2026-11-10', days: 28, timezone: Europe/Paris, historyDays: 90, limited: false }
                previousRange: { from: '2026-09-16', to: '2026-10-13' }
                available: [impressions, reach, likes, comments, shares, saves, engagement]
                totals: { impressions: 48210, reach: 30122, likes: 2210, comments: 140, shares: 96, saves: 310, clicks: null, engagement: 2756 }
                previous: { impressions: 39870, reach: 25010, likes: 1905, comments: 120, shares: 70, saves: 260, clicks: null, engagement: 2355 }
                change: { impressions: 20.9, reach: 20.4, likes: 16, comments: 16.7, shares: 37.1, saves: 19.2, clicks: null, engagement: 17 }
                engagementRate: 5.72
                postsPublished: 12
                previousPostsPublished: 9
        '400': { $ref: '#/components/responses/AnalyticsBadQuery' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /social/analytics/daily:
    get:
      tags: [Social]
      operationId: getSocialAnalyticsDaily
      summary: Social analytics per day
      description: |
        One row per day of the range: what the workspace's posts gained that
        day (whenever they were published), and how many posts went out.
        A post's first numbers count on the day it was published.
      parameters:
        - $ref: '#/components/parameters/AnalyticsFrom'
        - $ref: '#/components/parameters/AnalyticsTo'
        - $ref: '#/components/parameters/AnalyticsPlatform'
        - $ref: '#/components/parameters/AnalyticsAccountId'
      responses:
        '200':
          description: The days of the range, oldest first.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SocialAnalyticsDaily' }
              example:
                range: { from: '2026-11-09', to: '2026-11-10', days: 2, timezone: UTC, historyDays: 90, limited: false }
                available: [impressions, likes, comments, shares, saves, engagement]
                days:
                  - { day: '2026-11-09', impressions: 1820, reach: null, likes: 96, comments: 7, shares: 4, saves: 11, clicks: null, engagement: 118, postsPublished: 1 }
                  - { day: '2026-11-10', impressions: 640, reach: null, likes: 31, comments: 2, shares: 1, saves: 3, clicks: null, engagement: 37, postsPublished: 0 }
        '400': { $ref: '#/components/responses/AnalyticsBadQuery' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /social/analytics/insights:
    get:
      tags: [Social]
      operationId: getSocialAnalyticsInsights
      summary: Social analytics insights
      description: |
        From the posts published in the range and their numbers so far: the
        5 top posts (by engagement, then impressions), the best weekday and
        hour to post (average engagement per post, from this workspace's own
        posts; a time needs 2 posts and the range 5 before one is called
        best), and a per-platform comparison.
      parameters:
        - $ref: '#/components/parameters/AnalyticsFrom'
        - $ref: '#/components/parameters/AnalyticsTo'
        - $ref: '#/components/parameters/AnalyticsPlatform'
        - $ref: '#/components/parameters/AnalyticsAccountId'
      responses:
        '200':
          description: Top posts, best times and platforms.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SocialAnalyticsInsights' }
        '400': { $ref: '#/components/responses/AnalyticsBadQuery' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /ai/status:
    get:
      tags: [AI]
      operationId: getAiStatus
      summary: AI availability, price list and AI credits
      description: |
        Whether AI features can run (`status`), the model each AI task uses,
        the AI credit price list, and the API key's organization's AI
        credits for the current billing period. Free to call.
      responses:
        '200':
          description: The AI status.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AiStatus' }
              example:
                status: live
                models:
                  design: anthropic/claude-sonnet-5.5
                  fast: anthropic/claude-haiku-5.5
                  vision: google/gemini-3.8-flash
                  image: google/gemini-nano-banana-2.1
                  imageEdit: google/gemini-nano-banana-2.1
                  background: openai/gpt-image-2.6-flare
                  tts: google/gemini-3.8-flash-tts
                  stt: openai/whisper-large-v3-turbo
                  video: google/veo-3.1-lite
                  embedding: openai/text-embedding-3-small
                prices:
                  - { operation: image, credits: 4, per: 1, unit: image, label: 'AI image, generated or edited, up to 1.5K' }
                  - { operation: tts, credits: 1, per: 500, unit: character, label: 'Voiceover, per 500 characters' }
                credits:
                  planCode: starter
                  used: 120
                  reserved: 0
                  limit: 500
                  remaining: 380
                  periodStart: '2026-11-01T00:00:00.000Z'
                  periodEnd: '2026-12-01T00:00:00.000Z'
                  active: true
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /images/remove-background:
    post:
      tags: [AI]
      operationId: removeImageBackground
      summary: Remove an image's background
      description: |
        Cuts the subject out of a picture and stores the result in the API
        key's workspace brand library as a transparent PNG; `url` is ready
        for `modifications` (an image layer's parameter).

        The cut-out runs on our servers with U²-Net (`method: local`): the
        original pixels are kept at full size and only an alpha channel is
        added, with edges refined against the picture and logos on flat
        colours keyed out completely. Costs **1 AI credit**, refunded when
        it fails. A server without the local model uses an image model
        instead (`method: model`, **8 AI credits**), which redraws the
        subject, so small text can change.

        Send JSON with the picture's `url` (http(s); PNG, JPEG, GIF or WebP
        up to 10 MB) or a multipart upload in `file`. Pictures larger than
        4096 px a side are cut out at 4096 px, and a PNG over 10 MB is made
        smaller to fit (`scaled: true`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url: { type: string, format: uri, description: The picture (http or https). }
                name: { type: string, maxLength: 120, description: 'Name for the new brand-library asset (default: "Image"), suffixed with "(no background)".' }
            example: { url: 'https://example.com/photos/product.jpg', name: Product shot }
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
                name: { type: string }
      responses:
        '200':
          description: The cut-out.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackgroundRemoval' }
              example:
                url: https://cdn.jamframe.com/workspaces/ws_123/images/as_456.png
                width: 2537
                height: 1897
                method: local
                model: u2net
                scaled: false
                creditsCharged: 1
                asset:
                  id: as_456
                  kind: image
                  name: Product shot (no background)
                  url: https://cdn.jamframe.com/workspaces/ws_123/images/as_456.png
                  mimeType: image/png
                  size: 3663403
                  createdAt: '2026-11-10T09:12:00.000Z'
                  tags: [ai, cutout]
                  meta: { width: 2537, height: 1897 }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503':
          description: Neither the local model nor an AI model is available on this server (`AI_UNAVAILABLE`, `detail.reason` `no_model`). No credits were charged.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example: { error: AI_UNAVAILABLE, message: 'Background removal is not set up on this server', detail: { reason: no_model } }

  /ai/transcribe:
    post:
      tags: [AI]
      operationId: transcribeMedia
      summary: Transcribe audio or video into subtitles
      description: |
        Transcribes the speech in an audio file or a video's soundtrack and
        splits it into subtitle cues: at most 2 lines of 42 characters,
        ending at sentence ends, pauses and commas, on screen 1–7 seconds
        (`style: short`: one line of up to 24 characters, for vertical
        social video). Returns the cues and the same as SRT and WebVTT:
        pass `cues` (or `srt`) as `modifications.subtitles` in an MP4
        render to burn them in.

        Costs **1 AI credit per minute** of audio transcribed, refunded when
        it fails. `start` and `duration` transcribe only a window of the
        file (seconds); `offset` moves the cues to where that window sits
        on your video's timeline. Files up to 100 MB and 2 hours.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TranscribeRequest' }
            example: { url: 'https://example.com/audio/voiceover.mp3', language: en }
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
                language: { type: string }
                style: { type: string, enum: [standard, short] }
                start: { type: number }
                duration: { type: number }
                offset: { type: number }
      responses:
        '200':
          description: The transcript as subtitle cues.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Transcription' }
              example:
                language: en
                duration: 6.4
                text: Meet Aurora One, our new wireless speaker. It fills any room.
                cues:
                  - { start: 0.4, end: 3.3, text: 'Meet Aurora One, our new wireless speaker.' }
                  - { start: 3.5, end: 5.2, text: 'It fills any room.' }
                srt: "1\n00:00:00,400 --> 00:00:03,300\nMeet Aurora One, our new wireless speaker.\n\n2\n00:00:03,500 --> 00:00:05,200\nIt fills any room.\n"
                vtt: "WEBVTT\n\n00:00:00.400 --> 00:00:03.300\nMeet Aurora One, our new wireless speaker.\n\n00:00:03.500 --> 00:00:05.200\nIt fills any room.\n"
                creditsCharged: 1
                model: openai/whisper-large-v3-turbo
                mock: false
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '502':
          description: The speech-to-text provider failed (`AI_UPSTREAM_ERROR`) or answered unusably (`AI_BAD_OUTPUT`). No credits were charged.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example: { error: AI_UPSTREAM_ERROR, message: 'The AI provider failed: try again' }
        '503':
          description: AI is not available on this server (`AI_UNAVAILABLE`). No credits were charged.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example: { error: AI_UNAVAILABLE, message: AI features are not available on this server, detail: { reason: no_key } }

  /r/s/{token}:
    servers:
      - url: https://api.jamframe.com
        description: Production
      - url: http://localhost:3100
        description: Local development
    get:
      tags: [Public URLs]
      operationId: openSignedUrl
      summary: Open a signed URL
      security: []
      description: |
        The URL returned by `POST /signed-urls`: `<kid>.<payload>.<sig>.<ext>`.
        Renders the signed request (or serves it from the render cache) and
        answers with the file. No authentication: the signature is the
        credential. A query string is ignored.

        Cache: within the URL's cache time, the same request is served from
        the stored file for free, and `If-None-Match` with the `ETag`
        answers `304`. `X-Render-Cache` says `HIT` or `MISS`.
        `Cache-Control: max-age` is the cache time but at most one day, so a
        key rotation reaches browsers and CDNs within a day.

        `HEAD` answers from the render cache only and never renders or
        charges: a cached request gets the headers a `GET` would, anything
        else `200` with `X-Render-Cache: MISS` and `Cache-Control: no-store`.
      parameters:
        - in: path
          name: token
          required: true
          description: The signed token, ending in `.png`, `.jpg`, `.webp` or `.pdf`.
          schema: { type: string, maxLength: 6000 }
      responses:
        '200': { $ref: '#/components/responses/RenderedFile' }
        '304':
          description: The `If-None-Match` ETag is current.
        '400': { $ref: '#/components/responses/PublicError' }
        '402': { $ref: '#/components/responses/PublicError' }
        '403': { $ref: '#/components/responses/PublicError' }
        '404': { $ref: '#/components/responses/PublicError' }
        '410': { $ref: '#/components/responses/PublicError' }
        '422': { $ref: '#/components/responses/PublicError' }
        '429': { $ref: '#/components/responses/PublicError' }
        '500': { $ref: '#/components/responses/PublicError' }
        '503': { $ref: '#/components/responses/PublicError' }

  /r/d/{file}:
    servers:
      - url: https://api.jamframe.com
        description: Production
      - url: http://localhost:3100
        description: Local development
    get:
      tags: [Public URLs]
      operationId: openDynamicUrl
      summary: Open a dynamic URL
      security: []
      description: |
        A template's dynamic URL, switched on in the app's Integrations, API
        & Forms dialog:
        `/r/d/<publicId>.<ext>?key=value&…`. Every query parameter is a
        modification, as in `POST /render` (`headline`, `page2@headline`,
        `headline.color`); values are URL-decoded. Names starting with `_`
        are reserved: `_page` picks the page of an image (default 1) or the
        pages of a PDF (`1,3`), `_scale` is 1, 2 or 3, `_size` is a Smart
        Resize target (a size id, a size name or `WIDTHxHEIGHT`); any other
        `_name` is ignored. At most 50 parameters, names up to 200 and values up to
        2000 characters, 8000 characters in all; a repeated name is a `400`.

        A render costs credits like any other (1 per image, or per PDF
        page) and counts toward the URL's credit cap. Within the URL's cache
        time (default 300 seconds) the same parameters are served from the
        stored file: free, not counted toward the cap, and still served
        once the cap is reached. Parameters that match nothing in the
        template don't change the cache key.

        When the cap is reached (`402 CREDIT_CAP_REACHED`, for parameters
        not in the cache), the URL is turned off (`410 URL_DISABLED`) or
        has expired (`410 URL_EXPIRED`), the answer is a JSON error, not an
        image. A new dynamic URL starts with a 100-credit cap (change or
        remove it in the app). `Cache-Control: max-age` is the cache
        time but at most one hour, so turning the URL off or making a new
        link reaches browsers and CDNs within the hour.

        Output size: at most 20 megapixels per page (width × height ×
        `_scale`²; `PUBLIC_RENDER_MAX_PIXELS` on self-hosted servers), a
        `400` above that. `HEAD` answers from the render cache only, as for
        signed URLs: it never renders or charges.
      parameters:
        - in: path
          name: file
          required: true
          description: The URL's public id and the format, e.g. `Q2x5a1RqZmVt0GZ4aWw.png` (`png`, `jpg`, `jpeg`, `webp` or `pdf`).
          schema: { type: string }
        - in: query
          name: modifications
          required: false
          style: form
          explode: true
          description: Any number of `key=value` pairs, each a modification.
          schema:
            type: object
            additionalProperties: { type: string }
          example: { headline: Hello world, headline.color: '#FF0000' }
      responses:
        '200': { $ref: '#/components/responses/RenderedFile' }
        '304':
          description: The `If-None-Match` ETag is current.
        '400': { $ref: '#/components/responses/PublicError' }
        '402': { $ref: '#/components/responses/PublicError' }
        '403': { $ref: '#/components/responses/PublicError' }
        '404': { $ref: '#/components/responses/PublicError' }
        '410': { $ref: '#/components/responses/PublicError' }
        '422': { $ref: '#/components/responses/PublicError' }
        '429': { $ref: '#/components/responses/PublicError' }
        '500': { $ref: '#/components/responses/PublicError' }
        '503': { $ref: '#/components/responses/PublicError' }

  /api/public/forms/{publicId}:
    servers:
      - url: https://app.jamframe.com
        description: Production (placeholder until the domain is final)
      - url: http://localhost:3100
        description: Local development
    get:
      tags: [Public forms]
      operationId: getPublicForm
      summary: Get a public form
      security: []
      description: |
        The form's visible fields, output and branding, and the template
        data its live preview draws: the output's pages at the output size,
        without editor-only layer fields (names, locks, animations), the
        placeholder values those pages use and the fonts. Nothing else of
        the template or its owner. A form at its credit cap still answers
        (`status: cap_reached`) so the page can say so.
      parameters:
        - $ref: '#/components/parameters/FormPublicId'
      responses:
        '200':
          description: The form.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PublicForm' }
        '403': { $ref: '#/components/responses/PublicFormFailure' }
        '404': { $ref: '#/components/responses/PublicFormFailure' }
        '410': { $ref: '#/components/responses/PublicFormFailure' }
        '429': { $ref: '#/components/responses/PublicFormFailure' }

  /api/public/forms/{publicId}/render:
    servers:
      - url: https://app.jamframe.com
        description: Production (placeholder until the domain is final)
      - url: http://localhost:3100
        description: Local development
    post:
      tags: [Public forms]
      operationId: renderPublicForm
      summary: Render a public form
      security: []
      description: |
        Render the template with the visitor's answers, keyed by field
        (`key` in `GET /api/public/forms/{publicId}`). Text is trimmed (line
        breaks kept only in long text), colours are `#rrggbb`, image and
        file fields take a public `https://` URL or, for upload fields, the
        `url` of an upload of this form. An empty optional answer keeps the
        template's value; keys that are not visible fields are ignored.

        Costs 1 credit per page rendered, charged to the form owner and
        counted toward the form's credit cap (in the same transaction, so
        concurrent submissions can't overshoot it). The same answers again
        within an hour are served from the render cache for free; the
        response doesn't say so (nor which render it was), so a visitor
        can't tell that someone else sent the same answers. Output size is
        capped at 20 megapixels per page like the other public renders. A
        body that isn't JSON is `400 INVALID_REQUEST`; one over 256 kB is
        `413 BODY_TOO_LARGE`.
      parameters:
        - $ref: '#/components/parameters/FormPublicId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PublicFormRenderRequest' }
            example:
              values: { headline: Grand opening, photo: 'https://example.com/shop.jpg' }
              turnstileToken: 0.AbC…
      responses:
        '200':
          description: The render's files.
          content:
            application/json:
              schema:
                type: object
                required: [render]
                properties:
                  render: { $ref: '#/components/schemas/PublicFormRender' }
        '400': { $ref: '#/components/responses/PublicFormFailure' }
        '402': { $ref: '#/components/responses/PublicFormFailure' }
        '403': { $ref: '#/components/responses/PublicFormFailure' }
        '404': { $ref: '#/components/responses/PublicFormFailure' }
        '410': { $ref: '#/components/responses/PublicFormFailure' }
        '413': { $ref: '#/components/responses/PublicFormFailure' }
        '415': { $ref: '#/components/responses/PublicFormFailure' }
        '422': { $ref: '#/components/responses/PublicFormFailure' }
        '429': { $ref: '#/components/responses/PublicFormFailure' }
        '500': { $ref: '#/components/responses/PublicFormFailure' }
        '503': { $ref: '#/components/responses/PublicFormFailure' }

  /api/public/forms/{publicId}/uploads:
    servers:
      - url: https://app.jamframe.com
        description: Production (placeholder until the domain is final)
      - url: http://localhost:3100
        description: Local development
    post:
      tags: [Public forms]
      operationId: uploadToPublicForm
      summary: Upload an image to a public form
      security: []
      description: |
        Upload an image for an upload field, then send its `url` as that
        field's answer. PNG, JPEG, WebP or GIF, decided from the file's
        bytes (SVG and anything else is refused), at most 10 MB, 10,000 px a
        side and 40 megapixels. Uploads are kept 24 hours, then deleted;
        they never appear in the owner's brand library.

        Accepted only while the form could render (on, unexpired, room under
        its credit cap for one more render, credits left in the owner's
        account; `402` otherwise), and with a bot check: a Turnstile token
        in `X-Turnstile-Token`, which earns an `uploadPass` in the response,
        or that pass in `X-Upload-Pass` for the visit's next uploads (10
        within 30 minutes). At most 500 live uploads per form.
      parameters:
        - $ref: '#/components/parameters/FormPublicId'
        - in: query
          name: field
          required: true
          description: The key of an upload field of the form.
          schema: { type: string }
        - in: header
          name: X-Turnstile-Token
          required: false
          description: A Turnstile token, when there is no upload pass yet (or it ran out).
          schema: { type: string }
        - in: header
          name: X-Upload-Pass
          required: false
          description: The `uploadPass.pass` an earlier upload of this visit returned.
          schema: { type: string }
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
      responses:
        '200':
          description: The stored upload.
          content:
            application/json:
              schema:
                type: object
                required: [upload]
                properties:
                  upload: { $ref: '#/components/schemas/PublicFormUpload' }
                  uploadPass:
                    type: object
                    required: [pass, expiresAt]
                    description: Only when this upload spent a Turnstile token. Send `pass` as `X-Upload-Pass` with the visit's next uploads.
                    properties:
                      pass: { type: string }
                      expiresAt: { type: string, format: date-time }
        '400': { $ref: '#/components/responses/PublicFormFailure' }
        '402': { $ref: '#/components/responses/PublicFormFailure' }
        '403': { $ref: '#/components/responses/PublicFormFailure' }
        '404': { $ref: '#/components/responses/PublicFormFailure' }
        '410': { $ref: '#/components/responses/PublicFormFailure' }
        '413': { $ref: '#/components/responses/PublicFormFailure' }
        '429': { $ref: '#/components/responses/PublicFormFailure' }
        '503': { $ref: '#/components/responses/PublicFormFailure' }

  /api/public/forms/{publicId}/files/{handle}:
    servers:
      - url: https://app.jamframe.com
        description: Production (placeholder until the domain is final)
      - url: http://localhost:3100
        description: Local development
    get:
      tags: [Public forms]
      operationId: getPublicFormFile
      summary: Get a public form's result file
      security: []
      description: |
        A file of a render made through this form, by the handle in its
        `url` / `downloadUrl` (render response). Shown inline; with
        `download=1`, as an attachment named after the form. Handles are
        opaque, made afresh for each response and only valid on this form.
        Files are deleted 7 days after the render (`410 FILE_EXPIRED`).
      parameters:
        - $ref: '#/components/parameters/FormPublicId'
        - in: path
          name: handle
          required: true
          schema: { type: string }
        - in: query
          name: download
          required: false
          description: '`1`: `Content-Disposition: attachment`.'
          schema: { type: string, enum: ['1'] }
      responses:
        '200':
          description: The file.
          headers:
            Content-Disposition:
              description: '`inline` (or `attachment` with `download=1`) and a file name from the form''s title.'
              schema: { type: string }
            Cache-Control:
              description: '`private, max-age=3600`.'
              schema: { type: string }
          content:
            image/png:
              schema: { type: string, format: binary }
            image/jpeg:
              schema: { type: string, format: binary }
            image/webp:
              schema: { type: string, format: binary }
            application/pdf:
              schema: { type: string, format: binary }
        '403': { $ref: '#/components/responses/PublicFormFailure' }
        '404': { $ref: '#/components/responses/PublicFormFailure' }
        '410': { $ref: '#/components/responses/PublicFormFailure' }
        '429': { $ref: '#/components/responses/PublicFormFailure' }

  /workflows:
    get:
      tags: [Workflows]
      operationId: listWorkflows
      summary: List workflows
      description: The workspace's workflows, most recently changed first (at most 200).
      responses:
        '200':
          description: The workflows.
          content:
            application/json:
              schema:
                type: object
                required: [workflows]
                properties:
                  workflows:
                    type: array
                    items: { $ref: '#/components/schemas/Workflow' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Workflows]
      operationId: createWorkflow
      summary: Create a workflow
      description: |
        Creates a draft from a `definition`, from an Explore `starter`, or
        a blank 4-step draft when neither is sent. The definition's shape is
        checked; what it still needs before it can run is listed in
        `problems`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WorkflowCreate' }
            example:
              name: Quote cards
              definition:
                version: 1
                trigger: { kind: manual }
                source: { kind: file_url, url: 'https://example.com/quotes.csv' }
                transforms: [{ kind: dedupe, column: Quote }]
                action: { kind: render, templateId: cmw936lao0000hgw5xnjex7g5, mapping: { quote: '{{Quote}}', author: '{{Author}}' } }
                deliver: [{ kind: webhook, url: 'https://hooks.example.com/cards' }]
      responses:
        '201':
          description: The new workflow (a draft).
          headers:
            Location:
              schema: { type: string }
          content:
            application/json:
              schema:
                type: object
                required: [workflow]
                properties:
                  workflow: { $ref: '#/components/schemas/Workflow' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /workflows/{id}:
    parameters:
      - $ref: '#/components/parameters/WorkflowId'
    get:
      tags: [Workflows]
      operationId: getWorkflow
      summary: Get a workflow
      responses:
        '200':
          description: The workflow.
          content:
            application/json:
              schema:
                type: object
                required: [workflow]
                properties:
                  workflow: { $ref: '#/components/schemas/Workflow' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    patch:
      tags: [Workflows]
      operationId: updateWorkflow
      summary: Change a workflow
      description: |
        Fields sent replace the old ones. `status: active` needs a complete
        definition whose template, social accounts and Google accounts
        exist in the workspace; otherwise 400 with `detail.problems`.
        Activating a scheduled workflow sets `nextRunAt`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WorkflowUpdate' }
            example: { status: active }
      responses:
        '200':
          description: The workflow after the change.
          content:
            application/json:
              schema:
                type: object
                required: [workflow]
                properties:
                  workflow: { $ref: '#/components/schemas/Workflow' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    delete:
      tags: [Workflows]
      operationId: deleteWorkflow
      summary: Delete a workflow
      description: Deletes the workflow and its run history. Renders and posts it made stay.
      responses:
        '204': { description: Deleted. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /workflows/{id}/run:
    parameters:
      - $ref: '#/components/parameters/WorkflowId'
    post:
      tags: [Workflows]
      operationId: runWorkflow
      summary: Run a workflow
      description: |
        Queues a run now (drafts included). Each row renders the template
        (render credits) and goes to the deliveries. Answers 202 with the
        run; poll `GET /workflows/{id}/runs/{runId}`. Refused with 402 when
        the plan's runs this month or the render credits are used up, and
        with `503 VIDEO_UNAVAILABLE` when the workflow renders MP4 and
        video rendering is turned off.
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WorkflowRunRequest' }
            example: { maxRows: 1 }
      responses:
        '202':
          description: The queued run.
          headers:
            Location:
              schema: { type: string }
          content:
            application/json:
              schema:
                type: object
                required: [run]
                properties:
                  run: { $ref: '#/components/schemas/WorkflowRun' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503': { $ref: '#/components/responses/VideoUnavailable' }

  /workflows/{id}/webhook-token:
    parameters:
      - $ref: '#/components/parameters/WorkflowId'
    post:
      tags: [Workflows]
      operationId: rotateWorkflowWebhook
      summary: Get a new incoming webhook URL
      description: For workflows with the incoming webhook trigger. The old URL stops working at once.
      responses:
        '200':
          description: The new URL.
          content:
            application/json:
              schema:
                type: object
                required: [webhookUrl]
                properties:
                  webhookUrl: { type: string, format: uri }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /workflows/{id}/runs:
    parameters:
      - $ref: '#/components/parameters/WorkflowId'
    get:
      tags: [Workflows]
      operationId: listWorkflowRuns
      summary: List a workflow's runs
      description: Newest first.
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of runs.
          content:
            application/json:
              schema:
                type: object
                required: [runs, pagination]
                properties:
                  runs:
                    type: array
                    items: { $ref: '#/components/schemas/WorkflowRun' }
                  pagination: { $ref: '#/components/schemas/Pagination' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /workflows/{id}/runs/{runId}:
    parameters:
      - $ref: '#/components/parameters/WorkflowId'
      - $ref: '#/components/parameters/WorkflowRunId'
    get:
      tags: [Workflows]
      operationId: getWorkflowRun
      summary: Get a run with each row's result
      responses:
        '200':
          description: The run and its rows (at most 1,000).
          content:
            application/json:
              schema:
                type: object
                required: [run]
                properties:
                  run:
                    allOf:
                      - $ref: '#/components/schemas/WorkflowRun'
                      - type: object
                        required: [rows]
                        properties:
                          rows:
                            type: array
                            items: { $ref: '#/components/schemas/WorkflowRunRow' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /workflows/{id}/runs/{runId}/cancel:
    parameters:
      - $ref: '#/components/parameters/WorkflowId'
      - $ref: '#/components/parameters/WorkflowRunId'
    post:
      tags: [Workflows]
      operationId: cancelWorkflowRun
      summary: Cancel a run
      description: Cancels a queued or running run. Rows not started yet are skipped; the row in progress finishes.
      responses:
        '200':
          description: The run after canceling.
          content:
            application/json:
              schema:
                type: object
                required: [run]
                properties:
                  run: { $ref: '#/components/schemas/WorkflowRun' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: The run already finished.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
              example: { error: CONFLICT, message: The run already finished (succeeded) }
        '429': { $ref: '#/components/responses/RateLimited' }

webhooks:
  designEvent:
    post:
      tags: [Webhooks]
      operationId: onDesignEvent
      summary: Design event delivery
      description: |
        What JamFrame POSTs to a subscription's URL when a subscribed
        `design.*` event happens (`data` is a `Design`). Respond with any
        2xx within 10 seconds; anything else is retried (see "Outbound
        webhooks" in the introduction).
      security: []
      parameters:
        - in: header
          name: X-Webhook-Event
          required: true
          description: The event type.
          schema: { $ref: '#/components/schemas/WebhookEventType' }
        - in: header
          name: X-Webhook-Delivery
          required: true
          description: Delivery id, unchanged across retries. Use it to deduplicate.
          schema: { type: string }
        - in: header
          name: X-Webhook-Timestamp
          required: true
          description: Unix seconds when this attempt was signed.
          schema: { type: string }
        - in: header
          name: X-Webhook-Signature
          required: true
          description: '`t=<unixSeconds>,v1=<hex HMAC-SHA256 of "${t}.${rawBody}">`'
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookEvent' }
      responses:
        '200':
          description: Any 2xx acknowledges the delivery.
        '410':
          description: Gone. JamFrame deletes the subscription and stops delivering.
  renderEvent:
    post:
      tags: [Webhooks]
      operationId: onRenderEvent
      summary: Render job event delivery
      description: |
        What JamFrame POSTs to a subscription's URL when a render job in
        the workspace ends: `render.completed` or `render.failed`, with the
        render job as `data`. Signed, retried and deduplicated exactly like
        design events. Synchronous image and PDF renders don't send events.

        The job's file links are signed when the event is sent and work for
        the render's `expiresIn` (default 5 minutes) from then. A delivery
        retried after that carries links that no longer work: fetch the job
        (`GET /render-jobs/{id}`) for fresh ones.
      security: []
      parameters:
        - in: header
          name: X-Webhook-Event
          required: true
          description: '`render.completed` or `render.failed`.'
          schema: { $ref: '#/components/schemas/WebhookEventType' }
        - in: header
          name: X-Webhook-Delivery
          required: true
          description: Delivery id, unchanged across retries. Use it to deduplicate.
          schema: { type: string }
        - in: header
          name: X-Webhook-Timestamp
          required: true
          description: Unix seconds when this attempt was signed.
          schema: { type: string }
        - in: header
          name: X-Webhook-Signature
          required: true
          description: '`t=<unixSeconds>,v1=<hex HMAC-SHA256 of "${t}.${rawBody}">`'
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookEvent' }
            example:
              id: whe_sAYiZY7DgQIEBq1zO8tip_np
              type: render.completed
              createdAt: '2026-11-09T12:38:50.201Z'
              data:
                id: clx8n0q1r0008abcd1234efgh
                status: succeeded
                progress: 1
                format: mp4
                templateId: clx8m2k3p0004abcd1234efgh
                createdAt: '2026-11-09T12:38:36.161Z'
                startedAt: '2026-11-09T12:38:36.165Z'
                finishedAt: '2026-11-09T12:38:50.188Z'
                result:
                  content: https://cdn.jamframe.com/renders/ws_abc123/c724edf3-728c-4b57-8c31-4c2c0348ae6d.mp4?Expires=1794228230&Key-Pair-Id=K2JCJMDEHXQW5F&Signature=Yq0nRZ3x~Gd5WQ__
                  expiresAt: '2026-11-09T12:43:50.000Z'
                  type: url
                  format: mp4
                  pages: [1, 2]
                  credits: 13
                  renderId: clx8n0q1r0009abcd1234efgh
                  responseTime: 14023
                  duration: 13
                error: null
      responses:
        '200':
          description: Any 2xx acknowledges the delivery.
        '410':
          description: Gone. JamFrame deletes the subscription and stops delivering.
  socialEvent:
    post:
      tags: [Webhooks]
      operationId: onSocialEvent
      summary: Social post event delivery
      description: |
        What JamFrame POSTs to a subscription's URL each time one account
        of a social post finishes: `social.post.published` (with its
        permalink) or `social.post.failed` (after retries, with the
        reason). `data` carries the whole post and that account's target.
        Signed, retried and deduplicated like the other events.
      security: []
      parameters:
        - in: header
          name: X-Webhook-Event
          required: true
          description: '`social.post.published` or `social.post.failed`.'
          schema: { $ref: '#/components/schemas/WebhookEventType' }
        - in: header
          name: X-Webhook-Delivery
          required: true
          description: Delivery id, unchanged across retries. Use it to deduplicate.
          schema: { type: string }
        - in: header
          name: X-Webhook-Timestamp
          required: true
          description: Unix seconds when this attempt was signed.
          schema: { type: string }
        - in: header
          name: X-Webhook-Signature
          required: true
          description: '`t=<unixSeconds>,v1=<hex HMAC-SHA256 of "${t}.${rawBody}">`'
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookEvent' }
      responses:
        '200':
          description: Any 2xx acknowledges the delivery.
        '410':
          description: Gone. JamFrame deletes the subscription and stops delivering.
  workflowEvent:
    post:
      tags: [Webhooks]
      operationId: onWorkflowEvent
      summary: Workflow run event delivery
      description: |
        What JamFrame POSTs to a subscription's URL when a workflow run
        ends: `workflow.run.completed` (it succeeded, or some rows failed:
        see `status`) or `workflow.run.failed`. `data` is the run summary
        (`WorkflowRunEvent`). Signed, retried and deduplicated like the
        other events.
      security: []
      parameters:
        - in: header
          name: X-Webhook-Event
          required: true
          description: The event type.
          schema: { $ref: '#/components/schemas/WebhookEventType' }
        - in: header
          name: X-Webhook-Delivery
          required: true
          description: Delivery id, unchanged across retries. Use it to deduplicate.
          schema: { type: string }
        - in: header
          name: X-Webhook-Timestamp
          required: true
          description: Unix seconds when this attempt was signed.
          schema: { type: string }
        - in: header
          name: X-Webhook-Signature
          required: true
          description: '`t=<unixSeconds>,v1=<hex HMAC-SHA256 of "${t}.${rawBody}">`'
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookEvent' }
      responses:
        '200':
          description: Any 2xx acknowledges the delivery.
        '410':
          description: Gone. JamFrame deletes the subscription and stops delivering.
  renderJobCallback:
    post:
      tags: [Render]
      operationId: onRenderJobCallback
      summary: Render job callback (webhookUrl)
      description: |
        What JamFrame POSTs to a render request's `webhookUrl` when its
        job ends. Respond with any 2xx within 10 seconds. A network error,
        timeout, 408, 429 or 5xx is retried twice (after 5 and 30 seconds);
        other answers are final. The job's file links are signed when the
        job ends and work for the request's `expiresIn` from then.

        The callback is **not signed** (a per-request URL has no shared
        secret). Treat it as a hint: to trust the result, fetch the job with
        your API key (`GET /render-jobs/{id}`), or put an unguessable token
        in the `webhookUrl`.
      security: []
      parameters:
        - in: header
          name: X-Webhook-Event
          required: true
          description: '`render.completed` or `render.failed`, as in the body.'
          schema: { type: string, enum: [render.completed, render.failed] }
        - in: header
          name: X-Render-Job
          required: true
          description: The render job id.
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RenderJobCallback' }
      responses:
        '200':
          description: Any 2xx acknowledges the callback.
  designGenerateCallback:
    post:
      tags: [AI]
      operationId: onDesignGenerateCallback
      summary: AI design job callback (webhookUrl)
      description: |
        What JamFrame POSTs to a `POST /designs/generate` request's
        `webhookUrl` when its job ends. Same rules as the render job
        callback: respond with any 2xx within 10 seconds; a network error,
        timeout, 408, 429 or 5xx is retried twice (after 5 and 30 seconds).

        The callback is **not signed**. To trust the result, fetch the job
        with your API key (`GET /designs/generate/{jobId}`).
      security: []
      parameters:
        - in: header
          name: X-Webhook-Event
          required: true
          description: '`design.generate.completed` or `design.generate.failed`, as in the body.'
          schema: { type: string, enum: [design.generate.completed, design.generate.failed] }
        - in: header
          name: X-Design-Job
          required: true
          description: The job id.
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DesignGenerateCallback' }
      responses:
        '200':
          description: Any 2xx acknowledges the callback.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: jf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      description: Bearer API key created on the web app's API Keys page.

  parameters:
    AnalyticsFrom:
      name: from
      in: query
      required: false
      description: First day of the range (YYYY-MM-DD, in the organization's analytics time zone). Default 27 days before `to`.
      schema: { type: string, format: date, example: '2026-10-14' }
    AnalyticsTo:
      name: to
      in: query
      required: false
      description: Last day of the range, included. Default today. A range is at most 366 days.
      schema: { type: string, format: date, example: '2026-11-10' }
    AnalyticsPlatform:
      name: platform
      in: query
      required: false
      description: Only these platforms, comma-separated (or the parameter repeated).
      schema: { type: string, example: 'instagram,x' }
    AnalyticsAccountId:
      name: accountId
      in: query
      required: false
      description: Only these accounts (ids from `GET /social/accounts`), comma-separated (or repeated).
      schema: { type: string }
    FormPublicId:
      in: path
      name: publicId
      required: true
      description: The form's public id (the last part of its `/f/<publicId>` link).
      schema: { type: string, pattern: '^[A-Za-z0-9_-]{16,64}$' }
    Cursor:
      in: query
      name: cursor
      schema: { type: string }
      description: |
        Opaque cursor returned in the previous response's
        `pagination.nextCursor`. Omit to start from the first page.
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
      description: Page size (clamped to 100).
    SubscriptionId:
      in: path
      name: id
      required: true
      description: The webhook subscription id.
      schema: { type: string }

    SocialPostId:
      in: path
      name: id
      required: true
      description: A social post id.
      schema: { type: string, maxLength: 64 }
    WorkflowId:
      name: id
      in: path
      required: true
      description: The workflow's id.
      schema: { type: string, maxLength: 64 }
    WorkflowRunId:
      name: runId
      in: path
      required: true
      description: The run's id.
      schema: { type: string, maxLength: 64 }
  schemas:
    SocialMetricValues:
      type: object
      description: |
        Metrics; `null` when the platform doesn't report one. `impressions`
        holds impressions or views, whichever the platform reports;
        `engagement` is likes + comments + shares + saves of those known.
      required: [impressions, reach, likes, comments, shares, saves, clicks, engagement]
      properties:
        impressions: { type: [number, 'null'] }
        reach: { type: [number, 'null'] }
        likes: { type: [number, 'null'] }
        comments: { type: [number, 'null'] }
        shares: { type: [number, 'null'] }
        saves: { type: [number, 'null'] }
        clicks: { type: [number, 'null'] }
        engagement: { type: [number, 'null'] }
    SocialMetricName:
      type: string
      enum: [impressions, reach, likes, comments, shares, saves, clicks, engagement]
    SocialAnalyticsRange:
      type: object
      required: [from, to, days, timezone, historyDays, limited]
      properties:
        from: { type: string, format: date }
        to: { type: string, format: date }
        days: { type: integer }
        timezone: { type: string, description: 'The organization''s analytics time zone (UTC when unset).' }
        historyDays: { type: integer, description: 'Days of history the plan keeps.' }
        limited: { type: boolean, description: 'The range asked for started before the plan''s history; `from` was moved up.' }
    SocialAnalyticsOverview:
      type: object
      required: [range, previousRange, available, totals, previous, change, engagementRate, postsPublished, previousPostsPublished]
      properties:
        range: { $ref: '#/components/schemas/SocialAnalyticsRange' }
        previousRange:
          type: object
          required: [from, to]
          properties:
            from: { type: string, format: date }
            to: { type: string, format: date }
        available:
          type: array
          description: The metrics the platforms in scope report.
          items: { $ref: '#/components/schemas/SocialMetricName' }
        totals: { $ref: '#/components/schemas/SocialMetricValues' }
        previous: { $ref: '#/components/schemas/SocialMetricValues' }
        change:
          description: Percent change from `previous` to `totals`; null when there is no earlier number.
          allOf: [{ $ref: '#/components/schemas/SocialMetricValues' }]
        engagementRate: { type: [number, 'null'], description: 'Engagement ÷ impressions, in percent.' }
        postsPublished: { type: integer }
        previousPostsPublished: { type: integer }
    SocialAnalyticsDaily:
      type: object
      required: [range, available, days]
      properties:
        range: { $ref: '#/components/schemas/SocialAnalyticsRange' }
        available:
          type: array
          items: { $ref: '#/components/schemas/SocialMetricName' }
        days:
          type: array
          items:
            allOf:
              - { $ref: '#/components/schemas/SocialMetricValues' }
              - type: object
                required: [day, postsPublished]
                properties:
                  day: { type: string, format: date }
                  postsPublished: { type: integer }
    SocialPostMetrics:
      type: object
      description: One post on one account and its lifetime numbers so far.
      required: [id, accountId, accountName, platform, externalId, origin, caption, publishedAt, metrics, status]
      properties:
        id: { type: string }
        accountId: { type: string }
        accountName: { type: string }
        platform: { $ref: '#/components/schemas/SocialPlatform' }
        platformName: { type: string }
        externalId: { type: string, description: 'The platform''s post id.' }
        postId: { type: [string, 'null'], description: 'The post (`GET /social/posts/{id}`) when it was made here.' }
        origin: { type: string, enum: [app, imported] }
        permalink: { type: [string, 'null'] }
        caption: { type: string }
        mediaType: { type: [string, 'null'], example: image }
        thumbnailUrl: { type: [string, 'null'] }
        publishedAt: { type: string, format: date-time }
        metrics: { $ref: '#/components/schemas/SocialMetricValues' }
        engagementRate: { type: [number, 'null'] }
        status:
          type: string
          enum: [active, done, unavailable, gone]
          description: '`done`: past 90 days, no longer refreshed; `unavailable`: the platform gives no numbers for it (`statusReason`); `gone`: deleted at the platform.'
        statusReason: { type: [string, 'null'] }
        lastFetchedAt: { type: [string, 'null'], format: date-time }
    SocialAnalyticsInsights:
      type: object
      required: [range, topPosts, bestTimes, platforms]
      properties:
        range: { $ref: '#/components/schemas/SocialAnalyticsRange' }
        topPosts:
          type: array
          items: { $ref: '#/components/schemas/SocialPostMetrics' }
        bestTimes:
          type: object
          required: [basedOnPosts, enoughData, metric, timezone, weekdays, hours, bestWeekday, bestHour]
          properties:
            basedOnPosts: { type: integer }
            enoughData: { type: boolean, description: 'At least 5 posts with numbers.' }
            metric: { type: string, enum: [engagement, impressions] }
            timezone: { type: string }
            weekdays:
              type: array
              description: Sunday (0) to Saturday (6).
              items:
                type: object
                properties:
                  weekday: { type: integer }
                  name: { type: string }
                  posts: { type: integer }
                  average: { type: [number, 'null'] }
            hours:
              type: array
              description: 0 to 23.
              items:
                type: object
                properties:
                  hour: { type: integer }
                  posts: { type: integer }
                  average: { type: [number, 'null'] }
            bestWeekday:
              type: [object, 'null']
              properties:
                weekday: { type: integer }
                name: { type: string }
            bestHour: { type: [integer, 'null'] }
        platforms:
          type: array
          items:
            type: object
            properties:
              platform: { $ref: '#/components/schemas/SocialPlatform' }
              platformName: { type: string }
              posts: { type: integer }
              totals: { $ref: '#/components/schemas/SocialMetricValues' }
              averages: { $ref: '#/components/schemas/SocialMetricValues' }
              engagementRate: { type: [number, 'null'] }
    ApiError:
      type: object
      required: [error, message]
      properties:
        error:
          type: string
          description: |
            Stable, machine-readable error code. `INVALID_REQUEST` (400) is a
            body that isn't valid JSON, `BODY_TOO_LARGE` (413) a body over
            5 MB, and `UNSUPPORTED_MEDIA_TYPE` (415) a body in a charset or
            encoding the API can't read.
          enum:
            - MISSING_API_KEY
            - INVALID_API_KEY
            - EXPIRED_API_KEY
            - ORG_ON_HOLD
            - ORG_SUSPENDED
            - RATE_LIMITED
            - VALIDATION_ERROR
            - INVALID_REQUEST
            - BODY_TOO_LARGE
            - UNSUPPORTED_MEDIA_TYPE
            - NOT_FOUND
            - CONFLICT
            - QUOTA_EXCEEDED
            - WORKSPACE_QUOTA_EXCEEDED
            - PLAN_LIMIT_EXCEEDED
            - WEBHOOK_URL_INVALID
            - WEBHOOK_LIMIT_REACHED
            - VIDEO_UNAVAILABLE
            - AI_UNAVAILABLE
            - AI_CONTENT_REFUSED
            - AI_TIMEOUT
            - AI_RATE_LIMITED
            - AI_BAD_OUTPUT
            - AI_BAD_REQUEST
            - AI_UPSTREAM_ERROR
            - AI_CREDITS_EXCEEDED
            - INTERNAL
        message:
          type: string
          description: Human-readable error message, safe to show to end users.
        detail:
          type: object
          description: Optional structured context (varies by error code).
          additionalProperties: true

    AuthResult:
      type: object
      required: [username]
      properties:
        workspaceId:
          type: string
          description: |
            Stable identifier of the workspace the API key is bound to.
            Suitable as a connection UID for integration platforms
            (e.g. Make) since it doesn't change when the owner is renamed.
        username:
          type: string
          description: |
            Display name of the organization owner. Falls back to the
            owner's email when no name is set. Safe to show as a Zapier
            connection label.

    AiStatus:
      type: object
      required: [status, models, prices, credits]
      properties:
        status:
          type: string
          enum: [live, mock, off]
          description: |
            `live`: AI runs. `mock`: a development server without an AI key
            answers with placeholder output (no cost). `off`: AI features
            answer `503 AI_UNAVAILABLE`.
        models:
          type: object
          description: The model slug each AI task uses (design, fast, vision, image, imageEdit, background, tts, stt, video, embedding).
          additionalProperties: { type: string }
        prices:
          type: array
          description: The AI credit price list. An operation costs `credits` per started block of `per` units.
          items:
            type: object
            required: [operation, credits, per, unit, label]
            properties:
              operation:
                type: string
                enum: [text, design, vision, image, image_hd, background_local, background_model, tts, stt, video, embedding]
              credits: { type: integer }
              per: { type: integer }
              unit:
                type: string
                enum: [word, call, image, character, second, input]
              label: { type: string }
        credits:
          type: object
          description: The organization's AI credits for the current billing period.
          required: [planCode, used, reserved, limit, remaining, periodStart, periodEnd, active]
          properties:
            planCode: { type: string }
            used:
              type: integer
              description: Credits charged this period.
            reserved:
              type: integer
              description: Credits held by AI calls still running.
            limit:
              type: [integer, 'null']
              description: The period's allowance; `null` means unlimited.
            remaining:
              type: [integer, 'null']
              description: What can still be spent; `null` means unlimited.
            periodStart: { type: string, format: date-time }
            periodEnd: { type: string, format: date-time }
            active:
              type: boolean
              description: False when the subscription isn't active (AI credits can't be spent).

    Pagination:
      type: object
      required: [nextCursor, hasMore]
      properties:
        nextCursor:
          type: [string, 'null']
          description: |
            Pass this as `?cursor=` to fetch the next page. `null` on the
            last page.
        hasMore:
          type: boolean
          description: True when more pages remain.

    Design:
      type: object
      description: Template summary. Also the `data` of every `design.*` webhook event.
      required: [id, name, orientation, pages, animated, createdAt, updatedAt]
      properties:
        id: { type: string }
        name: { type: string }
        orientation:
          type: string
          enum: [landscape, portrait, square]
          description: Derived from the first page's canvas size.
        pages:
          type: integer
          minimum: 0
          description: |
            Number of pages in the template (1 for a single image, more for
            a carousel; each page is a scene of a video). 0 only for a
            template that can't be read, which fails to render.
        animated:
          type: boolean
          description: |
            A video template: a page has animated layers, a video layer, a
            set duration or a transition into the next page, or the template
            has a soundtrack. Render it with `response.format: "mp4"` to see
            the motion; image and PDF formats show it still.
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }

    DesignDetail:
      allOf:
        - $ref: '#/components/schemas/Design'
        - type: object
          required: [parameters, sizes]
          properties:
            parameters:
              type: array
              description: Everything a render's `modifications` can set by plain key.
              items: { $ref: '#/components/schemas/TemplateParameter' }
            sizes:
              type: array
              description: |
                Smart Resize sizes saved on the template (the editor's Resize
                tab). Pass an `id` as `response.size` to render that size with
                its manual adjustments. Any other size can be rendered too.
              items: { $ref: '#/components/schemas/TemplateSize' }

    DesignGenerateRequest:
      type: object
      required: [prompt]
      additionalProperties: false
      properties:
        prompt:
          type: string
          maxLength: 4000
          description: What to design (purpose, content, audience, style). Also the design's name unless `name` is given.
        size:
          type: string
          description: |
            A size preset id (`instagram-post`, `instagram-portrait`,
            `instagram-story`, `linkedin-post`, `linkedin-carousel`,
            `youtube-thumbnail`, `og-image`, `a4-portrait`…), a short alias
            (`square`, `portrait`, `story`, `landscape`) or `WIDTHxHEIGHT`.
            Default 1080x1350. Or send `width` and `height`.
          example: instagram-story
        width: { type: integer, minimum: 16, maximum: 10000 }
        height: { type: integer, minimum: 16, maximum: 10000 }
        pages:
          type: integer
          minimum: 1
          maximum: 10
          description: Pages to design (a carousel). Default 1.
        video:
          type: boolean
          description: Make an animated video template (page durations, transitions, enter animations); render it as `mp4`.
        brand:
          description: |
            `true` (default): the workspace's brand library (colours, fonts,
            logo); `false`: no brand; or explicit values. Fonts must be
            brand-library fonts or Google fonts the editor offers.
          oneOf:
            - type: boolean
            - type: object
              additionalProperties: false
              properties:
                colors: { type: array, maxItems: 12, items: { type: string, example: '#0b1f4d' }, description: 'Hex colours, primary first.' }
                fonts: { type: array, maxItems: 4, items: { type: string, example: Poppins }, description: 'Font families, heading first.' }
                logo: { type: string, description: A brand-library image URL or any https image URL. }
        referenceImageUrl:
          type: string
          description: A public https PNG, JPEG, GIF or WebP to recreate or take inspiration from (a screenshot, a mood board).
        name: { type: string, maxLength: 120, description: The design's name. }
        async:
          type: boolean
          description: Answer `202` with the job at once instead of waiting.
        webhookUrl:
          type: string
          format: uri
          maxLength: 2048
          description: |
            With `"async": true`: POSTed `{ event, job }` when the job ends
            (see the `designGenerateCallback` webhook). Public http(s) URLs
            only (`WEBHOOK_URL_INVALID` otherwise).

    DesignGenerateJob:
      type: object
      required: [jobId, status, createdAt]
      properties:
        jobId: { type: string }
        status: { type: string, enum: [running, succeeded, failed] }
        design:
          description: The saved design (succeeded).
          allOf:
            - $ref: '#/components/schemas/DesignDetail'
            - type: object
              properties:
                editorUrl: { type: string, description: Opens the design in the editor. }
        message: { type: string, description: The design agent's summary of what it made. }
        changes: { type: array, items: { type: string }, description: 'The changes it made, one line each.' }
        creditsCharged: { type: integer, description: AI credits charged (5). }
        mock: { type: boolean, description: Made by the development server's scripted designer (no AI key). }
        error:
          description: The error envelope (failed).
          $ref: '#/components/schemas/ApiError'
        createdAt: { type: string, format: date-time }
        finishedAt: { type: [string, 'null'], format: date-time }

    TemplateSize:
      type: object
      required: [id, name, width, height]
      properties:
        id:
          type: string
          description: The value for `response.size`, e.g. `story`.
        name: { type: string }
        width: { type: integer, minimum: 16, maximum: 10000 }
        height: { type: integer, minimum: 16, maximum: 10000 }

    TemplateParameter:
      type: object
      required: [key, type, pages, example]
      properties:
        key:
          type: string
          description: The modification key, e.g. `title`.
        type:
          type: string
          enum: [text, image, qr, shape, video, audio, subtitles, variable]
          description: |
            What the value sets: `text` → the layer's text, `image` → the
            image URL, `qr` → the encoded value, `shape` → the fill colour,
            `video` → the video clip URL, `audio` → the template's audio
            track URL (listed when the template has one; it plays across
            every page), `subtitles` → the video's subtitles (listed when
            the template has some; `example` is the first cue's text),
            `variable` → a `{{placeholder}}` inside text.
        pages:
          type: array
          items: { type: integer, minimum: 1 }
          description: Pages (from 1) on which this parameter appears.
        example:
          type: string
          description: The value currently in the template.
        prompt:
          type: string
          description: |
            Layers filled by AI at render time: their prompt. Send
            `<key>.prompt` to change it, or a plain value to skip the AI;
            `example` is then the layer's saved text or image. `{{name}}`
            placeholders in it are parameters of the render too.

    FigmaImportInfo:
      type: object
      required: [workspace, organization, appUrl, format, formatVersion, limits]
      properties:
        workspace:
          type: object
          required: [id, name]
          properties:
            id: { type: string }
            name: { type: string }
        organization:
          type: object
          required: [id, name]
          properties:
            id: { type: string }
            name: { type: string }
        appUrl:
          type: string
          description: The app's origin (the editor lives at `<appUrl>/designs/<id>/edit`).
        format: { type: string, enum: [figma-import] }
        formatVersion: { type: integer, enum: [1] }
        limits:
          type: object
          description: What one import may carry (bytes, counts, px).
          additionalProperties: { type: integer }
          example:
            maxFrames: 20
            maxLayersPerFrame: 1000
            maxLayers: 5000
            maxAssets: 300
            maxAssetBytes: 10485760
            maxSvgBytes: 5242880
            maxThumbnailBytes: 1048576
            maxTotalBytes: 62914560
            maxDocumentBytes: 4194304
            maxJsonBodyBytes: 5242880
            maxTextLength: 20000
            maxCanvasSide: 10000

    FigmaImportDocument:
      type: object
      description: |
        What the Figma plugin exports. Coordinates are px in the frame; a
        layer's box is unrotated and `rotation` turns it clockwise around
        its centre. Layers are listed bottom to top. The complete schema is
        `server/src/lib/figmaImport/format.ts`; the plugin's fixtures
        (`integrations/figma-plugin/fixtures/*.json`) are full examples.
      required: [format, version, frames, assets]
      properties:
        format: { type: string, enum: [figma-import] }
        version: { type: integer, enum: [1] }
        name:
          type: string
          maxLength: 200
          description: Template name (`pages` mode; default the first frame's name).
        mode:
          type: string
          enum: [pages, separate]
          default: pages
        source:
          type: object
          properties:
            fileName: { type: string }
            fileKey: { type: [string, 'null'] }
            pageName: { type: string }
            pluginVersion: { type: string }
        options:
          type: object
          properties:
            importFonts:
              type: boolean
              default: true
              description: Add Google Fonts that aren't built in to the brand library.
        frames:
          type: array
          minItems: 1
          maxItems: 20
          items: { $ref: '#/components/schemas/FigmaImportFrame' }
        assets:
          type: array
          maxItems: 300
          items:
            type: object
            required: [id, mime]
            properties:
              id: { type: string, pattern: '^[A-Za-z0-9_-]{1,64}$' }
              mime: { type: string, enum: [image/png, image/jpeg, image/gif, image/webp, image/svg+xml] }
              name: { type: string, description: The name it gets in the brand library. }
              role: { type: string, enum: [layer, thumbnail] }
              data: { type: string, format: byte, description: 'Base64 bytes (JSON requests only).' }
        warnings:
          type: array
          description: Notes from the plugin, passed through to the result.
          items: { $ref: '#/components/schemas/FigmaImportWarning' }

    FigmaImportFrame:
      type: object
      required: [id, name, width, height, background, layers]
      properties:
        id: { type: string, description: Figma node id. }
        name: { type: string }
        width: { type: number, minimum: 1, maximum: 10000 }
        height: { type: number, minimum: 1, maximum: 10000 }
        background:
          type: [string, 'null']
          description: '`#rrggbb`; null for none (white).'
        thumbnail:
          type: string
          description: Asset id of a small preview, stored as the design's thumbnail.
        layers:
          type: array
          maxItems: 1000
          items: { $ref: '#/components/schemas/FigmaImportLayer' }

    FigmaImportLayer:
      type: object
      description: |
        One layer. Common fields below; by `type`:
        `text`: `text`, `runs` (style runs: `start`, `end`, `fontFamily`,
        `fontStyle`, `fontWeight`, `italic`, `fontSize`, `lineHeight`,
        `letterSpacing`, `color`, `textCase`, `decoration`), `align`,
        `verticalAlign`, `autoResize`, `inkBounds`;
        `rectangle`, `ellipse`, `line`, `triangle`: `fill`, `stroke`,
        `strokeWidth`, `strokeAlign`, `strokeCap`, `cornerRadius`;
        `image`: `asset`, `fit` (`cover`, `contain`, or `fill` for a render
        of the layer), `cornerRadius`, `flipX`, `flipY`.
      required: [type, id, name, x, y, width, height]
      properties:
        type: { type: string, enum: [text, rectangle, ellipse, line, triangle, image] }
        id: { type: string }
        name: { type: string }
        param:
          type: string
          description: API parameter key (from a `{{key}}` or `#key` layer name).
        x: { type: number }
        y: { type: number }
        width: { type: number, minimum: 0 }
        height: { type: number, minimum: 0 }
        rotation: { type: number, description: 'Degrees, clockwise.' }
        opacity: { type: number, minimum: 0, maximum: 1 }
        clip:
          type: object
          description: The visible area left by a clipping parent frame (images and rectangles are cropped to it).
          properties:
            x: { type: number }
            y: { type: number }
            width: { type: number }
            height: { type: number }
            radius: { type: number }
      additionalProperties: true

    FigmaImportWarning:
      type: object
      required: [message]
      properties:
        frame: { type: string }
        layer: { type: string }
        message: { type: string }

    FigmaImportResult:
      type: object
      required: [designs, fonts, assets, warnings]
      properties:
        designs:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Design'
              - type: object
                required: [pages, parameters, editorUrl]
                properties:
                  pages: { type: integer, minimum: 1 }
                  parameters:
                    type: array
                    items: { $ref: '#/components/schemas/TemplateParameter' }
                  editorUrl:
                    type: string
                    format: uri
                    description: The template in the editor.
        fonts:
          type: array
          items:
            type: object
            required: [family, status, usedFamily]
            properties:
              family: { type: string, description: The family as Figma names it. }
              status:
                type: string
                enum: [google, brand-library, imported, fallback]
                description: |
                  `google`: a built-in Google Font. `brand-library`: a font
                  file in the brand library. `imported`: added to the brand
                  library from Google Fonts now. `fallback`: unavailable,
                  drawn in `usedFamily`.
              usedFamily: { type: string }
              note: { type: string }
        assets:
          type: object
          required: [stored, bytes]
          description: Files added to the brand library (fonts not counted).
          properties:
            stored: { type: integer }
            bytes: { type: integer }
        warnings:
          type: array
          description: What didn't carry over exactly (flattened text styles, dropped effects, fonts that fell back, …).
          items: { $ref: '#/components/schemas/FigmaImportWarning' }

    ModificationValue:
      description: |
        A value for one modification key. Strings are used as-is (up to
        20,000 characters; `subtitles` up to 500,000, a whole SRT or WebVTT
        file); numbers and booleans are accepted for numeric and boolean
        style properties; `null` clears the value. `subtitles` also takes
        an array of cues.
      oneOf:
        - type: string
          maxLength: 500000
        - type: number
        - type: boolean
        - type: 'null'
        - type: array
          maxItems: 5000
          description: '`subtitles` only: the cues, in seconds on the video''s timeline.'
          items: { $ref: '#/components/schemas/SubtitleCue' }

    BackgroundRemoval:
      type: object
      required: [url, method, model, scaled, creditsCharged, asset]
      properties:
        url: { type: string, format: uri, description: The transparent PNG (the brand-library asset's URL). }
        width: { type: [integer, 'null'] }
        height: { type: [integer, 'null'] }
        method:
          type: string
          enum: [local, model]
          description: '`local`: U²-Net on our servers, original pixels kept. `model`: an image model redrew the subject (servers without the local model).'
        model: { type: string, description: 'The model that cut it out: `u2net`, `u2netp`, `silueta`, or an AI model slug.' }
        scaled: { type: boolean, description: 'The cut-out is smaller than the picture (over 4096 px a side, or over 10 MB as PNG).' }
        creditsCharged: { type: integer }
        asset: { $ref: '#/components/schemas/BrandAsset' }
    BrandAsset:
      type: object
      description: A file in the workspace's brand library.
      required: [id, kind, name, url, tags]
      properties:
        id: { type: string }
        kind: { type: string, enum: [image, video, audio, font, color] }
        name: { type: string }
        url: { type: string }
        mimeType: { type: [string, 'null'] }
        size: { type: [integer, 'null'] }
        createdAt: { type: string, format: date-time }
        tags: { type: array, items: { type: string } }
        meta: { type: [object, 'null'], additionalProperties: true, description: 'Facts read from the file: `width`, `height` (images, videos), `duration` (videos, audio).' }
    TranscribeRequest:
      type: object
      required: [url]
      properties:
        url: { type: string, format: uri, description: 'An audio file (MP3, M4A, WAV, Ogg) or a video (MP4, WebM) with sound, up to 100 MB.' }
        language: { type: string, description: 'ISO-639-1 code such as `en`; detected when omitted.' }
        style: { type: string, enum: [standard, short], default: standard, description: '`standard`: up to 2 lines of 42 characters. `short`: one line of up to 24 characters.' }
        maxCharsPerLine: { type: integer, minimum: 12, maximum: 80 }
        maxLines: { type: integer, minimum: 1, maximum: 3 }
        start: { type: number, minimum: 0, description: Seconds into the file to start from. }
        duration: { type: number, minimum: 0.5, description: 'Seconds to transcribe (default: to the end).' }
        offset: { type: number, minimum: 0, default: 0, description: Seconds added to every cue (where `start` lands on your video). }
        words: { type: boolean, default: false, description: Include the word timestamps. }
    Transcription:
      type: object
      required: [duration, text, cues, srt, vtt, creditsCharged]
      properties:
        language: { type: [string, 'null'] }
        duration: { type: number, description: Seconds of audio transcribed. }
        text: { type: string }
        cues: { type: array, items: { $ref: '#/components/schemas/SubtitleCue' } }
        srt: { type: string }
        vtt: { type: string }
        words:
          type: array
          items:
            type: object
            properties:
              word: { type: string }
              start: { type: number }
              end: { type: number }
        creditsCharged: { type: integer }
        model: { type: string }
        mock: { type: boolean, description: 'A development server without an AI key: placeholder words.' }

    SubtitleCue:
      type: object
      required: [start, end, text]
      properties:
        start:
          type: number
          minimum: 0
          description: Seconds on the video's timeline when the cue appears.
        end:
          type: number
          description: Seconds when it goes (after `start`).
        text:
          type: string
          maxLength: 1000
          description: Plain text; a newline starts a new line. Styling tags are stripped.

    RenderRequest:
      type: object
      required: [templateId]
      properties:
        templateId:
          type: string
          maxLength: 64
          description: |
            Id of a design in the API key's workspace or of a template-library
            template. A library template can also be named by its slug
            (`tool-quote-card-paper`).
        modifications:
          type: object
          description: |
            Values to fill in, keyed by modification key: `key`,
            `pageN@key`, `key.property` or `pageN@key.property` (see
            "Modification keys" in the introduction). Keys are at most 200
            characters.
          propertyNames:
            minLength: 1
            maxLength: 200
          additionalProperties: { $ref: '#/components/schemas/ModificationValue' }
        response: { $ref: '#/components/schemas/RenderOptions' }
        async:
          type: boolean
          default: false
          description: |
            Run as a render job and answer `202` with its `jobId` at once
            (see `GET /render-jobs/{id}`). MP4 renders are always jobs; this
            makes the request return without waiting.
        webhookUrl:
          type: string
          format: uri
          maxLength: 2048
          description: |
            Render jobs only (`"async": true` or an MP4): JamFrame POSTs
            `{ "event": "render.completed" | "render.failed", "job": … }`
            here when the job ends (see the `renderJobCallback` webhook).
            Must be `https://` in production and must not point to a
            private or loopback address. Sending it with a synchronous
            image or PDF render is a `400`.
        expiresIn:
          type: integer
          minimum: 1
          maximum: 604800
          default: 300
          description: |
            How long the file links in the answer work, in seconds: 5
            minutes by default, at most 7 days (`expiresAt` says until
            when). A render job keeps it: each `GET /render-jobs/{id}`, and
            each webhook, carries fresh links that work this long. Files are
            deleted 8 days after the render. For a permanent image link, use
            a Dynamic URL. Not with `response.type: "base64"`.
          example: 3600
        translate:
          type: boolean
          default: false
          description: |
            Translate every text layer's final text (after `modifications`
            and AI layers) into `lang` with AI, in one call per render.
            `{{placeholders}}`, links, e-mail addresses, @handles, #hashtags
            and numbers are kept as they are. Cached per text and language:
            a repeat costs no AI credits. Needs `lang`.
        lang:
          type: string
          minLength: 2
          maxLength: 35
          description: The language to translate into with `translate`, a BCP 47 tag such as `es`, `fr`, `pt-BR` or `zh-Hant`.
          example: es
        ai:
          type: object
          additionalProperties: false
          description: How the render's AI layers and translation behave.
          properties:
            onError:
              type: string
              enum: [fail, fallback]
              default: fail
              description: |
                `fail`: an AI failure fails the render with its `AI_*` code.
                `fallback`: AI layers render their saved text and image (a
                cached result is still used) and the text stays
                untranslated, with a warning; no AI credits are charged.

    RenderOptions:
      type: object
      description: How to render and how to return the result. Every field is optional.
      properties:
        type:
          type: string
          enum: [url, base64]
          default: url
          description: |
            `url` stores each file and returns a link to it that works for
            `expiresIn` seconds. `base64` returns the file bytes inline and
            stores nothing.
        format:
          type: string
          enum: [png, jpeg, jpg, webp, pdf, mp4]
          default: png
          description: |
            Output format. `jpg` is an alias of `jpeg`. `mp4` renders a
            video (H.264, 30 fps, AAC audio when the template has a track,
            subtitles burned in) as a render job.
        scale:
          type: integer
          minimum: 1
          maximum: 3
          default: 1
          description: Pixel density for images (2 = twice the canvas size). Ignored for PDF and MP4 (videos are the canvas size).
        quality:
          type: integer
          minimum: 1
          maximum: 100
          description: Compression quality for `jpeg` and `webp`. Ignored for `png`, `pdf` and `mp4`.
        includePages:
          type: array
          maxItems: 50
          items: { type: integer, minimum: 1 }
          description: |
            Pages to render (from 1). All pages when omitted. A page the
            template doesn't have is a `400 VALIDATION_ERROR`; at most 20
            pages are rendered per request.
        size:
          type: string
          minLength: 1
          maxLength: 64
          description: |
            Smart Resize: render every page at this size. A size saved on
            the template (its id from `GET /designs/{id}` `sizes`, with its
            manual adjustments), a size name (`story`, `reel`, `square`,
            `portrait`, `landscape`, `widescreen`, `thumbnail`, `pin`, or a
            preset id like `instagram-story`, `og-image`,
            `youtube-thumbnail`), `"WIDTHxHEIGHT"` (16–10000 px; a saved
            size of those dimensions is used when there is one), or
            `original`. Works with every format, MP4 included.
          examples: [story, 1080x1920, original]
        sizes:
          type: array
          minItems: 1
          maxItems: 10
          items: { type: string, minLength: 1, maxLength: 64 }
          description: |
            Smart Resize: render each of these sizes (same values as
            `size`) in one synchronous call; `content` is then one entry per
            size (`SizedContent`). Not with `size`, `mp4`, `async` or
            `base64`. Credits: 1 per page per size. Two values that name the
            same output (`story` and `1080x1920`) are a `400`, and so is a
            call that would render more than 30 pages in all (pages ×
            sizes): ask for fewer, or send one request per size.
          examples: [[original, story, square]]
        subtitles:
          type: string
          enum: [srt, vtt]
          description: |
            MP4 only: also store the video's subtitles as an `.srt` or
            `.vtt` file next to the MP4 and return its URL as
            `data.subtitles`. Free. Without subtitles the file has no cues
            (and a warning says so).
        cmyk:
          description: |
            **Experimental.** PDF only (`"format": "pdf"`); off by default.
            Converts the PDF's colours to CMYK for print with an ICC
            profile: text and shapes stay vector, greys and black text print
            with black ink only, and the file gets the profile as its output
            intent and is labelled PDF/X-4 when it qualifies. `true` uses
            `fogra39`. Semi-transparent areas blend in CMYK, as PDF/X-4
            requires, so overlaps can look slightly different from the
            screen. The options and the output may still change.
          oneOf:
            - type: boolean
            - type: object
              additionalProperties: false
              properties:
                profile:
                  type: string
                  enum: [fogra39, fogra51, fogra52, fogra47, fogra29, fogra40, fogra45, ifra26, gracol2013, gracol2013-uncoated, swop2013, japan2011, gracol2006]
                  default: fogra39
                  description: |
                    The printing condition. `fogra39` (offset, coated paper,
                    Europe), `fogra51` / `fogra52` (PSO Coated / Uncoated v3,
                    Europe), `fogra47` and `fogra29` (uncoated, Europe),
                    `fogra40` and `fogra45` (magazine paper), `ifra26`
                    (newspapers), `gracol2013`, `gracol2013-uncoated` and
                    `gracol2006` (sheet-fed, USA), `swop2013` (publication,
                    USA), `japan2011` (Japan Color 2011 Coated). Ask your
                    print shop which one to use.
          examples: [true, { profile: gracol2013 }]
        compress:
          description: |
            **Experimental.** PDF only (`"format": "pdf"`); off by default.
            Makes the PDF smaller, like Ghostscript's PDF settings: images
            drawn at more than the preset's resolution are downsampled
            (measured where each image is drawn), photos may be stored as
            JPEG, and the file structure is compressed. Text and shapes are
            not changed. `true` uses the `ebook` preset. With `cmyk`, the CMYK
            file is compressed. The options and the output may still change.
          oneOf:
            - type: boolean
            - type: object
              additionalProperties: false
              properties:
                preset:
                  type: string
                  enum: [ebook, screen, printer, prepress]
                  default: ebook
                  description: |
                    `screen`: 72 dpi, JPEG quality 60 (smallest). `ebook`:
                    150 dpi, quality 75 (sharing and email). `printer`: 300
                    dpi, quality 90. `prepress`: 300 dpi, quality 95 (print
                    shops).
                dpi:
                  type: integer
                  minimum: 36
                  maximum: 1200
                  description: |
                    Image resolution in pixels per inch, instead of the
                    preset's. An image is downsampled only when it is above
                    1.5 times this.
          examples: [true, { preset: printer }, { preset: ebook, dpi: 200 }]

    SizedContent:
      type: object
      description: One size of a `response.sizes` render.
      required: [size, name, width, height, pages]
      properties:
        size:
          type: string
          description: The size as requested.
        name:
          type: string
          description: The saved size's or size preset's name (`Original` for `original`).
        width: { type: integer }
        height: { type: integer }
        pages:
          type: array
          items: { type: integer, minimum: 1 }
          description: Template pages rendered at this size.
        url:
          type: string
          description: A link to the file, when this size is one file (one image, or any PDF). Works until `data.expiresAt`.
        urls:
          type: array
          items: { type: string }
          description: One file per page (a carousel), in page order. Links that work until `data.expiresAt`.

    RenderResponse:
      type: object
      required: [data]
      properties:
        data: { $ref: '#/components/schemas/RenderResult' }
        warnings:
          type: array
          items: { type: string }
          description: |
            Non-fatal problems, such as modification keys that matched no
            layer or placeholder. Omitted when there are none.

    RenderResult:
      description: The `data` of a successful render, and a succeeded render job's `result`.
      type: object
      required: [content, type, format, pages, credits, renderId, responseTime]
      properties:
        content:
          description: |
            One link or base64 string per file. A single string when
            the render produced one file (one image, any PDF, any MP4);
            an array in page order for multi-page images. With
            `response.sizes`, one `SizedContent` per size instead. Links
            are signed: they work until `expiresAt`, then answer `403`.
          oneOf:
            - type: string
            - type: array
              items: { type: string }
            - type: array
              items: { $ref: '#/components/schemas/SizedContent' }
        urls:
          type: array
          items: { type: string }
          description: |
            `response.type: "url"` only: every file's link in one list, in
            page order; with `response.sizes`, every size's files in the
            order of `content`. The same links as `content`, but always an
            array, for clients that can't tell a string from an array
            (Make's formulas, for example).
        expiresAt:
          type: string
          format: date-time
          description: |
            `response.type: "url"` only: when the links in `content` (and
            `subtitles`) stop working, `expiresIn` seconds after they were
            handed out. A render job's `result` gets fresh links, and a new
            `expiresAt`, on every read.
        type:
          type: string
          enum: [url, base64]
        format:
          type: string
          enum: [png, jpeg, webp, pdf, mp4]
          description: The output format (`jpg` requests report `jpeg`).
        pages:
          type: array
          items: { type: integer, minimum: 1 }
          description: The template pages that were rendered (for MP4, the scenes in order).
        credits:
          type: integer
          description: Credits charged (1 per image or PDF page; 1 per second of video output, rounded up; with `sizes`, 1 per page per size).
        renderId:
          type: string
          description: Id of this render, for support and usage logs.
        responseTime:
          type: integer
          description: Server-side render time in milliseconds.
        duration:
          type: number
          description: MP4 only. The video's length in seconds (its frames / 30; each scene transition overlaps two scenes and shortens it).
        subtitles:
          type: string
          description: MP4 with `response.subtitles` only. A link to the `.srt` / `.vtt` file, until `expiresAt`.
        aiCredits:
          type: integer
          minimum: 0
          description: |
            Templates with AI layers, or `translate`: AI credits charged for
            this render (once for every size, page and frame), 0 when every
            result came from the cache. Omitted for renders without AI.

    RenderItem:
      type: object
      description: One render from the workspace's render log.
      required:
        [id, createdAt, designId, designName, source, format, pages, credits, status, durationMs, outputs, error, cached]
      properties:
        id:
          type: string
          description: The render id (`renderId` in the render response).
        createdAt: { type: string, format: date-time }
        designId:
          type: [string, 'null']
          description: The template rendered. `null` when it has since been deleted.
        designName:
          type: [string, 'null']
          description: The template's current name. `null` when it has been deleted.
        source:
          type: string
          enum: [api, editor, signed-url, dynamic-url, form, workflow, shopify, webflow]
          description: |
            `api` for this API (including integrations such as Zapier and
            Make), `editor` for the web app's test render, `signed-url` and
            `dynamic-url` for the public render URLs, `form` for a template's
            public form, `workflow` for a workflow's runs, `shopify` for the
            Shopify app, `webflow` for the Webflow app.
        cached:
          type: boolean
          description: |
            Served from the render cache (signed and dynamic URLs): nothing
            was rendered, `credits` is 0, and `outputs` are the cached
            render's files.
        format:
          type: string
          enum: [png, jpeg, webp, pdf, mp4]
        pages:
          type: integer
          minimum: 0
          description: Number of template pages rendered (0 when a render job failed before rendering).
        credits:
          type: integer
          minimum: 0
          description: Credits charged. Always 0 for a failed render.
        status:
          type: string
          enum: [succeeded, failed]
        durationMs:
          type: integer
          description: Server-side render time in milliseconds.
        outputs:
          type: array
          description: |
            The stored files, in page order: one per page for images, one
            for a PDF or an MP4. Empty for failed renders and for `base64`
            renders, which store nothing. Each read answers fresh links;
            files are deleted 8 days after the render (31 for signed and
            dynamic URLs).
          items: { $ref: '#/components/schemas/RenderOutputFile' }
        error:
          type: [string, 'null']
          maxLength: 300
          description: Why a failed render failed (shortened to 300 characters). `null` otherwise.

    SignedUrlRequest:
      type: object
      required: [templateId]
      additionalProperties: false
      properties:
        templateId:
          type: string
          maxLength: 64
          description: A template of the workspace, or a template-library template.
        modifications:
          type: object
          maxProperties: 50
          description: As in `POST /render`. Values up to 2000 characters.
          additionalProperties:
            type: [string, number, boolean, 'null']
        response:
          type: object
          additionalProperties: false
          properties:
            format:
              type: string
              enum: [png, jpeg, jpg, webp, pdf]
              default: png
            scale:
              type: integer
              minimum: 1
              maximum: 3
              default: 1
              description: Pixel density for images.
            quality:
              type: integer
              minimum: 1
              maximum: 100
              description: JPEG and WebP quality.
            includePages:
              type: array
              items: { type: integer, minimum: 1 }
              minItems: 1
              maxItems: 20
              description: One page for an image (default 1); any pages for a PDF (default all).
            size:
              type: string
              maxLength: 64
              description: A Smart Resize target (a size id, a size name or `WIDTHxHEIGHT`), as `response.size` in `POST /render`.
        expiresIn:
          type: integer
          minimum: 1
          maximum: 31536000
          default: 604800
          description: Seconds until the URL stops working (default 7 days, at most 1 year).
        cacheSeconds:
          type: integer
          minimum: 0
          maximum: 2592000
          default: 2592000
          description: |
            How long a render of this URL is reused (default and most 30
            days, since its file is deleted after 31; 0 renders every
            request). URLs signed with a longer time before reuse it for 30
            days.

    SignedUrlResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [url, templateId, format, expiresAt]
          properties:
            url:
              type: string
              format: uri
              description: The public URL, `<origin>/r/s/<kid>.<payload>.<sig>.<ext>`.
            templateId: { type: string }
            format:
              type: string
              enum: [png, jpeg, webp, pdf]
            expiresAt: { type: string, format: date-time }
        warnings:
          type: array
          items: { type: string }
          description: Modification keys that match nothing in the template.

    PublicUrlError:
      type: object
      required: [error, message]
      description: The error body of a public render URL. Short and generic on purpose.
      properties:
        error:
          type: string
          enum:
            - INVALID_PARAMETERS
            - INVALID_SIGNATURE
            - NOT_FOUND
            - URL_EXPIRED
            - URL_DISABLED
            - CREDIT_CAP_REACHED
            - CREDITS_EXHAUSTED
            - UNAVAILABLE
            - MEDIA_UNAVAILABLE
            - RATE_LIMITED
            - BUSY
            - RENDER_FAILED
        message: { type: string }

    PublicFormError:
      type: object
      required: [error, message]
      description: The error body of the public form API. Short and generic on purpose.
      properties:
        error:
          type: string
          enum:
            - NOT_FOUND
            - FORM_DISABLED
            - FORM_EXPIRED
            - INVALID_VALUES
            - INVALID_REQUEST
            - CAPTCHA_FAILED
            - CAPTCHA_UNAVAILABLE
            - UPLOAD_INVALID
            - UPLOAD_TOO_LARGE
            - UPLOADS_UNAVAILABLE
            - CREDIT_CAP_REACHED
            - CREDITS_EXHAUSTED
            - UNAVAILABLE
            - MEDIA_UNAVAILABLE
            - RATE_LIMITED
            - BUSY
            - RENDER_FAILED
            - FILE_EXPIRED
            - BODY_TOO_LARGE
            - UNSUPPORTED_MEDIA_TYPE
        message: { type: string }
        fields:
          type: object
          additionalProperties: { type: string }
          description: '`INVALID_VALUES` only: the problem with each field, by key.'

    PublicFormField:
      type: object
      required: [key, kind, input, label, help, required, options, maxLength, placeholder]
      properties:
        key:
          type: string
          description: The answer's key in `values` (a parameter, or `parameter.prop` for a style field).
        kind: { type: string, enum: [text, image, color, url, choice] }
        input: { type: string, enum: [text, textarea, select, upload, url, upload-or-url, color] }
        label: { type: string }
        help: { type: string }
        required: { type: boolean }
        options:
          type: array
          items: { type: string }
          description: The choices of a `select`.
        maxLength: { type: integer }
        placeholder:
          type: string
          description: The template's own text (text fields), shown as the input's placeholder.

    PublicForm:
      type: object
      required: [form, template, appName, turnstileSiteKey]
      properties:
        form:
          type: object
          required: [id, title, description, status, fields, output, branding, uploads]
          properties:
            id: { type: string, description: The public id. }
            title: { type: string }
            description: { type: [string, 'null'] }
            status:
              type: string
              enum: [active, cap_reached, unavailable]
              description: '`unavailable`: the server can''t take renders or uploads (no bot check configured).'
            fields:
              type: array
              items: { $ref: '#/components/schemas/PublicFormField' }
            output:
              type: object
              required: [format, scale, pages, width, height]
              properties:
                format: { type: string, enum: [png, jpeg, webp, pdf] }
                scale: { type: integer, enum: [1, 2] }
                pages: { type: array, items: { type: integer } }
                width: { type: integer }
                height: { type: integer }
            branding:
              type: object
              required: [logoUrl, accentColor]
              properties:
                logoUrl: { type: [string, 'null'] }
                accentColor: { type: [string, 'null'], description: '#rrggbb' }
            uploads:
              type: object
              required: [maxBytes, accept]
              properties:
                maxBytes: { type: integer }
                accept: { type: array, items: { type: string } }
        template:
          type: object
          required: [pages, variables, customFonts]
          description: What the live preview draws (the editor's template JSON, one page each).
          properties:
            pages:
              type: array
              items:
                type: object
                required: [canvas, elements]
                properties:
                  canvas: { type: object, additionalProperties: true }
                  elements: { type: array, items: { type: object, additionalProperties: true } }
            variables:
              type: object
              additionalProperties: { type: string }
            customFonts:
              type: array
              items: { type: object, additionalProperties: true }
        appName: { type: string }
        turnstileSiteKey:
          type: string
          description: Cloudflare Turnstile site key; empty when the check is off.

    PublicFormRenderRequest:
      type: object
      required: [values]
      properties:
        values:
          type: object
          additionalProperties: { type: string }
          description: Answers by field key.
        turnstileToken:
          type: string
          description: Required when the form's `turnstileSiteKey` is not empty.

    PublicFormRender:
      type: object
      required: [format, files]
      description: The render's files. Nothing says whether it came from the render cache or which render it was.
      properties:
        format: { type: string, enum: [png, jpeg, webp, pdf] }
        files:
          type: array
          items:
            type: object
            required: [url, page, downloadUrl]
            properties:
              url:
                type: string
                format: uri-reference
                description: The file, shown inline (`GET /api/public/forms/{publicId}/files/{handle}`), on the app's origin. A fresh handle per response.
              page: { type: [integer, 'null'] }
              downloadUrl:
                type: string
                format: uri-reference
                description: The same file as an attachment (`url` with `?download=1`).

    PublicFormUpload:
      type: object
      required: [id, url, expiresAt]
      properties:
        id: { type: string }
        url: { type: string, format: uri, description: The answer to send for the field. }
        expiresAt: { type: string, format: date-time }

    RenderOutputFile:
      type: object
      required: [url, page]
      properties:
        url:
          type: string
          format: uri
          description: A link to the file, signed for this read. It works until `expiresAt`.
        page:
          type: [integer, 'null']
          minimum: 1
          description: The template page this file shows; for a PDF, its first page.
        expiresAt:
          type: string
          format: date-time
          description: When `url` stops working (5 minutes after the read).

    RenderTotals:
      type: object
      description: Credit usage in the organization's current billing period.
      required:
        [periodStart, periodEnd, creditsUsed, creditsQuota, creditsRemaining, workspaceCreditsUsed]
      properties:
        periodStart: { type: string, format: date-time }
        periodEnd: { type: string, format: date-time }
        creditsUsed:
          type: integer
          description: Credits the organization used this period, across all its workspaces.
        creditsQuota:
          type: [integer, 'null']
          description: Credits the organization's plan includes per period. `null` when unlimited.
        creditsRemaining:
          type: [integer, 'null']
          description: Credits left this period. `null` when unlimited.
        workspaceCreditsUsed:
          type: integer
          description: This workspace's share of `creditsUsed`.

    WebhookEventType:
      type: string
      enum:
        - design.created
        - design.updated
        - design.deleted
        - render.completed
        - render.failed
        - social.post.published
        - social.post.failed
        - workflow.run.completed
        - workflow.run.failed
      description: |
        An event a subscription can listen to. Sent as the
        `X-Webhook-Event` header on every delivery.

    WebhookSubscription:
      type: object
      required:
        - id
        - url
        - events
        - status
        - secretTail
        - failureCount
        - lastFiredAt
        - createdAt
        - updatedAt
      properties:
        id: { type: string }
        url:
          type: string
          format: uri
          description: |
            The URL that receives signed POSTs. Always `https` in
            production.
        events:
          type: array
          minItems: 1
          items: { $ref: '#/components/schemas/WebhookEventType' }
        status:
          type: string
          enum: [active, suspended, revoked]
          description: |
            `suspended` once 20 consecutive deliveries have failed.
            Re-activate it in the web app after fixing your endpoint.
            `revoked` once its creator lost editor access to the
            workspace: it never delivers again (create a new one).
        secretTail:
          type: string
          description: |
            Last 4 characters of the signing secret, for display
            ("wh_sec_…wxyz"). The full secret is only returned by
            `createWebhookSubscription` and
            `rotateWebhookSubscriptionSecret`.
        failureCount:
          type: integer
          description: Consecutive failed deliveries since the last success.
        lastFiredAt: { type: [string, 'null'], format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }

    WebhookSubscriptionInput:
      type: object
      required: [url, events]
      properties:
        url:
          type: string
          format: uri
          description: |
            Endpoint that receives webhook POSTs. Must be `https://` in
            production and must not resolve to a private or loopback
            address.
        events:
          type: array
          minItems: 1
          items: { $ref: '#/components/schemas/WebhookEventType' }

    WebhookEvent:
      type: object
      required: [id, type, createdAt, data]
      description: |
        Body of every webhook POST. `id` identifies the event and is the
        same for every subscription that receives it; the
        `X-Webhook-Delivery` header identifies this subscription's
        delivery.
      properties:
        id:
          type: string
          description: Event id.
          example: whe_abcd1234EFGH56789ijklMNOP
        type: { $ref: '#/components/schemas/WebhookEventType' }
        createdAt: { type: string, format: date-time }
        data:
          description: A `Design` for `design.*` events; a `RenderJob` for `render.*` events; a `SocialPostEvent` for `social.post.*` events; a `WorkflowRunEvent` for `workflow.run.*` events.
          oneOf:
            - $ref: '#/components/schemas/Design'
            - $ref: '#/components/schemas/RenderJob'
            - $ref: '#/components/schemas/SocialPostEvent'
            - $ref: '#/components/schemas/WorkflowRunEvent'

    RenderJobAccepted:
      type: object
      required: [data]
      description: The `202` answer of a render that runs as a render job.
      properties:
        data:
          type: object
          required: [jobId, status]
          properties:
            jobId:
              type: string
              description: Pass it to `GET /render-jobs/{id}`.
            status:
              type: string
              enum: [queued, running]

    RenderJob:
      type: object
      description: |
        A render job: an MP4 render, or a render sent with
        `"async": true`. Also the `data` of `render.*` webhook events and
        the `job` of `webhookUrl` callbacks.
      required: [id, status, progress, format, templateId, createdAt, startedAt, finishedAt, result, error]
      properties:
        id: { type: string }
        status:
          type: string
          enum: [queued, running, succeeded, failed]
          description: '`succeeded` and `failed` are final.'
        progress:
          type: number
          minimum: 0
          maximum: 1
          description: |
            0 to 1 while running. For a video, the share of its frames
            captured so far (a long video is rendered in chunks side by
            side; this counts all of them); images and PDFs go from 0 to 1
            when done. A job interrupted by a server restart starts again
            once (from 0) and is charged only when it succeeds.
        format:
          type: string
          enum: [png, jpeg, webp, pdf, mp4]
        templateId:
          type: [string, 'null']
          description: The template rendered. `null` when it has since been deleted.
        createdAt: { type: string, format: date-time }
        startedAt:
          type: [string, 'null']
          format: date-time
          description: When a worker first picked the job up.
        finishedAt:
          type: [string, 'null']
          format: date-time
        result:
          description: |
            When `succeeded`: the same object a synchronous render returns
            as `data` (for an MP4, `content` is the video's link and
            `duration` its length in seconds). Its links are signed each
            time the job is read or sent, for the request's `expiresIn`,
            until `expiresAt`. `null` otherwise.
          oneOf:
            - $ref: '#/components/schemas/RenderResult'
            - type: 'null'
        error:
          description: |
            When `failed`: the error a synchronous render would have
            answered (`VALIDATION_ERROR` for an image, video or audio URL
            that won't load; `INTERNAL` when the renderer failed). No
            credits are charged. `null` otherwise.
          oneOf:
            - $ref: '#/components/schemas/ApiError'
            - type: 'null'
        warnings:
          type: array
          items: { type: string }
          description: As in a synchronous render (e.g. unknown modification keys). Omitted when there are none.

    RenderJobCallback:
      type: object
      required: [event, job]
      description: Body of the POST to a render request's `webhookUrl`.
      properties:
        event:
          type: string
          enum: [render.completed, render.failed]
        job: { $ref: '#/components/schemas/RenderJob' }
    DesignGenerateCallback:
      type: object
      required: [event, job]
      description: Body of the POST to a `POST /designs/generate` request's `webhookUrl`.
      properties:
        event:
          type: string
          enum: [design.generate.completed, design.generate.failed]
        job: { $ref: '#/components/schemas/DesignGenerateJob' }

    SocialPlatform:
      type: string
      enum: [instagram, facebook, linkedin, linkedin_page, x, tiktok, youtube, pinterest, bluesky, buffer]
      description: |
        `linkedin` is a personal profile, `linkedin_page` a company page,
        `facebook` a Page. `pinterest` posts Pins to a board. `buffer` is a channel of a connected Buffer
        account (docs/buffer.md); the post goes into its Buffer queue.

    SocialAccount:
      type: object
      required: [id, platform, platformName, name, status, sandbox, createdAt]
      properties:
        id: { type: string }
        platform: { $ref: '#/components/schemas/SocialPlatform' }
        platformName: { type: string, example: LinkedIn }
        name: { type: string }
        username: { type: [string, 'null'] }
        avatarUrl: { type: [string, 'null'] }
        status:
          type: string
          enum: [active, needs_reconnect]
          description: '`needs_reconnect`: the token was revoked or expired; reconnect it in the app.'
        statusReason: { type: [string, 'null'] }
        sandbox:
          type: boolean
          description: Connected without platform keys on a development server; posting is simulated.
        reconnectBy:
          type: [string, 'null']
          format: date-time
          description: When the connection lapses unless reconnected (LinkedIn tokens last 60 days).
        createdAt: { type: string, format: date-time }
        lastPostedAt: { type: [string, 'null'], format: date-time }

    SocialPostInput:
      type: object
      additionalProperties: false
      description: |
        One media source (`templateId`, `renderId` or `mediaUrls`; drafts
        may have none), the accounts, the caption, and when. Unknown fields
        are refused.
      properties:
        templateId: { type: string, maxLength: 64, description: Render this template and post the result. }
        modifications:
          type: object
          additionalProperties: { $ref: '#/components/schemas/ModificationValue' }
          description: The template's parameters, as for `POST /render`.
        response:
          type: object
          additionalProperties: false
          description: |
            Render options. Default format: `jpeg` when an Instagram or
            TikTok account is in the post, `mp4` when every account is
            YouTube, else `png`.
          properties:
            format: { type: string, enum: [png, jpeg, jpg, webp, pdf, mp4] }
            scale: { type: integer, minimum: 1, maximum: 3 }
            quality: { type: integer, minimum: 1, maximum: 100 }
            includePages: { type: array, items: { type: integer, minimum: 1 }, maxItems: 50 }
        renderId: { type: string, maxLength: 64, description: Post the stored files of this render. }
        mediaUrls:
          type: array
          minItems: 1
          maxItems: 35
          items: { type: string, maxLength: 2048 }
          description: Image, video or PDF URLs (up to 100 MB each), downloaded and stored when the post is created.
        accounts:
          type: array
          maxItems: 25
          description: Account ids, or objects overriding the caption or options for one account.
          items:
            oneOf:
              - type: string
              - type: object
                additionalProperties: false
                required: [id]
                properties:
                  id: { type: string }
                  caption: { type: string }
                  options: { type: object, description: "This account's platform options (see `options`)." }
        caption: { type: string, maxLength: 70000 }
        captions:
          type: object
          description: Per-platform captions over `caption` (a LinkedIn page falls back to `linkedin`).
          additionalProperties: false
          properties:
            instagram: { type: string }
            facebook: { type: string }
            linkedin: { type: string }
            linkedin_page: { type: string }
            x: { type: string }
            tiktok: { type: string }
            youtube: { type: string }
            pinterest: { type: string }
            bluesky: { type: string }
            buffer: { type: string }
        options:
          type: object
          additionalProperties: false
          description: Per-platform options.
          properties:
            instagram:
              type: object
              additionalProperties: false
              properties:
                shareToFeed: { type: boolean, description: 'Reels: also show in the feed (default true).' }
            facebook:
              type: object
              additionalProperties: false
              properties:
                title: { type: string, maxLength: 255, description: Video title. }
            linkedin: { $ref: '#/components/schemas/LinkedInPostOptions' }
            linkedin_page: { $ref: '#/components/schemas/LinkedInPostOptions' }
            x: { type: object, additionalProperties: false }
            tiktok:
              type: object
              additionalProperties: false
              description: |
                TikTok requires an explicit `privacyLevel` (one the creator
                offers). Until TikTok audits the app only `SELF_ONLY` works.
                With `draft: true` the post goes to the creator's TikTok inbox
                instead, and they finish it in the TikTok app: no
                `privacyLevel` needed, and the interaction and disclosure
                options don't apply.
              properties:
                draft:
                  type: boolean
                  description: >-
                    Send to the creator's TikTok inbox as a draft instead of
                    posting. Video drafts carry no caption; photo drafts keep
                    `title` and the caption. At most 5 pending drafts per
                    account in 24 hours.
                privacyLevel: { type: string, enum: [PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY] }
                allowComment: { type: boolean }
                allowDuet: { type: boolean }
                allowStitch: { type: boolean }
                commercialContent: { type: boolean, description: The content disclosure toggle. }
                yourBrand: { type: boolean, description: Promotes yourself or your business (Promotional content). }
                brandedContent: { type: boolean, description: Promotes a third party (Paid partnership); can't be SELF_ONLY. }
                aiGenerated: { type: boolean }
                title: { type: string, description: 'Photo posts: the title (90 characters).' }
                autoAddMusic: { type: boolean }
                videoCoverTimestampMs: { type: integer, minimum: 0 }
            youtube:
              type: object
              additionalProperties: false
              properties:
                title: { type: string, description: "Default: the caption's first line (100 characters)." }
                privacy: { type: string, enum: [public, unlisted, private] }
                madeForKids: { type: boolean }
                tags: { type: array, items: { type: string } }
                categoryId: { type: string, description: 'YouTube category id (default 22).' }
                aiGenerated: { type: boolean, description: Altered or synthetic content. }
            pinterest:
              type: object
              additionalProperties: false
              description: |
                The caption is the Pin's description (800 characters). Set
                `boardId` per account (`accounts[].options`) to pick a board.
              properties:
                boardId: { type: string, description: "The board (default: the account's first board)." }
                title: { type: string, maxLength: 100, description: The Pin's title. }
                link: { type: string, format: uri, maxLength: 2048, description: Where the Pin links to. }
                altText: { type: string, maxLength: 500 }
            bluesky:
              type: object
              additionalProperties: false
              description: Captions are limited to 300 graphemes; up to 4 images (2 MB each) or 1 video.
              properties:
                altText: { type: string, maxLength: 2000, description: Alt text for the images or the video. }
            buffer:
              type: object
              additionalProperties: false
              description: Buffer channels (docs/buffer.md).
              properties:
                mode:
                  type: string
                  enum: [queue, next, now, draft]
                  description: 'queue (default): the next free slot; next: first in the queue; now: at once; draft: a Buffer draft.'
                instagramType: { type: string, enum: [post, story, reel] }
                facebookType: { type: string, enum: [post, story, reel] }
                pinterestBoardId: { type: string, maxLength: 100, description: "Default: the channel's first board." }
                title: { type: string, maxLength: 100, description: Pinterest Pin title. }
                link: { type: string, format: uri, maxLength: 2048, description: Pinterest Pin link. }
                youtubeCategoryId: { type: string, description: 'YouTube category id (default 22).' }
        scheduledAt:
          type: string
          description: |
            ISO 8601. With `Z` or an offset it is absolute; without one it is
            read in `timezone`. Up to a year ahead; omit to post now.
          example: '2026-11-10T09:00'
        timezone: { type: string, description: 'IANA time zone, e.g. Europe/Paris (default UTC).' }
        draft: { type: boolean, description: Save without posting. }

    LinkedInPostOptions:
      type: object
      additionalProperties: false
      properties:
        firstComment: { type: string, maxLength: 1250, description: Posted as a comment right after the post. }
        documentTitle: { type: string, maxLength: 400, description: 'PDF document posts: the title.' }
        visibility: { type: string, enum: [PUBLIC, CONNECTIONS], description: 'Profiles only (default PUBLIC).' }

    SocialMedia:
      type: object
      required: [kind, contentType, url]
      properties:
        kind: { type: string, enum: [image, video, pdf] }
        contentType: { type: string }
        url:
          type: string
          description: The file. A rendered file is a fresh link on every read that works for an hour (`expiresAt`); uploads and fetched media are plain URLs.
        expiresAt:
          type: string
          format: date-time
          description: Rendered files only. When `url` stops working.
        bytes: { type: integer }
        width: { type: integer }
        height: { type: integer }
        durationSec: { type: number }
        pages: { type: integer }

    SocialPostTarget:
      type: object
      required: [id, platform, accountName, status, caption, warnings, attempts]
      description: One account of a post.
      properties:
        id: { type: string }
        accountId: { type: [string, 'null'], description: '`null` once the account was removed.' }
        platform: { $ref: '#/components/schemas/SocialPlatform' }
        accountName: { type: string }
        status: { type: string, enum: [draft, queued, rendering, publishing, published, failed, canceled] }
        caption: { type: string, description: The caption this account posts. }
        permalink: { type: [string, 'null'] }
        externalId: { type: [string, 'null'], description: The platform's id of the post. }
        error:
          oneOf:
            - type: 'null'
            - type: object
              required: [kind, code, message]
              properties:
                kind: { type: string, enum: [auth, transient, permanent, validation] }
                code: { type: string }
                message: { type: string }
          description: Why it failed; while a retry is pending, the last error.
        warnings: { type: array, items: { type: string } }
        attempts: { type: integer, description: Transient failures so far. }
        nextAttemptAt: { type: [string, 'null'], format: date-time }
        publishedAt: { type: [string, 'null'], format: date-time }

    SocialPost:
      type: object
      required: [id, status, caption, targets, createdAt]
      properties:
        id: { type: string }
        status: { type: string, enum: [draft, scheduled, queued, rendering, publishing, published, partial, failed, canceled] }
        caption: { type: string }
        captions: { type: object }
        options: { type: object }
        media:
          type: [array, 'null']
          items: { $ref: '#/components/schemas/SocialMedia' }
          description: The files posted; `null` until a render-and-post has rendered.
        mediaSource: { type: object, description: 'Where the media comes from: `render`, `render_id` or `urls`.' }
        renderJobId: { type: [string, 'null'] }
        renderId: { type: [string, 'null'] }
        scheduledAt: { type: [string, 'null'], format: date-time }
        timezone: { type: [string, 'null'] }
        source: { type: string, enum: [app, api, mcp] }
        error:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ApiError'
          description: When the media step (the render) failed.
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        finishedAt: { type: [string, 'null'], format: date-time }
        targets:
          type: array
          items: { $ref: '#/components/schemas/SocialPostTarget' }

    SocialTargetIssues:
      type: object
      required: [accountId, platform, accountName, errors, warnings]
      properties:
        accountId: { type: string }
        platform: { $ref: '#/components/schemas/SocialPlatform' }
        accountName: { type: string }
        errors:
          type: array
          items: { $ref: '#/components/schemas/SocialIssue' }
        warnings:
          type: array
          items: { $ref: '#/components/schemas/SocialIssue' }

    SocialIssue:
      type: object
      required: [level, code, message]
      properties:
        level: { type: string, enum: [error, warning] }
        code: { type: string, example: caption_too_long }
        message: { type: string }

    SocialPostEvent:
      type: object
      required: [post, target]
      description: '`data` of `social.post.*` events: the post, and the account whose result this is.'
      properties:
        post: { $ref: '#/components/schemas/SocialPost' }
        target: { $ref: '#/components/schemas/SocialPostTarget' }

    WorkflowDefinition:
      type: object
      description: |
        The steps, as JSON with a version. Step objects may carry an `id`
        (1–32 letters, digits, `_` or `-`); one is assigned otherwise.
        `{{Column}}` placeholders in `action.mapping`, social captions and
        Slack messages are filled from each row (`{{render.url}}` too in
        deliveries). Secret fields (`source.token`, a Slack step's
        `webhookUrl`) are write-only: responses show `{ set: true, tail }`;
        send that back to keep the stored value, or `""` to clear it.
      required: [version, trigger, source, action]
      properties:
        version: { type: integer, enum: [1] }
        trigger:
          type: object
          required: [kind]
          description: |
            `manual`; `schedule` with `frequency` (`hourly` + `minute`;
            `daily`/`weekly`/`monthly` + `time` "HH:MM", `dayOfWeek` 0–6,
            `dayOfMonth` 1–28; `custom` + a 5-field `cron`, at most every
            15 minutes) and an IANA `timezone`; `webhook`; or `new_rows`
            with `intervalMinutes` (15, 30, 60, 180, 360, 720 or 1440).
          properties:
            kind: { type: string, enum: [manual, schedule, webhook, new_rows] }
            frequency: { type: string, enum: [hourly, daily, weekly, monthly, custom] }
            minute: { type: integer, minimum: 0, maximum: 59 }
            time: { type: string, pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$' }
            dayOfWeek: { type: integer, minimum: 0, maximum: 6 }
            dayOfMonth: { type: integer, minimum: 1, maximum: 28 }
            cron: { type: string, maxLength: 120 }
            timezone: { type: string, maxLength: 64 }
            intervalMinutes: { type: integer, enum: [15, 30, 60, 180, 360, 720, 1440] }
        source:
          type: object
          required: [kind]
          description: |
            `google_sheets` (`url`, `sheet`?, `connectionId`? for a private
            sheet), `file_url` (`url` of a CSV or XLSX file, `format`
            auto/csv/xlsx, `sheet`?), `airtable` (`baseId`, `table`,
            `view`?, `token`), `drive_folder` (`folder`, `connectionId`) or
            `webhook` (the incoming webhook's payload).
          properties:
            kind: { type: string, enum: [google_sheets, file_url, airtable, drive_folder, webhook] }
            url: { type: string, maxLength: 2048 }
            sheet: { type: string, maxLength: 200 }
            format: { type: string, enum: [auto, csv, xlsx] }
            baseId: { type: string, maxLength: 40 }
            table: { type: string, maxLength: 200 }
            view: { type: string, maxLength: 200 }
            token:
              description: Write-only Airtable personal access token.
              oneOf:
                - { type: string, maxLength: 1000 }
                - $ref: '#/components/schemas/WorkflowSecret'
            folder: { type: string, maxLength: 2048 }
            connectionId: { type: string, maxLength: 64 }
        transforms:
          type: array
          maxItems: 10
          items:
            type: object
            required: [kind]
            description: |
              `filter` (`column`, `operator`: equals, not_equals, contains,
              not_contains, starts_with, is_empty, not_empty, greater_than,
              less_than; `value`), `sort` (`column`, `direction`),
              `limit` (`count`), `pick` (`which`: first/last/random,
              `count`), `dedupe` (`column`? else the whole row).
            properties:
              kind: { type: string, enum: [filter, sort, limit, pick, dedupe] }
              column: { type: string, maxLength: 200 }
              operator: { type: string }
              value: { type: string, maxLength: 500 }
              direction: { type: string, enum: [asc, desc] }
              count: { type: integer, minimum: 1, maximum: 10000 }
              which: { type: string, enum: [first, last, random] }
        action:
          type: object
          required: [kind, templateId]
          properties:
            kind: { type: string, enum: [render] }
            templateId: { type: string, maxLength: 64 }
            mapping:
              type: object
              description: Template parameter → value with `{{Column}}` placeholders.
              additionalProperties: { type: string, maxLength: 5000 }
            format: { type: string, enum: [png, jpeg, webp, pdf, mp4] }
            scale: { type: integer, minimum: 1, maximum: 3 }
            quality: { type: integer, minimum: 1, maximum: 100 }
            includePages:
              type: array
              items: { type: integer, minimum: 1 }
        deliver:
          type: array
          maxItems: 6
          items:
            type: object
            required: [kind]
            description: |
              `url`; `webhook` (`url`: each row POSTed as JSON, event
              `workflow.row.rendered`); `slack` (`webhookUrl`, `message`?);
              `social` (`accountIds`, `caption`?, `when`: now/schedule/draft,
              `scheduledAt`?, `timezone`?); `sheets_writeback` (`column`,
              `connectionId`); `drive_upload` (`folder`: a folder name this
              app creates in My Drive, or a link to one it created;
              `connectionId`); `s3_upload` (`provider`?: `aws` (default)
              or `r2`; `bucket`; `region` for S3; `accountId` and
              `jurisdiction`? for Cloudflare R2; `accessKeyId`,
              `secretAccessKey`; `key`?: the path and file name, with
              `{{Column}}`, `{{render.id}}`, `{{row.number}}` and
              `{{run.date}}` placeholders; default `renders/{{render.id}}`;
              the extension is added).
            properties:
              kind: { type: string, enum: [url, webhook, slack, social, sheets_writeback, drive_upload, s3_upload] }
              url: { type: string, maxLength: 2048 }
              webhookUrl:
                description: Write-only Slack incoming webhook URL.
                oneOf:
                  - { type: string, maxLength: 1000 }
                  - $ref: '#/components/schemas/WorkflowSecret'
              message: { type: string, maxLength: 3000 }
              provider: { type: string, enum: [aws, r2], description: 'Amazon S3 (default) or Cloudflare R2 (`s3_upload`).' }
              bucket: { type: string, maxLength: 63, description: 'Bucket name (`s3_upload`).' }
              accountId: { type: string, maxLength: 64, description: 'Cloudflare account ID, 32 characters (`s3_upload` with `provider: r2`).' }
              jurisdiction: { type: string, enum: [default, eu], description: 'R2 bucket jurisdiction (`s3_upload` with `provider: r2`).' }
              region: { type: string, maxLength: 32, description: 'The bucket''s AWS region, e.g. `us-east-1` (`s3_upload` with Amazon S3; ignored for R2).' }
              key: { type: string, maxLength: 1024, description: 'The object''s path and file name, without the extension (`s3_upload`).' }
              accessKeyId: { type: string, maxLength: 128, description: 'An IAM user''s access key ID allowed s3:PutObject on the bucket, or an R2 API token''s access key ID (`s3_upload`).' }
              secretAccessKey:
                description: Write-only secret access key of the S3 or R2 key (`s3_upload`).
                oneOf:
                  - { type: string, maxLength: 128 }
                  - $ref: '#/components/schemas/WorkflowSecret'
              accountIds:
                type: array
                maxItems: 25
                items: { type: string }
              caption: { type: string, maxLength: 10000 }
              when: { type: string, enum: [now, schedule, draft] }
              scheduledAt: { type: string, maxLength: 200 }
              timezone: { type: string, maxLength: 64 }
              column: { type: string, maxLength: 200 }
              folder: { type: string, maxLength: 2048 }
              connectionId: { type: string, maxLength: 64 }
    WorkflowSecret:
      type: object
      description: A stored secret, shown masked.
      required: [set]
      properties:
        set: { type: boolean, enum: [true] }
        tail: { type: string, description: The last 4 characters. }
    WorkflowCreate:
      type: object
      properties:
        name: { type: string, minLength: 1, maxLength: 120 }
        description: { type: [string, 'null'], maxLength: 2000 }
        definition: { $ref: '#/components/schemas/WorkflowDefinition' }
        starter:
          type: string
          description: An Explore starter's id, e.g. `csv-quotes-webhook`.
    WorkflowUpdate:
      type: object
      properties:
        name: { type: string, minLength: 1, maxLength: 120 }
        description: { type: [string, 'null'], maxLength: 2000 }
        definition: { $ref: '#/components/schemas/WorkflowDefinition' }
        status: { type: string, enum: [draft, active] }
    WorkflowRunRequest:
      type: object
      properties:
        payload:
          description: Rows for a webhook-payload source (an array of objects, or one object).
        maxRows:
          type: integer
          minimum: 1
          maximum: 10000
          description: Render only the first N rows (a test run).
    Workflow:
      type: object
      required: [id, name, status, definition, steps, problems, trigger, createdAt, updatedAt]
      properties:
        id: { type: string }
        name: { type: string }
        description: { type: [string, 'null'] }
        status: { type: string, enum: [draft, active] }
        definition: { $ref: '#/components/schemas/WorkflowDefinition' }
        steps: { type: integer, description: 'Steps as the plan counts them.' }
        problems:
          type: array
          description: What stops it from running (empty when ready).
          items:
            type: object
            required: [stepId, message]
            properties:
              stepId: { type: string }
              message: { type: string }
        trigger:
          type: object
          required: [kind, summary]
          properties:
            kind: { type: string }
            summary: { type: string, example: 'Every day at 09:00 (Europe/Paris)' }
        nextRunAt: { type: [string, 'null'], format: date-time }
        lastRunAt: { type: [string, 'null'], format: date-time }
        lastRun:
          oneOf:
            - $ref: '#/components/schemas/WorkflowRun'
            - type: 'null'
        webhookUrl:
          type: [string, 'null']
          format: uri
          description: The incoming webhook URL (webhook trigger only). Anyone with it can start runs.
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    WorkflowRun:
      type: object
      required: [id, workflowId, trigger, status, rowsTotal, rowsSucceeded, rowsFailed, rowsSkipped, credits, warnings, createdAt]
      properties:
        id: { type: string }
        workflowId: { type: string }
        trigger: { type: string, enum: [manual, schedule, webhook, new_rows, api, mcp] }
        status: { type: string, enum: [queued, running, succeeded, partial, failed, canceled] }
        rowsTotal: { type: integer }
        rowsSucceeded: { type: integer }
        rowsFailed: { type: integer }
        rowsSkipped: { type: integer }
        credits: { type: integer, description: Render credits the run's renders cost. }
        error:
          type: [object, 'null']
          properties:
            code: { type: string, example: QUOTA_EXCEEDED }
            message: { type: string }
        warnings:
          type: array
          items: { type: string }
        createdAt: { type: string, format: date-time }
        startedAt: { type: [string, 'null'], format: date-time }
        finishedAt: { type: [string, 'null'], format: date-time }
    WorkflowRunEvent:
      description: The `data` of `workflow.run.completed` and `workflow.run.failed` events.
      allOf:
        - $ref: '#/components/schemas/WorkflowRun'
        - type: object
          required: [workflowName]
          properties:
            workflowName: { type: string, description: The workflow's name when the run ended. }
    WorkflowRunRow:
      type: object
      required: [index, status, values, urls, credits, deliveries]
      properties:
        index: { type: integer }
        status: { type: string, enum: [pending, running, succeeded, partial, failed, skipped] }
        values:
          type: object
          additionalProperties: { type: string }
        rowNumber: { type: [integer, 'null'], description: Google Sheets row number. }
        modifications:
          type: [object, 'null']
          additionalProperties: { type: string }
        renderId: { type: [string, 'null'] }
        urls:
          type: array
          items: { type: string, format: uri }
          description: |
            The row's rendered files, as fresh links on every read that work
            for an hour. Files are deleted 8 days after the render.
        credits: { type: integer }
        deliveries:
          type: array
          items:
            type: object
            required: [stepId, kind, status]
            properties:
              stepId: { type: string }
              kind: { type: string }
              status: { type: string, enum: [succeeded, failed, sandbox] }
              message: { type: string }
              url: { type: string }
        error:
          type: [object, 'null']
          properties:
            code: { type: string }
            message: { type: string }
  responses:
    AnalyticsBadQuery:
      description: A malformed date, a range in the wrong order or over 366 days, or an unknown platform.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          example: { error: VALIDATION_ERROR, message: 'from must be on or before to' }
    Unauthorized:
      description: |
        Missing, malformed, expired or revoked API key, or the key's
        creator is suspended or no longer has editor access to the
        workspace.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          examples:
            missing:
              value: { error: MISSING_API_KEY, message: Missing Authorization header }
            invalid:
              value: { error: INVALID_API_KEY, message: Invalid API key }
            expired:
              value: { error: EXPIRED_API_KEY, message: API key has expired }
    Forbidden:
      description: |
        The organization is on hold (`ORG_ON_HOLD`: reads still work,
        changes and renders are refused) or suspended (`ORG_SUSPENDED`:
        everything is refused).
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          examples:
            onHold:
              value:
                error: ORG_ON_HOLD
                message: This organization is on hold while we review recent activity. You can still view everything, but changes are paused.
            suspended:
              value:
                error: ORG_SUSPENDED
                message: This organization has been suspended.
    RenderedFile:
      description: The rendered file.
      headers:
        Cache-Control:
          description: '`public, max-age=<seconds>`: the cache time, at most one hour (dynamic URLs) or one day (signed URLs) and never past the URL''s expiry (`no-cache` when the cache time is 0).'
          schema: { type: string }
        ETag:
          description: Strong validator of the file's bytes; send it back in `If-None-Match` for a `304`.
          schema: { type: string }
        X-Render-Cache:
          description: '`HIT` (served from the render cache, free) or `MISS` (rendered now).'
          schema: { type: string, enum: [HIT, MISS] }
      content:
        image/png:
          schema: { type: string, format: binary }
        image/jpeg:
          schema: { type: string, format: binary }
        image/webp:
          schema: { type: string, format: binary }
        application/pdf:
          schema: { type: string, format: binary }
    PublicError:
      description: |
        A public render URL that can't be served, with `Cache-Control:
        no-store`:

        | Status | `error` | When |
        | --- | --- | --- |
        | 400 | `INVALID_PARAMETERS` | A query parameter or modification is invalid, an image URL isn't a public http(s) address, or the output would be over the pixel cap. |
        | 402 | `CREDIT_CAP_REACHED` | A dynamic URL's credit cap is used up (cached parameters are still served). |
        | 402 | `CREDITS_EXHAUSTED` | The workspace has no credits left. |
        | 403 | `INVALID_SIGNATURE` | A signed URL was changed, or its key was rotated. |
        | 403 | `UNAVAILABLE` | The account is on hold or suspended. |
        | 404 | `NOT_FOUND` | No such URL, or the template was deleted. |
        | 410 | `URL_EXPIRED` | The URL's expiry has passed. |
        | 410 | `URL_DISABLED` | The dynamic URL was turned off. |
        | 422 | `MEDIA_UNAVAILABLE` | An image could not be loaded (or its host resolves to a private address). |
        | 429 | `RATE_LIMITED` | Too many requests, or the URL's renders keep failing and it is paused for a while (see `Retry-After`). |
        | 500 | `RENDER_FAILED` | The render failed. |
        | 503 | `BUSY` | Too many renders in progress, for the server, the workspace or this URL (see `Retry-After`). |
      content:
        application/json:
          schema: { $ref: '#/components/schemas/PublicUrlError' }
          examples:
            expired:
              value: { error: URL_EXPIRED, message: This link has expired. }
            cap:
              value: { error: CREDIT_CAP_REACHED, message: This link has used its credit allowance. }
            tampered:
              value: { error: INVALID_SIGNATURE, message: This link is not valid. }
    PublicFormFailure:
      description: |
        A public form request that can't be served, with `Cache-Control:
        no-store`:

        | Status | `error` | When |
        | --- | --- | --- |
        | 400 | `INVALID_VALUES` | An answer is missing or invalid (`fields` names each), or the output would be over the pixel cap. |
        | 400 | `INVALID_REQUEST` | The body isn't valid JSON (or couldn't be read). |
        | 400 | `CAPTCHA_FAILED` | The Turnstile token (or, on upload, the upload pass) is missing or was refused. |
        | 400 | `UPLOAD_INVALID` | Not a PNG, JPEG, WebP or GIF, too many pixels, or not an upload field. |
        | 402 | `CREDIT_CAP_REACHED` | The form's credit cap is used up (uploads: no room for one more render). |
        | 402 | `CREDITS_EXHAUSTED` | The owner's workspace has no credits left. |
        | 403 | `UNAVAILABLE` | The owner's account is on hold or suspended. |
        | 404 | `NOT_FOUND` | No such form, or its template was deleted, or not a file handle of this form. |
        | 410 | `FORM_DISABLED` | The owner turned the form off. |
        | 410 | `FORM_EXPIRED` | The form's expiry has passed. |
        | 410 | `FILE_EXPIRED` | The result file was deleted (7 days after the render). |
        | 413 | `UPLOAD_TOO_LARGE` | The upload is over 10 MB. |
        | 413 | `BODY_TOO_LARGE` | The JSON body is over 256 kB. |
        | 415 | `UNSUPPORTED_MEDIA_TYPE` | The body uses an unsupported charset or encoding. |
        | 422 | `MEDIA_UNAVAILABLE` | An image could not be loaded (or its host resolves to a private address). |
        | 429 | `RATE_LIMITED` | Too many requests, too many uploads to this form, or the form's renders keep failing and it is paused for a while (see `Retry-After`). |
        | 500 | `RENDER_FAILED` | The render failed. |
        | 503 | `BUSY` / `UPLOADS_UNAVAILABLE` / `CAPTCHA_UNAVAILABLE` | Too many renders in progress (see `Retry-After`), uploads are off, or the server has no bot check configured. |
      content:
        application/json:
          schema: { $ref: '#/components/schemas/PublicFormError' }
          examples:
            invalid:
              value: { error: INVALID_VALUES, message: Some answers need attention., fields: { headline: Required. } }
            disabled:
              value: { error: FORM_DISABLED, message: This form has been turned off. }
            cap:
              value: { error: CREDIT_CAP_REACHED, message: This form has reached its limit. }
    NotFound:
      description: The requested resource was not found in this workspace.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          examples:
            template:
              value: { error: NOT_FOUND, message: Template clx8m2k3p0002abcd1234efgh not found in this workspace }
    RateLimited:
      description: |
        Too many requests for this organization (or endpoint). Honour the `Retry-After`
        response header (seconds) or the `detail.retryAfter` field.
      headers:
        Retry-After:
          description: Seconds until the next request will succeed.
          schema: { type: integer }
        RateLimit:
          description: |
            The current window (IETF rate-limit headers, draft 7), sent on
            every authenticated response: `limit=100, remaining=0, reset=42`
            (requests per window, requests left, seconds until it resets).
          schema: { type: string }
          example: 'limit=100, remaining=0, reset=42'
        RateLimit-Policy:
          description: The limit and the window length in seconds (`100;w=60`), sent on every authenticated response.
          schema: { type: string }
          example: '100;w=60'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          examples:
            default:
              value:
                error: RATE_LIMITED
                message: Rate limit exceeded. Retry after 30 seconds.
                detail: { retryAfter: 30 }
    VideoUnavailable:
      description: |
        The request renders MP4, and MP4 video is turned off on this
        server (`VIDEO_UNAVAILABLE`). Render png, jpeg, webp or pdf
        instead. Nothing was queued and no credits were charged.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          example:
            error: VIDEO_UNAVAILABLE
            message: 'MP4 video is turned off on this server. Render png, jpeg, webp or pdf instead. No credits were charged.'
    PaymentRequired:
      description: |
        Not enough credits. `QUOTA_EXCEEDED` means the organization's plan
        is used up for this period (or the subscription isn't active);
        `WORKSPACE_QUOTA_EXCEEDED` means this workspace has reached the
        cap an organization admin set for it; `AI_CREDITS_EXCEEDED` (renders
        with AI layers or `translate`, and AI endpoints) means the
        organization's AI credits are used up. No credits are charged.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          examples:
            quota:
              value:
                error: QUOTA_EXCEEDED
                message: 'Quota exceeded: requested 3, remaining 1 of 100'
                detail:
                  planCode: free
                  used: 99
                  quotaPerPeriod: 100
                  requested: 3
                  remaining: 1
                  periodEnd: '2027-01-01T00:00:00.000Z'
            workspaceCap:
              value:
                error: WORKSPACE_QUOTA_EXCEEDED
                message: 'Workspace quota exceeded: requested 3, remaining 0 of 500'
                detail:
                  limit: 500
                  used: 500
                  requested: 3
                  remaining: 0
                  periodEnd: '2027-01-01T00:00:00.000Z'
    ValidationError:
      description: |
        The request body or query was invalid: a malformed body, a page
        that doesn't exist (`includePages` or a `pageN@` key), a style
        property the layer type doesn't support, a non-numeric value for a
        numeric property, more than 20 pages, or a video longer than the
        plan allows (30 seconds on Free, 60 on paid plans).
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          examples:
            badBody:
              value:
                error: VALIDATION_ERROR
                message: Invalid render request
                detail:
                  issues:
                    - code: invalid_type
                      path: [templateId]
                      message: 'Invalid input: expected string, received undefined'
            badPage:
              value:
                error: VALIDATION_ERROR
                message: 'includePages: the template has 3 page(s)'
                detail: { missing: [4] }
            badProperty:
              value:
                error: VALIDATION_ERROR
                message: '"photo.color": "color" can''t be set on a image layer'
    RenderFailed:
      description: The renderer failed. No credits were charged; retrying is safe.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          examples:
            default:
              value:
                error: INTERNAL
                message: The render failed. No credits were charged.
    WebhookUrlInvalid:
      description: |
        The webhook URL failed validation (a private or loopback address,
        an unsupported scheme, or not a URL), or `events` was empty or
        held an unknown event type.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          examples:
            private:
              value:
                error: WEBHOOK_URL_INVALID
                message: url must not target a private host
            scheme:
              value:
                error: WEBHOOK_URL_INVALID
                message: url must use https://
            events:
              value:
                error: VALIDATION_ERROR
                message: 'Unknown event type "design.published". Supported: design.created, design.updated, design.deleted, render.completed, render.failed, social.post.published, social.post.failed.'
                detail: { field: events }
    WebhookLimitReached:
      description: |
        The workspace has reached the cap of 20 webhook subscriptions.
        Delete an unused subscription and try again.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
          examples:
            default:
              value:
                error: WEBHOOK_LIMIT_REACHED
                message: 'Each workspace can have at most 20 webhook subscriptions. Delete an unused subscription and try again.'
                detail: { limit: 20, current: 20 }
