# MintRender

> MintRender turns a template plus data into a finished image (PNG, JPEG, WebP, SVG) or PDF, through an API, signed image links, bulk jobs from a CSV, no-code tools and an MCP server for AI assistants.

- 1 image or 1 PDF page = 1 credit. The same template version and the same data again gives the same file, at no cost (`cached: true`).
- Auth: `Authorization: Bearer mr_live_…` (or `mr_test_…`: watermark, no cost). Base URL: https://mintrender.com/v1
- Errors are JSON: `{"error": {"code", "message", "field", "request_id"}}`; `field` names the bad value, like `data.title.color`.
- Formats: PNG, JPEG, WebP, SVG and PDF from one template. PDF text is real text: people can select, copy and search it.
- No code needed: design in the browser editor, then fill the template from n8n, Make, a CSV file, a Google Sheet, or Claude and ChatGPT over MCP.
- Previews, repeats of the same file, test keys and failed renders cost no credits.

## Signed links

`https://img.mintrender.com/{template}/{size}.{png|jpg|webp|svg|pdf}?{param}={value}&…&s={sig}`

sig = base64url (no padding) of the first 16 bytes of HMAC-SHA256(workspace link key, the string `{path}?{k1}={v1}&{k2}={v2}…`), where the query has every parameter except `s`, keys and values encoded as RFC 3986 (encodeURIComponent, plus `!'()*`), sorted by key, then value. Views of a file that exists are free; a new input costs one credit (one per page for a PDF).

## Endpoints

### GET /healthz

Health check

No API key needed.

Answers:
- 200: The API is up

### GET /v1/templates

List templates

Needs an API key.

Answers:
- 200: The workspace's templates, newest first
- 401: No API key, or the key is not valid
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/templates

Create a template from a scene

Needs an API key.

JSON body:
- `name` (string, required)
- `scene` (Scene, required)

Answers:
- 201: The new template (a draft; publish it to render it)
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 402: A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
- 413: Too large
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/templates/generate

Make a draft template from a description (AI)

The AI template maker (spec 11.3). The result is a draft that the validator accepts; it is never published by itself. Limits: the plan's AI templates a month, and a daily cap for the whole service.

Needs an API key.

JSON body:
- `description` (string, required)
- `size` (string, default "1200x630")
- `name` (string)

Answers:
- 201: The new draft template
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 402: A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
- 422: The request cannot be done; `code` says why (for example an Idempotency-Key used with a different body)
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)
- 502: A service we use failed; try again
- 503: Not available now: a set-up step is missing, or a daily limit is reached; `code` says which
- 504: A service we use took too long; try again

### GET /v1/templates/{id}

Get a template, its params and versions

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: The template
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### DELETE /v1/templates/{id}

Delete a template

Signed links and renders of it stop at once (404). Files already made stay until they expire. The template no longer counts toward the plan's limit.

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: Deleted
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### PUT /v1/templates/{id}/draft

Save the draft scene

Needs an API key.

Parameters:
- `id` (path, string, required)

JSON body:
- `scene` (Scene, required)
- `name` (string)

Answers:
- 200: The template with the new draft
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 404: Not found
- 413: Too large
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/templates/{id}/publish

Publish the draft as a new version

Signed links and renders without a `version` use the newest published version.

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: The new version
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 404: Not found
- 409: Conflict
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/templates/{id}/duplicate

Copy a template (its draft)

Needs an API key.

Parameters:
- `id` (path, string, required)

JSON body:
- `name` (string)

Answers:
- 201: The copy
- 401: No API key, or the key is not valid
- 402: A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/assets

Upload an image or CSV

Send `multipart/form-data` with a `file` (and an optional `name`), or JSON `{"url": "https://…"}` to fetch it. Images: PNG, JPEG, GIF, WebP, SVG up to 20 MB and 16 megapixels (bigger ones are refused with `image_too_large`; the editor makes them smaller before it uploads them). CSV: UTF-8 up to 5 MB. A workspace stores up to 500 MB of files on Free and 10 GB on paid plans.

Needs an API key.

JSON body:
- `url` (string, required)
- `name` (string)

Answers:
- 201: The stored asset
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 402: A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
- 413: Too large
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### GET /v1/assets

List assets

Needs an API key.

Parameters:
- `kind` (query, "image" | "csv")

Answers:
- 200: Newest first, at most 500
- 401: No API key, or the key is not valid
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### GET /v1/assets/{id}/uses

Templates that use an asset

For a confirm step before a delete: the templates whose draft or a saved version uses the asset. A delete is refused (409) while a saved version uses it.

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: At most 100
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### DELETE /v1/assets/{id}

Delete an asset

Refused (409 `in_use`) while a saved version of a template that is not deleted uses it. GET /v1/assets/{id}/uses lists the templates.

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: Deleted
- 401: No API key, or the key is not valid
- 404: Not found
- 409: Conflict
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/render

Render a template

Renders each size as one file. 1 image or 1 PDF page = 1 credit; files that already exist for the same input answer at once (`cached: true`) and cost nothing. `mode: async` (or a PDF over 10 pages, or more than 5 sizes) answers 202 with a job to poll. `?inline=1` (one output) streams the bytes.

Needs an API key.

Parameters:
- `inline` (query, "0" | "1")
- `idempotency-key` (header, string): Send the same key again within 24 hours to get the first answer without a second charge

