makespdf-com Public API

openapi: 3.2.0
info:
  title: makesPDF Public 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: Public
paths:
  /api/v1/templates:
    summary: List templates
    description: List templates under the read predicate — curated library rows are world-readable.
    get:
      operationId: listTemplates
      summary: List templates
      description: Metadata for visible templates, newest first. Anonymous callers see the curated library only. Fetch one with GET /api/v1/templates/{id} to get its DSL.
      tags:
      - Public
      responses:
        '200':
          description: Visible templates.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      security: []
      parameters:
      - name: owner
        in: query
        schema:
          type: string
          enum:
          - mine
          - library
          - all
          default: all
      - name: category
        in: query
        schema:
          type: string
      - name: tags
        in: query
        description: Comma-separated; all must match.
        schema:
          type: string
      - name: q
        in: query
        description: Free text over name and description.
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
  /api/v1/templates/{id}:
    summary: Get a template
    description: One template with its DSL source and sample data.
    get:
      operationId: getTemplate
      summary: Get a template by id
      description: Returns the template's DSL and sampleData. Library templates are readable anonymously; user templates only by their owner.
      tags:
      - Public
      responses:
        '200':
          description: The template.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      security: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
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
    TemplateSummary:
      type: object
      required:
      - templateId
      - name
      - category
      - tags
      - createdAt
      - updatedAt
      properties:
        templateId:
          type: string
          description: Library slug or user template UUID.
        ownerUserId:
          type:
          - string
          - 'null'
          description: null for curated library rows.
        name:
          type: string
        description:
          type: string
        category:
          type:
          - string
          - 'null'
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    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.
    Template:
      allOf:
      - $ref: '#/components/schemas/TemplateSummary'
      - type: object
        required:
        - dsl
        properties:
          dsl:
            type: string
            description: Builder DSL source.
          sampleData:
            description: Example data for the template, or null.
    TemplateList:
      type: object
      required:
      - templates
      - total
      - limit
      - offset
      properties:
        templates:
          type: array
          items:
            $ref: '#/components/schemas/TemplateSummary'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
  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:
    NotFound:
      description: Not found, or not visible to this caller.
      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'
    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'
    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'
  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'