{
  "openapi": "3.0.3",
  "info": {
    "title": "GrabShot Screenshot API",
    "description": "Capture pixel-perfect website screenshots via a simple REST API. Supports PNG, JPEG, WebP, full-page capture, custom viewports, dark mode, and AI-powered cleanup that removes cookie banners and popups.",
    "version": "1.0.0",
    "contact": {
      "name": "GrabShot",
      "url": "https://grabshot.dev",
      "email": "hello@grabshot.dev"
    },
    "x-logo": {
      "url": "https://grabshot.dev/img/logo.svg"
    }
  },
  "servers": [
    {
      "url": "https://grabshot.dev",
      "description": "Production"
    }
  ],
  "paths": {
    "/v1/screenshot": {
      "get": {
        "summary": "Capture a screenshot",
        "description": "Takes a screenshot of any URL. Returns the image directly as binary data.",
        "operationId": "captureScreenshot",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "The URL to screenshot (must include protocol)",
            "schema": { "type": "string", "example": "https://github.com" }
          },
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "description": "Your API key",
            "schema": { "type": "string", "example": "gs_your_api_key" }
          },
          {
            "name": "width",
            "in": "query",
            "description": "Viewport width in pixels (default: 1280)",
            "schema": { "type": "integer", "default": 1280 }
          },
          {
            "name": "height",
            "in": "query",
            "description": "Viewport height in pixels (default: 800)",
            "schema": { "type": "integer", "default": 800 }
          },
          {
            "name": "format",
            "in": "query",
            "description": "Output format",
            "schema": { "type": "string", "enum": ["png", "jpeg", "webp"], "default": "png" }
          },
          {
            "name": "fullPage",
            "in": "query",
            "description": "Capture full scrollable page",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "quality",
            "in": "query",
            "description": "JPEG/WebP quality (1-100)",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
          },
          {
            "name": "delay",
            "in": "query",
            "description": "Wait time in ms before capture (max 10000)",
            "schema": { "type": "integer", "maximum": 10000 }
          },
          {
            "name": "darkMode",
            "in": "query",
            "description": "Force dark color scheme",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "frame",
            "in": "query",
            "description": "Add a browser frame around the screenshot",
            "schema": { "type": "string", "enum": ["browser", "none"], "default": "none" }
          },
          {
            "name": "cleanup",
            "in": "query",
            "description": "AI cleanup - removes cookie banners, popups (paid plans only)",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "selector",
            "in": "query",
            "description": "CSS selector to capture a specific element",
            "schema": { "type": "string" }
          },
          {
            "name": "blockAds",
            "in": "query",
            "description": "Block ads and trackers",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Screenshot image",
            "content": {
              "image/png": { "schema": { "type": "string", "format": "binary" } },
              "image/jpeg": { "schema": { "type": "string", "format": "binary" } },
              "image/webp": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/v1/register": {
      "post": {
        "summary": "Create an account",
        "description": "Register a new account and get an API key. Free plan includes 100 screenshots/month.",
        "operationId": "register",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "format": "email", "example": "dev@example.com" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "email": { "type": "string" },
                    "plan": { "type": "string" },
                    "apiKey": { "type": "string" },
                    "limits": {
                      "type": "object",
                      "properties": {
                        "monthly": { "type": "integer" },
                        "perMinute": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/account": {
      "get": {
        "summary": "Get account info",
        "description": "Returns account details, plan, and usage stats.",
        "operationId": "getAccount",
        "parameters": [
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Account info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": { "type": "string" },
                    "plan": { "type": "string" },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "used": { "type": "integer" },
                        "limit": { "type": "integer" },
                        "remaining": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": { "type": "string" }
        }
      }
    }
  }
}