openapi: 3.1.0
info:
  title: screenshotbase
  version: "1"
  summary: Capture screenshots of any web page.
  description: >-
    screenshotbase renders any URL and returns a screenshot image, with control
    over viewport, format, full-page capture, element hiding, ad/cookie-banner
    blocking and more. Authenticate every request with your API key, either as
    the `apikey` query parameter or the `apikey` request header.


    This document is generated from the screenshotbase service implementation and
    is the machine-readable source of truth for the v1 REST API. A human-readable
    version is available at https://screenshotbase.com/docs.
  contact:
    name: screenshotbase support
    email: support@screenshotbase.com
  x-logo:
    url: https://screenshotbase.com/screenshotbase_logo.svg
servers:
  - url: https://api.screenshotbase.com
    description: Production
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
tags:
  - name: Screenshots
    description: Capture screenshots.
  - name: Metadata
    description: Account status.
paths:
  /v1/take:
    get:
      tags: [Screenshots]
      summary: Take a screenshot
      operationId: take
      description: >-
        Renders the given URL and returns the screenshot. By default the image
        binary is returned directly; pass `upload=true` to instead store the
        image and receive a JSON object with its public URL.
      parameters:
        - name: url
          in: query
          required: true
          description: The URL of the page to capture.
          schema: { type: string, format: uri }
          example: "https://example.com"
        - name: format
          in: query
          required: false
          description: Image format of the returned screenshot.
          schema: { type: string, enum: [jpg, png, gif, webp], default: png }
        - name: quality
          in: query
          required: false
          description: Image quality (only applied for jpg).
          schema: { type: integer }
        - name: full_page
          in: query
          required: false
          description: Capture the full scrollable page instead of just the viewport.
          schema: { type: boolean, default: false }
        - name: viewport_width
          in: query
          required: false
          description: Viewport width in pixels.
          schema: { type: integer }
          example: 1920
        - name: viewport_height
          in: query
          required: false
          description: Viewport height in pixels.
          schema: { type: integer }
          example: 1080
        - name: ip_country_code
          in: query
          required: false
          description: >-
            Capture from an exit IP in the given country (ISO 3166-1 alpha-2).
            Only a subset of countries with datacenter presence is supported.
          schema: { type: string }
          example: "US"
        - name: delay
          in: query
          required: false
          description: Seconds to wait after load before capturing (0-30).
          schema: { type: integer, minimum: 0, maximum: 30 }
        - name: timeout
          in: query
          required: false
          description: Navigation timeout in seconds (5-60).
          schema: { type: integer, minimum: 5, maximum: 60 }
        - name: wait_until
          in: query
          required: false
          description: The navigation lifecycle event to wait for before capturing.
          schema:
            type: string
            enum: [load, domcontentloaded, networkidle0, networkidle2]
        - name: block_cookie_banners
          in: query
          required: false
          description: Attempt to hide cookie-consent banners before capturing.
          schema: { type: boolean }
        - name: block_ads
          in: query
          required: false
          description: Attempt to block ads before capturing.
          schema: { type: boolean }
        - name: block_chats
          in: query
          required: false
          description: Attempt to hide chat widgets before capturing.
          schema: { type: boolean }
        - name: hide_selectors
          in: query
          required: false
          description: >-
            CSS selectors of elements to hide before capturing. Repeat the
            parameter for multiple selectors (`hide_selectors[]=.foo`).
          schema:
            type: array
            items: { type: string, maxLength: 255 }
        - name: styles
          in: query
          required: false
          description: Custom CSS to inject before capturing (max 10000 chars).
          schema: { type: string, maxLength: 10000 }
        - name: attachment_name
          in: query
          required: false
          description: Filename (without extension) for the downloaded image.
          schema: { type: string, maxLength: 255 }
        - name: upload
          in: query
          required: false
          description: >-
            When `true`, stores the screenshot and returns a JSON object with the
            public URL instead of the image binary.
          schema: { type: boolean, default: false }
      responses:
        '200':
          description: >-
            The screenshot image binary, or a JSON object with the stored image
            URL when `upload=true`.
          headers:
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            image/png:
              schema: { type: string, format: binary }
            image/jpeg:
              schema: { type: string, format: binary }
            image/gif:
              schema: { type: string, format: binary }
            image/webp:
              schema: { type: string, format: binary }
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                    example: "https://cdn.screenshotbase.com/screenshots/1337/abc123.png"
                required: [url]
        '401': { $ref: '#/components/responses/Unauthorized' }
        '408':
          description: The target website took too long to load.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example: { message: "The target website took too long to load." }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v1/status:
    get:
      tags: [Metadata]
      summary: Account quota status
      operationId: getStatus
      description: >-
        Returns your current monthly and grace quota usage. Requests to this
        endpoint do not count against your quota or rate limit.
      responses:
        '200':
          description: Current quota usage for the authenticated account.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusResponse' }
              example:
                account_id: 313373133731337
                quotas:
                  month: { total: 300, used: 72, remaining: 228 }
                  grace: { total: 0, used: 0, remaining: 0 }
        '401': { $ref: '#/components/responses/Unauthorized' }
components:
  securitySchemes:
    ApiKeyQuery: { type: apiKey, in: query, name: apikey, description: "API key as the apikey query parameter." }
    ApiKeyHeader: { type: apiKey, in: header, name: apikey, description: "API key as the apikey request header (recommended)." }
  headers:
    Cost:
      description: Requests this call counted against your quota.
      schema: { type: integer }
      example: 1
  responses:
    Unauthorized:
      description: An API key was supplied but is invalid.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { message: "If you specify an apikey it has to be a valid one." }
    ValidationError:
      description: One or more request parameters failed validation.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ValidationError' }
          example:
            message: "Validation error"
            errors: { url: ["The url field is required."] }
            info: "For more information, see documentation: https://screenshotbase.com/docs/status-codes#_422"
    RateLimited:
      description: You have exceeded your monthly quota or minute rate limit.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { message: "You have reached your monthly limit, please upgrade your plan" }
  schemas:
    StatusResponse:
      type: object
      properties:
        account_id: { type: integer, example: 313373133731337 }
        quotas:
          type: object
          properties:
            month: { $ref: '#/components/schemas/QuotaBucket' }
            grace: { $ref: '#/components/schemas/QuotaBucket' }
          required: [month]
      required: [quotas]
    QuotaBucket:
      type: object
      properties:
        total: { type: integer, example: 300 }
        used: { type: integer, example: 72 }
        remaining: { type: integer, example: 228 }
    Error:
      type: object
      properties: { message: { type: string }, info: { type: string } }
      required: [message]
    ValidationError:
      type: object
      properties:
        message: { type: string, example: "Validation error" }
        errors:
          type: object
          additionalProperties: { type: array, items: { type: string } }
        info: { type: string }
      required: [message, errors]
