openapi.sdk.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "pdfrender",
    "description": "HTML and CSS to PDF API with page headers, footers and page numbers. No headless browser. REST API and MCP server, hosted in Germany.\n\nBase URL: `https://api.pdfrender.dev`.\n\n### Authentication\nSend your key in the `X-API-Key` header. Calls without a key run anonymously at\na lower rate limit per IP address.\n\n### Rate limits\nEvery response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and\n`X-RateLimit-Reset` (seconds until the window resets). Over-budget calls return\n`429` with a `Retry-After` header. Check your live budget at `GET /v1/me`.\n\n### Pagination\nList endpoints return a keyset envelope: `{\"items\": [...], \"next_cursor\": \"...\"}`.\nPass `next_cursor` back as the `?cursor=` query param for the next page; it is\n`null` on the last page.\n\n### Errors\nErrors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `problem+json` with a\nstable machine-readable **`code`** (e.g. `rate_limited`, `credits_exhausted`,\n`validation_error`). Branch on `code`. The `title` and `detail` text may change.\n\n### Quickstart\n```sh\ncurl -H \"X-API-Key: $API_KEY\" https://api.pdfrender.dev/v1/me\n```\n",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://api.pdfrender.dev"
    }
  ],
  "paths": {
    "/v1/me": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Your plan, remaining requests, and remaining credits",
        "description": "Check where you stand before a call fails.\n\nReturns the plan this request runs on and whether your key was recognized.\nWithout an `X-API-Key`, the call runs anonymously at the rate limit for\ncalls without a key. It also returns the requests left in the current window\nand the features your plan includes. On plans priced in credits, it returns\nthe credits left in the current billing period.\n\nThis call does not count against your rate limit, so the numbers it reports\nare the numbers you have.\n\n**Credits:** free. This endpoint is not metered.",
        "operationId": "get_me",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "x-credits-cost": 0,
        "x-connector": {
          "kind": "action"
        }
      }
    },
    "/v1/render": {
      "post": {
        "tags": [
          "Render"
        ],
        "summary": "Render an HTML document to a PDF",
        "description": "Send an HTML document and get the PDF back as a download.\n\nInline images, fonts and CSS as `data:` URIs. External resources (http,\nhttps, file) are not loaded: a document that references one is rejected with\n400, and the detail lists the URLs. Relative URLs are ignored. JavaScript is\nnot run.\n\nLimits: 2 MB of HTML, 50 pages, and 20 seconds including time in the queue.\nWithout an API key, the limit is 8 seconds and one render runs at a time.\n\nOn a paid plan, set `pdf_variant` to `pdf/a-2b` or `pdf/a-3b` for PDF/A\noutput.\n\nWorks without an API key for 10 requests a day per IP address. With a\nkey, a rejected or failed call costs no credits.\n\n**Credits:** 1 per call.",
        "operationId": "render_html_to_pdf",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenderRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The PDF, as a download (`Content-Disposition: attachment`).",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "The HTML references an external resource (`external_resource_blocked`). The detail lists the URLs.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "402": {
            "description": "The credit balance is used up (`credits_exhausted`).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "`pdf_variant` was set without a paid plan (`feature_not_available`). The `upgrade_url` starts the checkout.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "The HTML is larger than 2 MB (`html_too_large`).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request body is invalid (`validation_error`), or the document has more than 50 pages (`too_many_pages`).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "The rate limit is reached (`rate_limited`). Retry after the seconds in the `Retry-After` header. Without an API key, one render runs at a time: a second one gets `render_busy`. Retry in a few seconds, or use a key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The document could not be rendered (`render_failed`).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "504": {
            "description": "The render took longer than 20 seconds with an API key, or 8 seconds without one (`render_timeout`).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "x-credits-cost": 1,
        "x-connector": {
          "kind": "action"
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreditsInfo": {
        "properties": {
          "balance": {
            "type": "integer",
            "title": "Balance"
          },
          "granted": {
            "type": "integer",
            "title": "Granted"
          },
          "period_end": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Period End"
          }
        },
        "type": "object",
        "required": [
          "balance",
          "granted"
        ],
        "title": "CreditsInfo",
        "description": "Your credit balance for the current billing period. `granted` is what\nyour plan included, `balance` what is still unspent, and `period_end` the\ndate (ISO 8601) your allowance refills. Present only on plans that are\npriced in credits."
      },
      "MeResponse": {
        "properties": {
          "tier": {
            "type": "string",
            "title": "Tier",
            "description": "The plan this request is served on."
          },
          "is_keyed": {
            "type": "boolean",
            "title": "Is Keyed",
            "description": "Whether the request carried a valid API key. Without an `X-API-Key`, the call runs anonymously at the rate limit for calls without a key."
          },
          "rate_limit": {
            "$ref": "#/components/schemas/RateLimitInfo"
          },
          "credits": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CreditsInfo"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null on plans that are not priced in credits."
          },
          "features": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Features",
            "description": "The features your plan includes."
          }
        },
        "type": "object",
        "required": [
          "tier",
          "is_keyed",
          "rate_limit",
          "features"
        ],
        "title": "MeResponse",
        "description": "The `GET /v1/me` payload: who the request is authenticated as, what is\nleft of your request and credit allowances, and which features your plan\nincludes."
      },
      "RateLimitInfo": {
        "properties": {
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Limit"
          },
          "remaining": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Remaining"
          },
          "reset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reset"
          }
        },
        "type": "object",
        "title": "RateLimitInfo",
        "description": "How many requests you may still make in the current window. These are the\nsame numbers as the `X-RateLimit-*` response headers. `limit` is the size of the\nwindow, `remaining` what is left of it, and `reset` how many seconds until\nit refills (not a timestamp). All three are `null` in the rare case the\ncounter cannot be read; treat that as \"unknown\", not zero."
      },
      "RenderRequest": {
        "properties": {
          "html": {
            "type": "string",
            "title": "Html",
            "description": "The HTML document, up to 2 MB. Inline images, fonts and CSS as data: URIs; external resources are not loaded. JavaScript is not run."
          },
          "filename": {
            "type": "string",
            "title": "Filename",
            "description": "Filename of the downloaded PDF. Characters other than A–Z, a–z, 0–9, `.`, `_` and `-` become `_`, and `.pdf` is added if missing.",
            "default": "document.pdf"
          },
          "pdf_variant": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "pdf/a-2b",
                  "pdf/a-3b"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Pdf Variant",
            "description": "Write the PDF as PDF/A-2b or PDF/A-3b, for archiving. Paid plans only: without one, the call gets 403 `feature_not_available` with an `upgrade_url`. Leave it out for a regular PDF."
          }
        },
        "type": "object",
        "required": [
          "html"
        ],
        "title": "RenderRequest",
        "description": "An HTML document to render, an optional filename and an optional PDF/A variant.",
        "examples": [
          {
            "filename": "invoice.pdf",
            "html": "<!doctype html>\n<style>\n@page { size: A4; margin: 22mm }\nbody { font: 11pt/1.5 sans-serif; color: #1c2024 }\ntable { width: 100%; border-collapse: collapse }\nth { text-align: left; border-bottom: 2px solid #1c2024 }\ntd { padding: 3mm 0; border-bottom: 1px solid #e3e6ea }\n</style>\n<h1>Invoice 2026-041</h1>\n<p>Northwind Studio · Due Sep 30, 2026</p>\n<table>\n  <thead><tr><th>Description</th><th>Qty</th><th>Amount</th></tr></thead>\n  <tbody>\n    <tr><td>Design retainer, September</td><td>1</td><td>1,800.00</td></tr>\n    <tr><td>Illustration, cover set</td><td>6</td><td>720.00</td></tr>\n  </tbody>\n</table>\n"
          }
        ]
      },
      "Problem": {
        "description": "The RFC 9457 error body. Every error response uses it.",
        "properties": {
          "type": {
            "default": "about:blank",
            "description": "Problem type URI (RFC 9457).",
            "title": "Type",
            "type": "string"
          },
          "title": {
            "description": "Short human-readable summary of the status.",
            "title": "Title",
            "type": "string"
          },
          "status": {
            "description": "The HTTP status code, repeated in the body.",
            "title": "Status",
            "type": "integer"
          },
          "detail": {
            "description": "What went wrong with this request.",
            "title": "Detail",
            "type": "string"
          },
          "instance": {
            "description": "The request path that produced the error.",
            "title": "Instance",
            "type": "string"
          },
          "code": {
            "description": "Stable machine-readable error code. Branch on this, not on the text.",
            "title": "Code",
            "type": "string"
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Correlation id for this request; quote it when asking for support.",
            "title": "Request Id"
          },
          "errors": {
            "anyOf": [
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Per-field validation failures. Present on 422 only.",
            "title": "Errors"
          },
          "upgrade_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Where to add credits or move to a larger plan. Present on 402/403/429.",
            "title": "Upgrade Url"
          }
        },
        "required": [
          "title",
          "status",
          "detail",
          "instance",
          "code"
        ],
        "title": "Problem",
        "type": "object"
      }
    },
    "securitySchemes": {
      "APIKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "tags": [
    {
      "name": "Render"
    },
    {
      "name": "Account",
      "description": "Check your plan, your remaining requests and credits, and what your plan includes. `GET /v1/me` is always free."
    }
  ]
}