{
  "openapi": "3.0.3",
  "info": {
    "title": "Agent QR API",
    "description": "QR code generation infrastructure for AI agents. First call auto-provisions an API key — no signup required.",
    "version": "0.1.0",
    "contact": {
      "name": "Agent QR",
      "url": "https://agentqr.tools"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/patrickjrs/agent-qr"
    }
  },
  "servers": [
    {
      "url": "https://api.agentqr.tools",
      "description": "Production API"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "Service status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "service": { "type": "string", "example": "agent-qr" },
                    "version": { "type": "string", "example": "0.1.0" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/qr": {
      "post": {
        "summary": "Generate a QR code",
        "description": "Generate a QR code from data. On first call without an API key, one is auto-provisioned and returned in the response. Store the key for future calls to get 1,000 free codes/month.",
        "parameters": [
          {
            "name": "X-API-Key",
            "in": "header",
            "required": false,
            "schema": { "type": "string" },
            "description": "API key. If omitted, a new key is auto-provisioned."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["data"],
                "properties": {
                  "data": {
                    "type": "string",
                    "description": "The data to encode (URL, text, vCard, etc.)"
                  },
                  "format": {
                    "type": "string",
                    "enum": ["png", "svg", "base64"],
                    "default": "png"
                  },
                  "size": {
                    "type": "integer",
                    "default": 300,
                    "description": "Image size in pixels"
                  },
                  "errorCorrectionLevel": {
                    "type": "string",
                    "enum": ["L", "M", "Q", "H"],
                    "default": "M"
                  },
                  "colorDark": {
                    "type": "string",
                    "default": "#000000",
                    "description": "Foreground color in hex"
                  },
                  "colorLight": {
                    "type": "string",
                    "default": "#FFFFFF",
                    "description": "Background color in hex"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "QR code generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "image": { "type": "string", "description": "QR code image (data URI or raw)" },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "qr_id": { "type": "string" },
                        "format": { "type": "string" },
                        "size": { "type": "integer" }
                      }
                    },
                    "tier": { "type": "string", "example": "free" },
                    "remaining": { "type": "integer", "example": 999 },
                    "api_key": { "type": "string", "description": "Auto-provisioned API key (only on first call)" },
                    "upgrade_hint": { "type": "string" }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": { "type": "string", "example": "limit_exceeded" },
                    "message": { "type": "string" },
                    "upgrade_url": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/qr/batch": {
      "post": {
        "summary": "Generate multiple QR codes",
        "description": "Generate a batch of QR codes in a single request. Requires an API key.",
        "parameters": [
          {
            "name": "X-API-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["items"],
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "data": { "type": "string" },
                        "format": { "type": "string" },
                        "size": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch of QR codes generated"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    }
  }
}