{
  "openapi": "3.1.0",
  "info": {
    "title": "Screenshot API",
    "version": "1.0.0",
    "description": "Screenshots are private and expire seven days after creation. Cleanup is best effort; target websites can block automated browsers. No application-level usage limits are enforced."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/screenshots": {
      "post": {
        "summary": "Capture a screenshot",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CaptureRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Image bytes. X-Screenshot-Id and X-Expires-At identify the saved capture.",
            "headers": {
              "X-Screenshot-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Expires-At": {
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            },
            "content": {
              "image/png": {},
              "image/jpeg": {},
              "image/webp": {}
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "description": "Capture unavailable or the outcome is being reconciled. If code is capture_finalization_pending, use X-Screenshot-Id to check metadata.",
            "headers": {
              "X-Screenshot-Id": {
                "description": "Present when finalization is pending.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/screenshots/{id}": {
      "get": {
        "summary": "Retrieve screenshot metadata",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Owned, unexpired screenshot metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Screenshot"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/screenshots/{id}/image": {
      "get": {
        "summary": "Retrieve a saved screenshot image",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Owned, unexpired image",
            "content": {
              "image/png": {},
              "image/jpeg": {},
              "image/webp": {}
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key, not a session token."
      }
    },
    "parameters": {
      "Id": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Request failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "CaptureRequest": {
        "type": "object",
        "required": ["url"],
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "device": {
            "type": "string",
            "enum": [
              "desktop",
              "hd",
              "laptop",
              "laptop-wide",
              "full-hd",
              "qhd",
              "tablet",
              "mobile",
              "macbook-air-13",
              "macbook-air-15",
              "macbook-pro-14",
              "macbook-pro-16",
              "imac-24",
              "studio-display",
              "iphone-17-pro-max",
              "iphone-17-pro",
              "iphone-air",
              "iphone-16-plus",
              "iphone-16",
              "iphone-16e",
              "iphone-13-mini",
              "iphone-se",
              "ipad-pro-13",
              "ipad-pro-11",
              "ipad-air-13",
              "ipad-air-11",
              "ipad-mini",
              "ipad-classic",
              "android",
              "android-compact"
            ],
            "default": "desktop",
            "description": "Viewport and frame preset. Sizes are CSS pixels."
          },
          "format": {
            "type": "string",
            "enum": ["png", "jpeg", "webp"],
            "default": "png",
            "description": "WebP capture has not yet been verified against Browser Run."
          },
          "fullPage": {
            "type": "boolean",
            "default": false
          },
          "frame": {
            "type": "boolean",
            "default": false,
            "description": "Adds an illustrative browser or mobile frame. Output has size limits; frame rendering is not yet verified in Browser Run."
          },
          "cleanup": {
            "type": "boolean",
            "default": true,
            "description": "Best-effort removal of ads and obstructions; may alter page content."
          }
        }
      },
      "Screenshot": {
        "type": "object",
        "required": ["id", "status", "options", "createdAt", "expiresAt"],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "options": {
            "type": "object"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "failureCode": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "requestId"],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}