makespdf-com Render API

openapi: 3.2.0
info:
  title: makesPDF Render API
  version: 1.0.0
  description: 'Deterministic PDF rendering API: GitHub-flavoured Markdown or a compact DSL to tagged, PDF/A-2A + PDF/UA-1 dual-compliant PDFs. Authenticate with a Bearer token (API key or OAuth device flow), or pay per call via x402 (USDC on Base) on the x402-tagged operations. Errors use the shared Error schema. Rate limits are reported in RateLimit / RateLimit-Policy headers, with Retry-After on 429. Versioning: the major version is in the path (/api/v1); breaking changes ship as a new version, and a deprecated endpoint keeps working for at least 90 days after it starts sending Deprecation and Sunset headers.'
  x-guidance: 'POST /api/v1/markdown converts markdown to PDF ($0.01). POST /api/v1/render renders a template from templateId or inline DSL ($0.02). Both require an x402 payment: call unpaid to receive the 402 challenge (PAYMENT-REQUIRED header), sign an EIP-3009 USDC transfer, retry with the PAYMENT-SIGNATURE header. Free: GET /api/v1/templates?owner=library lists curated templates.'
  contact:
    name: makesPDF support
    email: jason@makespdf.com
    url: https://makespdf.com/contact
servers:
- url: https://makespdf.com
security: []
tags:
- name: render
paths:
  /api/v1/md:
    summary: Markdown to PDF
    description: Markdown to PDF for authenticated callers, billed at 1 credit per 10 pages. While the anonymous promo is enabled, unauthenticated calls are also accepted (rate-limited per IP, 20-page cap, watermarked). Not x402-annotated — use /api/v1/markdown for x402.
    post:
      operationId: mdToPdf
      summary: Convert Markdown to PDF (API key)
      description: Convert GitHub-flavoured Markdown (tables, code, Mermaid, math, alerts, footnotes) to a tagged PDF in about a second. Options can also come from YAML frontmatter.
      tags:
      - render
      responses:
        '200':
          description: 'Rendered PDF (PDF/A-2A + PDF/UA-1 dual-compliant, tagged). Send `Accept: application/json` for metadata instead of bytes.'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            X-Artifact-Id:
              description: Render artifact id.
              schema:
                type: string
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/RenderMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - bearerAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - markdown
              properties:
                markdown:
                  type: string
                  minLength: 1
                  description: 'GitHub-flavoured Markdown source. Max 200KB of text - inline `data:` image payloads are excluded from that budget and bounded by the image limits (5MB each, 20 per document). Request body max 15MB. A single block (no blank line between its lines) maxes out at ~8MB: past that the request fails with 413 and code `markdown-block-too-large`. A blank line splits a paragraph or image block and renders the same content, but it does not split a fenced code block and, between table rows, splits one table into two.'
                options:
                  type: object
                  properties:
                    pageSize:
                      type: string
                      enum:
                      - A3
                      - A4
                      - A5
                      - Letter
                      - Legal
                    fontFamily:
                      type: string
                      enum:
                      - Inter
                      - NotoSans
                    fontSize:
                      type: number
                      minimum: 6
                      maximum: 24
                    margins:
                      type: array
                      minItems: 4
                      maxItems: 4
                      items:
                        type: number
                      description: '[top, right, bottom, left] in points.'
                    title:
                      type: string
                      maxLength: 200
                    theme:
                      type: string
                      enum:
                      - default
                      - github
                    pageNumbers:
                      type: string
                      enum:
                      - page-n-of-total
                      - n-of-total
                      - n
                      description: 'Footer page numbers: ''page-n-of-total'' -> ''Page 3 of 12'', ''n-of-total'' -> ''3 / 12'', ''n'' -> ''3''. Omit for no page numbers.'
                    pageNumberPosition:
                      type: string
                      enum:
                      - left
                      - center
                      - right
                      description: Footer alignment when pageNumbers is set. Default 'right'.
                  description: Rendering options. Omit for defaults.
  /api/v1/canvas:
    summary: JSON Canvas board to PDF
    description: 'Convert a JSON Canvas 1.0 document (an Obsidian .canvas board) to a tagged, accessible PDF, billed at 1 credit per 10 pages for authenticated callers. While the anonymous promo is enabled, unauthenticated calls are also accepted (rate-limited per IP, 20-page cap, watermarked). Not x402-annotated: a PAYMENT-SIGNATURE header on an unauthenticated request gets the standard 401.'
    post:
      operationId: canvasToPdf
      summary: Convert a JSON Canvas board to PDF (API key)
      description: Send the parsed canvas object or the raw .canvas file text - cards, connector arrows, groups, image and note cards render in about a second. Text cards run the full markdown pipeline. Cards whose content overflows continue on later pages.
      tags:
      - render
      responses:
        '200':
          description: 'Rendered PDF (PDF/A-2A + PDF/UA-1 dual-compliant, tagged). Send `Accept: application/json` for metadata instead of bytes.'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            X-Artifact-Id:
              description: Render artifact id.
              schema:
                type: string
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/RenderMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - bearerAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - canvas
              properties:
                canvas:
                  description: A JSON Canvas 1.0 document (an Obsidian .canvas board) - the parsed object, or the raw file text as a string. Max 2MB of JSON; cards render through the markdown pipeline, so text cards support headings, lists, tables, images, Mermaid and graph blocks.
                  oneOf:
                  - type: object
                  - type: string
                    minLength: 1
                files:
                  type: object
                  additionalProperties:
                    oneOf:
                    - type: object
                      required:
                      - data
                      properties:
                        data:
                          type: string
                          description: A data:<mime>;base64,... URI (images).
                    - type: object
                      required:
                      - markdown
                      properties:
                        markdown:
                          type: string
                          description: Note text for a .md file.
                  description: Contents for the canvas file / background paths, keyed by the exact path string. The server cannot read a vault, so image and note cards resolve through this map (or the standard image fetcher for bare http(s) URLs).
                options:
                  type: object
                  properties:
                    pageSize:
                      type: string
                      enum:
                      - A3
                      - A4
                      - A5
                      - Letter
                      - Legal
                      description: Fit the board on a sheet. Omit to make the page the board itself.
                    fontFamily:
                      type: string
                      enum:
                      - Inter
                      - NotoSans
                    title:
                      type: string
                      maxLength: 200
                    author:
                      type: string
                      maxLength: 200
                    subject:
                      type: string
                      maxLength: 200
                    keywords:
                      type: string
                      maxLength: 500
                    lang:
                      type: string
                      maxLength: 35
                      description: Document language (BCP 47) - sets the PDF /Lang and picks the built-in CJK font ('ja', 'ko', 'zh-Hant', 'zh-Hans', ...). Omit to infer from the text.
                  description: Rendering options. Omit for defaults.
  /api/v1/preview:
    summary: Render a DSL draft (free)
    description: Free, rate-limited authoring endpoint. Same pipeline as /api/v1/render.
    post:
      operationId: previewPdf
      summary: Render a DSL template draft to PDF
      description: Render inline builder DSL with data while authoring a template. Free and not billed; limited to 200 renders per hour. Publish with POST /api/v1/render.
      tags:
      - render
      responses:
        '200':
          description: 'Rendered PDF (PDF/A-2A + PDF/UA-1 dual-compliant, tagged). Send `Accept: application/json` for metadata instead of bytes.'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            X-Artifact-Id:
              description: Render artifact id.
              schema:
                type: string
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/RenderMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - dsl
              properties:
                dsl:
                  type: string
                  minLength: 1
                  description: 'Builder DSL script. Reference: https://makespdf.com/skills/pdf-template-author.md'
                data:
                  type: object
                  description: Values substituted into {{placeholders}}. Defaults to the script's sampleData.
                options:
                  type: object
                  properties:
                    title:
                      type: string
                      maxLength: 200
