{
  "openapi": "3.1.0",
  "info": {
    "title": "SnapPDF API",
    "version": "0.1.0",
    "description": "Developer-first REST API for 15 PDF operations. See https://snappdf.au/docs.",
    "contact": { "name": "SnapPDF", "email": "hello@snappdf.au", "url": "https://snappdf.au" },
    "license": { "name": "Proprietary" }
  },
  "servers": [
    { "url": "https://api.snappdf.au", "description": "Production" },
    { "url": "https://api.staging.snappdf.au", "description": "Staging" }
  ],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_* or sk_test_*" }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "details": { "type": "object", "additionalProperties": true }
            },
            "required": ["code", "message"]
          }
        }
      },
      "UsageSummary": {
        "type": "object",
        "properties": {
          "currentPeriodStart": { "type": "string", "format": "date-time" },
          "currentPeriodEnd": { "type": "string", "format": "date-time" },
          "plan": { "type": "string", "enum": ["free", "starter", "pro", "business", "enterprise"] },
          "limit": { "type": "integer" },
          "used": { "type": "integer" },
          "remaining": { "type": "integer" },
          "perOperation": { "type": "object", "additionalProperties": { "type": "integer" } }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "livemode": { "type": "boolean" },
          "scopes": { "type": "array", "items": { "type": "string" } },
          "lastFour": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" },
          "revokedAt": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "WebhookSubscription": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "events": { "type": "array", "items": { "type": "string" } },
          "secret": { "type": "string" },
          "active": { "type": "boolean" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "TextExtractResult": {
        "type": "object",
        "properties": {
          "text": { "type": "string" },
          "pages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pageNumber": { "type": "integer" },
                "text": { "type": "string" }
              }
            }
          },
          "stats": {
            "type": "object",
            "properties": {
              "wordCount": { "type": "integer" },
              "charCount": { "type": "integer" }
            }
          }
        }
      },
      "OcrResult": {
        "type": "object",
        "properties": {
          "text": { "type": "string" },
          "pages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pageNumber": { "type": "integer" },
                "text": { "type": "string" },
                "confidence": { "type": "number" }
              }
            }
          },
          "meanConfidence": { "type": "number" },
          "languagesUsed": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "responses": {
      "Pdf": {
        "description": "A PDF document",
        "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }
      },
      "ZipOrPdf": {
        "description": "A ZIP of PDFs (multi-part) or a single PDF",
        "content": {
          "application/pdf": { "schema": { "type": "string", "format": "binary" } },
          "application/zip": { "schema": { "type": "string", "format": "binary" } }
        }
      },
      "ZipOrImage": {
        "description": "A ZIP of images (multi-page) or a single image",
        "content": {
          "image/png": { "schema": { "type": "string", "format": "binary" } },
          "image/jpeg": { "schema": { "type": "string", "format": "binary" } },
          "image/webp": { "schema": { "type": "string", "format": "binary" } },
          "application/zip": { "schema": { "type": "string", "format": "binary" } }
        }
      },
      "Error4xx": {
        "description": "Client error",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Error5xx": {
        "description": "Server error",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  },
  "paths": {
    "/api/v1/merge": {
      "post": {
        "summary": "Merge 2+ PDFs", "operationId": "merge", "tags": ["Operations"],
        "requestBody": {
          "required": true,
          "content": { "multipart/form-data": { "schema": {
            "type": "object",
            "properties": {
              "file0": { "type": "string", "format": "binary" },
              "file1": { "type": "string", "format": "binary" },
              "fileN": { "type": "string", "format": "binary" },
              "interleave": { "type": "string" },
              "title": { "type": "string" },
              "author": { "type": "string" }
            }
          }}}
        },
        "responses": {
          "200": { "$ref": "#/components/responses/Pdf" },
          "400": { "$ref": "#/components/responses/Error4xx" },
          "429": { "$ref": "#/components/responses/Error4xx" }
        }
      }
    },
    "/api/v1/split": {
      "post": {
        "summary": "Split a PDF", "operationId": "split", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/ZipOrPdf" } }
      }
    },
    "/api/v1/extract-text": {
      "post": {
        "summary": "Extract text", "operationId": "extractText", "tags": ["Operations"],
        "responses": {
          "200": {
            "description": "Extracted text + stats",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextExtractResult" } } }
          }
        }
      }
    },
    "/api/v1/extract-pages": {
      "post": { "summary": "Extract pages", "operationId": "extractPages", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/Pdf" } } }
    },
    "/api/v1/to-images": {
      "post": { "summary": "Rasterize to images", "operationId": "toImages", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/ZipOrImage" } } }
    },
    "/api/v1/from-images": {
      "post": { "summary": "Build PDF from images", "operationId": "fromImages", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/Pdf" } } }
    },
    "/api/v1/ocr": {
      "post": { "summary": "OCR scanned PDF", "operationId": "ocr", "tags": ["Operations"],
        "responses": { "200": {
          "description": "OCR output",
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/OcrResult" } },
            "application/pdf": { "schema": { "type": "string", "format": "binary" } }
          }
        } } }
    },
    "/api/v1/watermark": {
      "post": { "summary": "Watermark", "operationId": "watermark", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/Pdf" } } }
    },
    "/api/v1/protect": {
      "post": { "summary": "Password-protect", "operationId": "protect", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/Pdf" } } }
    },
    "/api/v1/sign": {
      "post": { "summary": "Apply visual signature", "operationId": "sign", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/Pdf" } } }
    },
    "/api/v1/fill-form": {
      "post": { "summary": "Fill form fields", "operationId": "fillForm", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/Pdf" } } }
    },
    "/api/v1/compress": {
      "post": { "summary": "Compress PDF", "operationId": "compress", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/Pdf" } } }
    },
    "/api/v1/rotate": {
      "post": { "summary": "Rotate pages", "operationId": "rotate", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/Pdf" } } }
    },
    "/api/v1/add-page-numbers": {
      "post": { "summary": "Add page numbers", "operationId": "addPageNumbers", "tags": ["Operations"],
        "responses": { "200": { "$ref": "#/components/responses/Pdf" } } }
    },
    "/api/v1/metadata": {
      "post": { "summary": "Read or write metadata", "operationId": "metadata", "tags": ["Operations"],
        "responses": { "200": { "description": "JSON (action=get) or PDF (action=set)" } } }
    },
    "/api/v1/keys": {
      "get": { "summary": "List API keys", "operationId": "listKeys", "tags": ["Keys"],
        "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } },
            "count": { "type": "integer" }
          }
        }}}}}},
      "post": { "summary": "Create API key", "operationId": "createKey", "tags": ["Keys"],
        "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } } } }
    },
    "/api/v1/webhooks": {
      "get": { "summary": "List webhooks", "operationId": "listWebhooks", "tags": ["Webhooks"],
        "responses": { "200": { "description": "OK" } } },
      "post": { "summary": "Create webhook", "operationId": "createWebhook", "tags": ["Webhooks"],
        "responses": { "201": { "description": "Created",
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } }
    },
    "/api/v1/usage": {
      "get": { "summary": "Current usage", "operationId": "currentUsage", "tags": ["Usage"],
        "responses": { "200": { "description": "Usage",
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } } } }
    },
    "/api/v1/health": {
      "get": { "summary": "Health check", "operationId": "health", "tags": ["Meta"],
        "security": [],
        "responses": { "200": { "description": "ok" } } }
    }
  }
}