JSON body:
- `template` (string, required)
- `version` (integer): Default: the newest published version
- `data` (object)
- `ignore_unknown` (boolean): Skip data keys that match no param instead of a 400
- `format` ("png" | "jpg" | "webp" | "svg" | "pdf", default "png")
- `sizes` (string[], default ["main"])
- `scale` (number, default 1)
- `quality` (integer, default 90)
- `mode` ("sync" | "async", default "sync")
- `webhook_url` (string)
- `metadata` (object): Your own values, returned with the render (at most 4 KB)

Answers:
- 200: The finished render (with ?inline=1: the file itself)
- 202: Queued as a job
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 402: A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
- 404: Not found
- 409: Conflict
- 413: Too large
- 422: The request cannot be done; `code` says why (for example an Idempotency-Key used with a different body)
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### DELETE /v1/renders/{id}

Cancel a queued job

Only a job that has not started can be canceled; its credits come back.

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: The canceled job
- 401: No API key, or the key is not valid
- 404: Not found
- 409: Conflict
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### GET /v1/renders/{id}

Get a render or job

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: The render
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/batch

Render many rows

Up to 10,000 rows of data (from `rows`, an uploaded CSV or a CSV link). Credits for every row are reserved at once; failed rows give theirs back. Poll GET /v1/batch/{id}, or give a webhook_url.

Needs an API key.

JSON body:
- `template` (string, required)
- `version` (integer)
- `format` ("png" | "jpg" | "webp" | "svg" | "pdf", default "png")
- `sizes` (string[], default ["main"])
- `scale` (number, default 1)
- `quality` (integer, default 90)
- `rows` (object[])
- `csv_asset` (string): An uploaded CSV (asset id); the header row gives the param names
- `csv_url` (string): A public CSV link, for example a Google Sheet published as CSV
- `ignore_unknown` (boolean)
- `zip` (boolean, default false): Also build one ZIP of all files
- `webhook_url` (string)

Answers:
- 202: Queued
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 402: A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
- 404: Not found
- 409: Conflict
- 413: Too large
- 422: The request cannot be done; `code` says why (for example an Idempotency-Key used with a different body)
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### GET /v1/batch/{id}

Get a batch: counts and each row's render

Needs an API key.

Parameters:
- `id` (path, string, required)
- `offset` (query, integer | null)
- `limit` (query, integer)

Answers:
- 200: The batch
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### GET /v1/batch/{id}/zip

Download a batch's ZIP

The ZIP of a batch sent with `zip: true`, once the batch shows a `zip_url`. 404 while it is not ready, and after it expires with the batch's files (the last of its renders): `zip_url` is then null again.

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: The ZIP file
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/webhooks

Add a webhook

Events are POSTed as JSON with `MR-Signature: t={unix},v1={hex HMAC-SHA256(secret, t + "." + body)}`. The secret is shown only in this answer.

Needs an API key.

JSON body:
- `url` (string, required)
- `events` ("render.succeeded" | "render.failed" | "batch.completed"[], default ["render.succeeded","render.failed","batch.completed"])

Answers:
- 201: The webhook and its secret
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### GET /v1/webhooks

List webhooks

Needs an API key.

Answers:
- 200: Webhooks
- 401: No API key, or the key is not valid
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### DELETE /v1/webhooks/{id}

Delete a webhook

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: Deleted
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### GET /v1/deliveries

Recent webhook deliveries (every try)

Needs an API key.

Parameters:
- `render` (query, string)
- `limit` (query, integer)

Answers:
- 200: Newest first
- 401: No API key, or the key is not valid
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/deliveries/{id}/resend

Send a delivery again

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: The new delivery (tried now; retried like any other)
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### GET /v1/usage

Credits and renders this period

Needs an API key.

Answers:
- 200: Usage
- 401: No API key, or the key is not valid
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/preview

A free low-res preview with a watermark

Send a `scene` (no key needed; free tools and the docs use this) or, with an API key, a `template`. The answer is the image itself, at most 600 px on its long side. 30 a minute.

No API key needed.

JSON body:
- `template` (string)
- `scene` (Scene)
- `data` (object)
- `size` (string, default "main")
- `format` ("png" | "jpg" | "webp", default "png")
- `cf-turnstile-response` (string)

Answers:
- 200: The image
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 403: Not allowed
- 404: Not found
- 413: Too large
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### GET /v1/assets/{id}/file

Download an asset's file

The uploaded file itself, with its own type (a cleaned SVG for SVG uploads).

Needs an API key.

Parameters:
- `id` (path, string, required)

Answers:
- 200: The file
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

### POST /v1/links

Make a signed link

A link that renders the template when it is opened (spec 7.2). Data values are strings; at most 2,048 characters each.

Needs an API key.

JSON body:
- `template` (string, required)
- `size` (string, default "main")
- `format` ("png" | "jpg" | "webp" | "svg" | "pdf", default "png")
- `data` (object, default {}): Values are strings in a link

Answers:
- 200: The link
- 400: The request is not valid; `field` names the problem
- 401: No API key, or the key is not valid
- 404: Not found
- 429: Too many requests; see Retry-After
- 451: The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)
- 503: Not available now: a set-up step is missing, or a daily limit is reached; `code` says which