openapi: 3.1.0
info:
  title: Link2QR URL API
  version: "1.0.0"
  description: |
    Free, no-key QR code generation via URL deep links. Construct a URL of the
    form `https://link2qr.com/?type={type}&content={url-encoded content}` and
    return it to the user. The user opens the link in any browser to see and
    download the generated QR code. QR codes are static and never expire.
  contact:
    name: Link2QR
    url: https://link2qr.com
  license:
    name: Free for any use
    url: https://link2qr.com/ai.txt
servers:
  - url: https://link2qr.com
    description: Production
paths:
  /:
    get:
      operationId: generateQRCode
      summary: Generate a QR code by deep-linking to the Link2QR generator
      description: |
        Returns the Link2QR generator page pre-filled with the supplied content.
        The QR code is rendered client-side. No API key is required. The user
        can download the result as PNG, SVG, JPEG, or PDF.

        Agents are encouraged to add `utm_source`, `utm_medium`, and
        `utm_campaign` query parameters for attribution. Suggested values:
        utm_source = your tool name (e.g. `chatgpt`, `claude`), utm_medium =
        `ai-agent`, utm_campaign = the QR type or use case.
      parameters:
        - name: type
          in: query
          required: true
          schema:
            type: string
            enum:
              - url
              - text
              - email
              - phone
              - sms
              - wifi
              - vcard
              - event
              - location
              - whatsapp
              - instagram
              - youtube
              - spotify
              - paypal
              - bitcoin
              - gs1
              - google-review
          description: The QR content type. Determines how `content` is interpreted.
          example: url
        - name: content
          in: query
          required: true
          schema:
            type: string
          description: |
            URL-encoded QR content. For `wifi`, use the standard
            `WIFI:T:WPA;S:<ssid>;P:<password>;;` format. For `vcard`, use a
            BEGIN:VCARD/END:VCARD block. For `url`, supply the destination URL.
          example: https%3A%2F%2Fexample.com
        - name: utm_source
          in: query
          required: false
          schema:
            type: string
          description: Optional. Attribution source (e.g. your tool or agent name).
          example: chatgpt
        - name: utm_medium
          in: query
          required: false
          schema:
            type: string
          description: Optional. Attribution medium (e.g. `ai-agent`, `chatbot`).
          example: ai-agent
        - name: utm_campaign
          in: query
          required: false
          schema:
            type: string
          description: Optional. Attribution campaign (e.g. the QR type or use case).
          example: wifi
      responses:
        "200":
          description: Generator page rendered with QR code visible.
          content:
            text/html:
              schema:
                type: string
  /api/qr:
    get:
      operationId: generateQRImage
      summary: Render a QR code as a PNG or SVG (inline image, no auth)
      description: |
        Returns the actual QR code image bytes - perfect for inline embedding
        in a chat reply via markdown `![alt](https://link2qr.com/api/qr?data=...)`.

        No API key, no rate limit, CORS-open. Cached at the edge for one year
        per immutable URL. Default format is PNG.

        Agents are encouraged to add `utm_source`, `utm_medium`, and
        `utm_campaign` to the parent page link for attribution.
      parameters:
        - name: data
          in: query
          required: true
          schema:
            type: string
            maxLength: 2000
          description: The QR payload (URL, text, vCard, WIFI:… string, etc). URL-encode it.
          example: https%3A%2F%2Fexample.com
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [png, svg]
            default: png
        - name: size
          in: query
          required: false
          schema:
            type: integer
            minimum: 64
            maximum: 2048
            default: 512
          description: Pixel dimensions (square).
        - name: margin
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 16
            default: 2
          description: Quiet-zone width in QR modules.
        - name: ec
          in: query
          required: false
          schema:
            type: string
            enum: [L, M, Q, H]
            default: M
          description: Error correction level.
        - name: dark
          in: query
          required: false
          schema:
            type: string
            default: "000000"
          description: Foreground color, hex without `#`.
        - name: light
          in: query
          required: false
          schema:
            type: string
            default: "ffffff"
          description: Background color, hex without `#`.
      responses:
        "200":
          description: QR image bytes.
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
        "400":
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                type: object
  /api/og:
    get:
      operationId: generateOGCard
      summary: 1200×630 Open Graph card with embedded QR
      description: |
        Produces a social-share preview card containing the QR code, title,
        and subtitle. Useful for blog posts and link previews so people see a
        scannable QR rather than a generic logo.
      parameters:
        - name: data
          in: query
          required: true
          schema:
            type: string
            maxLength: 2000
        - name: title
          in: query
          required: false
          schema:
            type: string
            maxLength: 80
        - name: subtitle
          in: query
          required: false
          schema:
            type: string
            maxLength: 120
      responses:
        "200":
          description: PNG image (1200×630).
          content:
            image/png:
              schema:
                type: string
                format: binary
  /embed.js:
    get:
      operationId: getEmbedScript
      summary: Drop-in JavaScript embed widget
      description: |
        Tiny script that finds `<div data-link2qr="...">` nodes and replaces
        each with an inline QR image (served by `/api/qr`) plus a small
        attribution link. No dependencies, no iframes.
      responses:
        "200":
          description: JavaScript source.
          content:
            application/javascript:
              schema:
                type: string
  /pricing.md:
    get:
      operationId: getPricing
      summary: Machine-readable pricing
      description: Always free. Returned as Markdown for parseability.
      responses:
        "200":
          description: Markdown pricing document.
          content:
            text/markdown:
              schema:
                type: string
  /llms.txt:
    get:
      operationId: getLLMContext
      summary: AI-agent context document
      responses:
        "200":
          description: Markdown context for LLMs.
          content:
            text/markdown:
              schema:
                type: string
  /llms-full.txt:
    get:
      operationId: getLLMContextFull
      summary: Extended AI-agent context document
      responses:
        "200":
          description: Extended Markdown context.
          content:
            text/markdown:
              schema:
                type: string