Shared types and security

Look up shared request and response fields, error types, response headers, and API authentication schemes.

See all API resources or read the PDF generation API guide.

Schemas

AiProgressStage

Schema rules: {"type":"object","additionalProperties":false}.

AiProgress

Measured stages and elapsed time. Estimates use at least five successful requests from the last 48 hours for the same model route and task. Unknown routes have no estimate.

Schema rules: {"type":"object","additionalProperties":false}.

FieldDetail

One request field that failed, its fixed safe reason, and an optional bounded source location. Details never carry template source, customer values, rendered output, or raw evaluator prose.

Schema rules: {"type":"object","additionalProperties":false}.

BrandKitId

Schema rules: {"type":"string","pattern":"^kit_[0-9a-f]{32}$"}.

TemplateMessageId

Schema rules: {"type":"string","pattern":"^msg_[0-9a-f]{32}$"}.

TemplateMessageInput

Schema rules: {"oneOf":[{"type":"object","properties":{"type":{"const":"prompt"},"prompt":{"type":"string","minLength":1,"maxLength":65536}},"required":["type","prompt"],"additionalProperties":false},{"type":"object","properties":{"type":{"const":"html"},"html":{"type":"string","minLength":1,"maxLength":65536},"prompt":{"type":"string","maxLength":65536}},"required":["type","html"],"additionalProperties":false,"description":"HTML plus optional written instructions, at most 65536 UTF-8 bytes together."},{"type":"object","description":"Use a still PNG, JPEG, or WebP to rebuild its layout or guide a written request. Reference images require a nonempty prompt. At most 10 MiB, 7680 by 4320, 32 million pixels, and 64 MiB decoded. Invalid files fail before the model.","properties":{"type":{"const":"image"},"base64":{"type":"string","minLength":1,"maxLength":13981016,"contentEncoding":"base64"},"purpose":{"type":"string","enum":["rebuild","reference"]},"prompt":{"type":"string","maxLength":65536}},"required":["type","base64","purpose"],"additionalProperties":false,"allOf":[{"if":{"properties":{"purpose":{"const":"reference"}}},"then":{"required":["prompt"],"properties":{"prompt":{"minLength":1,"pattern":"\\S"}}}}]},{"type":"object","description":"Your own working template, sent as data. It must pass the saved-template checks and evaluate with sample_data. It becomes the draft without a model call and costs 0 credits.","properties":{"type":{"const":"source"},"source":{"type":"string","minLength":1,"maxLength":1048576},"sample_data":{"type":"object"},"schema":{"oneOf":[{"type":"object"},{"type":"boolean"}]}},"required":["type","source"],"additionalProperties":false}]}.

TemplateOutputIntent

Schema rules: {"oneOf":[{"type":"object","description":"Let the model choose PDF or image from the message. An image result from a source image uses the source dimensions.","properties":{"type":{"const":"auto"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"const":"pdf"}},"required":["type"],"additionalProperties":false},{"type":"object","description":"Request an image. Explicit width and height take priority. Otherwise source-image dimensions or the model’s resolved image dimensions are used. The initial fallback is 1200 by 628 when neither supplies a size.","properties":{"type":{"const":"image"},"format":{"type":"string","enum":["png","jpeg","webp"],"default":"png"},"width":{"type":"integer","minimum":320,"maximum":7680},"height":{"type":"integer","minimum":200,"maximum":4320}},"required":["type"],"additionalProperties":false}]}.

TemplateOutput

Schema rules: {"oneOf":[{"type":"object","properties":{"type":{"const":"pdf"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"const":"image"},"format":{"type":"string","enum":["png","jpeg","webp"]},"width":{"type":"integer","minimum":320,"maximum":7680},"height":{"type":"integer","minimum":200,"maximum":4320}},"required":["type","format","width","height"],"additionalProperties":false}]}.

TemplateMessage

Schema rules: {"type":"object","additionalProperties":false}.

TemplateChat

The AI chat of one template. A template has at most one chat.

Schema rules: {"type":"object","additionalProperties":false}.

TemplateId

Schema rules: {"type":"string","pattern":"^tpl_[0-9a-f]{32}$"}.

ArchivePeriod

Schema rules: {"type":"object","additionalProperties":false}.

FileExpiryChange

The file's new end, in days from the job's created_at.

Schema rules: {"type":"object","additionalProperties":false}.

TemplatePdfPage

The printed PDF page of a saved template, such as 85mm by 55mm. A PDF render of the template with no format, width, or height uses this page, and the design scales to fit it. Without a page, the render uses the canvas size, or A4 when the source has no canvas.

Schema rules: {"type":"object","additionalProperties":false}.

TemplateVersionDetail

Schema rules: {"type":"object","additionalProperties":false}.

SizeVariant

One saved canvas size for a template version. docs/SMART-RESIZE.md owns the rules.

Schema rules: {"type":"object","additionalProperties":false}.

SizeVariantList

Schema rules: {"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/SizeVariant"}}. See SizeVariant.

PlanLimitInfo

Present when the account's plan causes the refusal: brand_kit_limit and batch_row_limit. It names the limit and the plan that sets it, so a caller can act without a second request. The message text never names the number.

Schema rules: {"type":"object","additionalProperties":false}.

RetryInfo

How long the caller must wait before it retries.

Schema rules: {"type":"object","additionalProperties":false}.

ErrorEnvelope

The one error shape every backend response uses.

Schema rules: {"type":"object","additionalProperties":false}.

Headers and security

XRequestId

{
  "description": "The UUID that identifies this request and matches error.request_id on an error response.",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}

sessionCookie

{
  "type": "apiKey",
  "in": "cookie",
  "name": "__Host-thirds_session",
  "description": "A browser session. Browser writes also require the matching x-csrf-token header from GET /v1/me."
}

bearerAuth

{
  "type": "http",
  "scheme": "bearer",
  "description": "An API key's secret, sent as \"Authorization: Bearer thirds_sk_v1_...\"."
}