components:
  schemas:
    Error:
      type: object
      required:
      - error
      description: Every 4xx/5xx JSON body. `error` is always present; the other fields appear when they apply.
      properties:
        error:
          type: string
          description: Human-readable message. Some routes use a stable kebab-case value (e.g. `rate-limited`, `in-place-impossible`) that is safe to branch on.
        code:
          type: string
          description: Machine-readable error code, when the route sets one (e.g. `containers-disabled`).
        details:
          type: array
          items:
            type: string
          description: 'Per-field validation messages, `path: message`.'
        issues:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
          description: Template validation issues, on DSL/catalog failures.
        hint:
          type: string
          description: How to fix the request.
        retryAfter:
          type: integer
          description: Seconds until the rate limit resets (429 only; mirrors Retry-After).
        docs:
          type: string
          format: uri
        agent_guide:
          type: string
          format: uri
        skill:
          type: string
          format: uri
      additionalProperties: true
    RenderMetadata:
      type: object
      required:
      - success
      - pageCount
      - sizeBytes
      - renderMs
      description: 'Returned instead of PDF bytes when the request sends `Accept: application/json`.'
      properties:
        success:
          type: boolean
          const: true
        templateId:
          type: string
          description: Stored template rendered (/render only).
        pageCount:
          type: integer
        sizeBytes:
          type: integer
        renderMs:
          type: integer
        artifactId:
          type: string
          description: Render artifact id; download again via GET /api/v1/artifacts/{id}/pdf.
        templateWarnings:
          type: array
          items: {}
        layoutWarnings:
          type: array
          items: {}
        credits_deducted:
          type: integer
        remaining_balance:
          type: integer
        paid:
          type: object
          properties:
            payer:
              type: string
            txHash:
              type: string
      additionalProperties: true
    PaymentRequired:
      type: object
      description: x402 PaymentRequired envelope. The same requirements are in the PAYMENT-REQUIRED header; see https://www.x402.org/.
      properties:
        x402Version:
          type: integer
        error:
          type: string
        accepts:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    ValidationIssue:
      type: object
      required:
      - severity
      - message
      properties:
        severity:
          type: string
          enum:
          - error
          - warning
        message:
          type: string
        path:
          type: string
          description: Location in the document tree.
        rule:
          type: string
          description: Rule identifier, e.g. a PDF/UA check.
  headers:
    RateLimit:
      description: Quota left in each policy this request counted against (draft-ietf-httpapi-ratelimit-headers-11), e.g. `"render";r=1999;t=3600`. `r` = requests remaining, `t` = seconds until the oldest counted request leaves the window.
      schema:
        type: string
    RateLimit-Policy:
      description: Policies this request counted against, e.g. `"render";q=2000;w=3600`. `q` = quota, `w` = window in seconds.
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying. Takes precedence over RateLimit.
      schema:
        type: integer
        minimum: 0
  responses:
    Unauthorized:
      description: Missing or invalid Bearer token. The body links the docs, llms.txt and the auth skill.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected server error. Never billed.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Malformed body or failed validation. Never billed.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: Insufficient credits (authed callers) or an x402 challenge (wallet callers, PAYMENT-REQUIRED header).
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/PaymentRequired'
            - $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key or OAuth device-flow token sent as `Authorization: Bearer <token>`. Agents should get one through the device flow (/skills/pdf-auth.md); never ask a user for their password.'
externalDocs:
  description: API reference, including errors, rate limits and the versioning policy
  url: https://makespdf.com/docs/api
x-discovery:
  ownershipProofs:
  - '0xF4d2bC1034beE5eA270AcA773aEB97736d14fb31'