esyURL Render API

openapi: 3.2.0
info:
  title: Esyurl Fyi Render API
  version: 2.0.0
  contact:
    name: esyURL
    email: contact@esyurl.fyi
    url: https://esyurl.fyi/about/contact
  x-guidance: 'Get an API key first: follow /auth.md (agents sign themselves up, no human needed). Then POST /v1/links with {"targetUrl": "...", "slug": "..."} for a short link and GET /v1/links/{id}/qr for its QR code. PUT /v1/domain {"domain": "go.example.com"} sets a custom domain; for self-signed-up tenants it answers 402 and is paid with x402 (USDC), once per domain. The full guide is /llms.txt.'
  description: 'Operations tagged Render across 2 of this provider''s published API definitions: openapi.json, esyurl-fyi-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://esyurl.fyi
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Render
paths:
  /v1/render:
    post:
      summary: Render arbitrary data as a QR image, without saving anything
      description: 'Requires `links:read`. Static: the image encodes `data` directly and is not tracked. Styles are free here; without an API key, POST /x402/qr does the same for a small x402 payment.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderRequest'
      responses:
        '200':
          description: Image
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            WWW-Authenticate:
              schema:
                type: string
              description: 'Bearer resource_metadata="{baseUrl}/.well-known/oauth-protected-resource" (RFC 9728; how to sign up: /auth.md)'
        '403':
          description: API key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Render
      operationId: postV1Render
      x-operation-id-source: derived
    servers:
    - url: https://esyurl.fyi
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - bad_request
              - validation_error
              - unauthorized
              - forbidden
              - not_found
              - conflict
              - gone
              - payment_required
              - quota_exceeded
              - rate_limited
              - internal_error
              - payments_not_configured
              - service_unavailable
            message:
              type: string
            details: {}
    RenderRequest:
      type: object
      required:
      - data
      additionalProperties: false
      properties:
        data:
          type: string
          maxLength: 2048
        format:
          type: string
          enum:
          - png
          - svg
          default: png
        size:
          type: integer
          minimum: 64
          maximum: 2048
        margin:
          type: integer
          minimum: 0
          maximum: 16
        dark:
          $ref: '#/components/schemas/HexColour'
        light:
          $ref: '#/components/schemas/HexColour'
        ecl:
          type: string
          enum:
          - L
          - M
          - Q
          - H
        modules:
          type: string
          enum:
          - square
          - rounded
          - dot
          - row
          - column
          description: Shape of the data modules (default square)
        eyeFrame:
          type: string
          enum:
          - square
          - rounded
          - circle
          description: Outer ring of the three corner markers
        eyeBall:
          type: string
          enum:
          - square
          - rounded
          - circle
          description: Centre of the corner markers
        eyeColor:
          $ref: '#/components/schemas/HexColour'
          description: Colour of the corner markers; defaults to dark
        image:
          type: object
          required:
          - mode
          - data
          additionalProperties: false
          properties:
            mode:
              type: string
              enum:
              - logo
              - halftone
              description: 'logo: in the middle; halftone: a photo behind the code, drawn as dots'
            data:
              type: string
              description: data:image/png;base64,... (png, jpeg, webp or gif, up to 2 MB)
            size:
              type: number
              minimum: 0.1
              maximum: 0.3
              description: Logo side as a share of the code (default 0.22)
    HexColour:
      type: string
      pattern: ^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
      examples:
      - '#000000'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key `esy_{keyId}_{secret}`, from an operator or from agent self-sign-up (/auth.md)
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
x-refined-from:
- openapi.json
- esyurl-fyi-openapi.json