openapi: 3.1.0
info:
  title: ScreenshotOne API
  description: Minimal OpenAPI description of the ScreenshotOne screenshot rendering API.
  version: "1.0.0"
  x-generated-from: https://screenshotone.com/docs/
  x-generated-by: claude-crawl-2026-05-08
servers:
  - url: https://api.screenshotone.com
    description: ScreenshotOne production API
security:
  - accessKeyQuery: []
  - accessKeyHeader: []
tags:
  - name: Screenshots
  - name: Animations
  - name: Account
paths:
  /take:
    get:
      tags: [Screenshots]
      summary: Take a screenshot
      description: Captures a screenshot of the requested URL or rendered HTML/Markdown content.
      parameters:
        - $ref: '#/components/parameters/Url'
        - $ref: '#/components/parameters/Html'
        - $ref: '#/components/parameters/Markdown'
        - $ref: '#/components/parameters/Format'
        - $ref: '#/components/parameters/FullPage'
        - $ref: '#/components/parameters/ViewportWidth'
        - $ref: '#/components/parameters/ViewportHeight'
        - $ref: '#/components/parameters/BlockAds'
        - $ref: '#/components/parameters/BlockCookieBanners'
      responses:
        '200':
          description: Rendered screenshot
          content:
            image/png: { schema: { type: string, format: binary } }
            image/jpeg: { schema: { type: string, format: binary } }
            image/webp: { schema: { type: string, format: binary } }
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags: [Screenshots]
      summary: Take a screenshot (POST)
      description: Same as GET /take but accepts options as a JSON request body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenshotOptions'
      responses:
        '200':
          description: Rendered screenshot
          content:
            image/png: { schema: { type: string, format: binary } }
            image/jpeg: { schema: { type: string, format: binary } }
            image/webp: { schema: { type: string, format: binary } }
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /animate:
    get:
      tags: [Animations]
      summary: Render an animated screenshot
      description: Captures an animated rendering of a URL (scroll, navigation, default scenarios).
      parameters:
        - $ref: '#/components/parameters/Url'
        - name: scenario
          in: query
          description: Animation scenario (default, scroll, navigation)
          schema:
            type: string
            enum: [default, scroll, navigation]
      responses:
        '200':
          description: Rendered animation
          content:
            video/mp4: { schema: { type: string, format: binary } }
            image/gif: { schema: { type: string, format: binary } }
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags: [Animations]
      summary: Render an animated screenshot (POST)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenshotOptions'
      responses:
        '200':
          description: Rendered animation
          content:
            video/mp4: { schema: { type: string, format: binary } }
            image/gif: { schema: { type: string, format: binary } }
  /usage:
    get:
      tags: [Account]
      summary: Get current plan usage
      description: Retrieves request quota and consumption information for the current billing period.
      responses:
        '200':
          description: Usage details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    accessKeyQuery:
      type: apiKey
      in: query
      name: access_key
      description: API access key passed as a query string parameter.
    accessKeyHeader:
      type: apiKey
      in: header
      name: X-Access-Key
      description: API access key passed via the X-Access-Key request header.
  parameters:
    Url:
      name: url
      in: query
      description: The URL of the website to screenshot.
      schema:
        type: string
        format: uri
    Html:
      name: html
      in: query
      description: Raw HTML to render. One of url, html, or markdown is required.
      schema:
        type: string
    Markdown:
      name: markdown
      in: query
      description: Markdown content to render. One of url, html, or markdown is required.
      schema:
        type: string
    Format:
      name: format
      in: query
      description: Output image format.
      schema:
        type: string
        enum: [png, jpeg, jpg, webp, gif, pdf]
    FullPage:
      name: full_page
      in: query
      description: Capture the entire scrollable page.
      schema:
        type: boolean
    ViewportWidth:
      name: viewport_width
      in: query
      description: Viewport width in pixels.
      schema:
        type: integer
        minimum: 1
    ViewportHeight:
      name: viewport_height
      in: query
      description: Viewport height in pixels.
      schema:
        type: integer
        minimum: 1
    BlockAds:
      name: block_ads
      in: query
      description: Block advertisements during rendering.
      schema:
        type: boolean
    BlockCookieBanners:
      name: block_cookie_banners
      in: query
      description: Block cookie consent banners during rendering.
      schema:
        type: boolean
  schemas:
    ScreenshotOptions:
      type: object
      description: Generic ScreenshotOne options envelope.
      properties:
        url:
          type: string
          format: uri
        html:
          type: string
        markdown:
          type: string
        format:
          type: string
        full_page:
          type: boolean
        viewport_width:
          type: integer
        viewport_height:
          type: integer
        access_key:
          type: string
      additionalProperties: true
    Usage:
      type: object
      description: Usage information for the API account.
      additionalProperties: true
    Error:
      type: object
      description: Generic error response.
      properties:
        error_code:
          type: string
        error_message:
          type: string
      additionalProperties: true