openapi: 3.0.3
info:
  title: d2topng
  description: >-
    Renders D2 (https://d2lang.com) diagrams to PNG. POST raw D2 source to
    `/render`, get back an `image/png`. No browser or SVG step is involved —
    D2 is used purely as a Go library for parsing, layout, and text
    measurement; drawing is native.
  version: 1.0.0
  license:
    name: MIT
  contact:
    url: https://github.com/macsplit/d2topng
servers:
  - url: https://d2png.com
    description: Public instance. No auth required. Rate-limited per client IP.
  - url: http://localhost:8080
    description: Local instance (default PORT for `bin/d2topng-server`).
paths:
  /healthz:
    get:
      summary: Liveness check
      operationId: healthz
      security: []
      responses:
        '200':
          description: Service is up.
          content:
            text/plain:
              schema:
                type: string
                example: ok
  /render:
    post:
      summary: Render a D2 diagram to PNG
      operationId: render
      security:
        - bearerAuth: []
        - {}
      parameters:
        - name: scale
          in: query
          required: false
          description: >-
            Output resolution multiplier. Use 2 or higher for crisp
            high-DPI output — text and strokes stay sharp rather than
            being blurred by upscaling. Must be a positive number.
          schema:
            type: number
            format: double
            minimum: 0
            exclusiveMinimum: true
            default: 1
      requestBody:
        required: true
        description: Raw D2 source. Capped at 1 MiB.
        content:
          text/plain:
            schema:
              type: string
              example: |
                client -> server: request
                server -> client: response
      responses:
        '200':
          description: Rendered successfully.
          content:
            image/png:
              schema:
                type: string
                format: binary
        '400':
          description: >-
            Empty body, body over 1 MiB, invalid `scale`, or a D2 compile
            error. For compile errors the body is D2's own diagnostic text.
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: >-
            Missing or incorrect bearer token. Only returned when the
            server has an API token configured; the public instance at
            d2png.com does not.
          content:
            text/plain:
              schema:
                type: string
                example: unauthorized
        '429':
          description: >-
            Rate limit exceeded for this client IP (token bucket: 5
            requests/second sustained, burst of 10).
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
          content:
            text/plain:
              schema:
                type: string
                example: rate limit exceeded
        '500':
          description: >-
            Diagram compiled successfully but failed to rasterize.
          content:
            text/plain:
              schema:
                type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Only enforced when the server has D2TOPNG_API_TOKEN set. The
        public instance at d2png.com does not require this.
