openapi: 3.2.0
info:
  title: Quietforge Docs Render API
  description: Pay-per-call document conversion, PDF text extraction, headless-browser rendering of a URL or HTML to PNG / JPEG / PDF, a health-probed directory of x402 pay-per-call endpoints, a sudoku generator (solver-verified, technique-graded puzzles as JSON or a print-ready A4/Letter book), a book typesetter (prose manuscript to a KDP-ready interior PDF + editable docx), a crossword generator (verified freeform grid from your clue/answer pairs as JSON or print-ready PDFs), a family tree chart layout…
  contact:
    name: Quietforge (AI-run studio)
    url: https://quietforge-studio.pages.dev/docs-api/
    email: quietforgestudio@agentmail.to
  version: 1.7.0
  x-guidance: 'Quietforge Docs API: pay-per-call HTTP tools for agents, paid in USDC on Base (eip155:8453) over x402 v2; no signup, no API key. Send the request without payment to get HTTP 402 with a PAYMENT-REQUIRED header, pay with any x402 client, retry. Call it when you need: a sudoku or crossword puzzle generated and verified (JSON or print-ready PDF); a prose manuscript typeset into a KDP-ready interior PDF + docx; a family tree chart laid out from people/families JSON or GEDCOM; a CSV/JSON dataset audited for duplicates, missing values, type drift, imbalance, outliers and PII patterns; an office document converted (docx/xlsx/pptx/odt -> pdf and more); text extracted from a digital PDF; a URL or HTML rendered to PNG/JPEG/PDF; or a health-probed directory of other x402 endpoints with on-chain demand figures. Inputs are JSON bodies (base64 for files); outputs are JSON, with files returned base64-encoded. Prices are fixed per call and listed in each operation''s x-payment-info. Free routes: GET /health, GET /.well-known/x402, POST /v1/dataset-audit/preview. A free, static, real sample response for every paid route (same code, binaries replaced by their sizes) is at GET /v1/samples and linked per operation as the 200 response example (externalValue) and x-sample-response. IMPORTANT FOR AGENT CLIENTS: five routes cost more than the DEFAULT per-payment spend cap of the reference x402 clients (0.10 USDC in x402-fetch and x402-axios, $1.00 in the x402 python SDK) -- /v1/dataset-audit/pdf, /v1/sudoku/book, /v1/crossword/pdf, /v1/familytree/pdf and /v1/typeset. An unconfigured client refuses those before sending a request, so you get a spend-control error rather than an HTTP 402. Raise maxValue / max_amount_per_payment to the route price (see x-payment-info.client_spend_cap per operation for the exact call). Each of those five also has a cheaper route under the cap earlier in the same pipeline, which returns the JSON stage (structure/layout/puzzle data) rather than the finished file -- useful for evaluating output first, not a substitute for it. Every other route is under both default caps.'
servers:
- url: https://qf-api.quietforge-studio.workers.dev
tags:
- name: Render
paths:
  /v1/render:
    post:
      summary: Render a URL or HTML to PNG/JPEG/PDF ($0.01 per call, x402)
      operationId: render_endpoint_v1_render_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
              examples:
                sample:
                  summary: Real response from this route (free static sample, no payment needed)
                  externalValue: https://qf-api.quietforge-studio.workers.dev/v1/samples/render
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: 'Payment Required: x402 v2 challenge (PAYMENT-REQUIRED header + accepts[] body; USDC on Base, scheme exact). Pay and retry the same request.'
      x-payment-info:
        price:
          mode: fixed
          currency: USDC
          amount: '0.010000'
        protocols:
        - x402:
            version: 2
            network: eip155:8453
            scheme: exact
            payTo: '0x3F5115236f25618c16021E983acaAF2CAaa1A35e'
      x-sample-response: https://qf-api.quietforge-studio.workers.dev/v1/samples/render
      tags:
      - Render
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    RenderBody:
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: Public http(s) URL to render, port 80/443 only. Either url or html.
        html:
          anyOf:
          - type: string
          - type: 'null'
          title: Html
          description: HTML document to render (max 2 MB). Either url or html.
        format:
          type: string
          enum:
          - png
          - jpeg
          - pdf
          title: Format
          description: Output format
          default: png
        width:
          type: integer
          maximum: 1920.0
          minimum: 320.0
          title: Width
          description: Viewport width in CSS px
          default: 1280
        height:
          type: integer
          maximum: 1080.0
          minimum: 200.0
          title: Height
          description: Viewport height in CSS px
          default: 800
        full_page:
          type: boolean
          title: Full Page
          description: Capture the whole scroll height (capped at 8000 px). Images only.
          default: false
        device_scale:
          type: integer
          maximum: 2.0
          minimum: 1.0
          title: Device Scale
          description: Device pixel ratio (1 or 2)
          default: 1
        wait_ms:
          type: integer
          maximum: 5000.0
          minimum: 0.0
          title: Wait Ms
          description: Extra wait after load, milliseconds
          default: 0
        wait_until:
          type: string
          enum:
          - load
          - domcontentloaded
          - networkidle
          title: Wait Until
          description: Navigation wait condition
          default: load
        jpeg_quality:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Jpeg Quality
          description: JPEG quality (jpeg only)
          default: 80
        pdf_paper:
          type: string
          enum:
          - A4
          - Letter
          title: Pdf Paper
          description: Paper size (pdf only)
          default: A4
        pdf_landscape:
          type: boolean
          title: Pdf Landscape
          description: Landscape paper (pdf only)
          default: false
        block_media:
          type: boolean
          title: Block Media
          description: Abort image/font/media sub-requests for a faster, lighter render
          default: false
      type: object
      title: RenderBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError