openapi: 3.1.0
info:
  title: ScraperAPI
  description: |
    ScraperAPI is a web scraping API that handles proxies, headless browsers,
    and CAPTCHA solving. Sync, async, structured data, and data pipeline
    endpoints are available. All requests require an api_key.
    Source: https://docs.scraperapi.com/
  version: "1.0"
servers:
  - url: https://api.scraperapi.com
    description: Synchronous API
  - url: https://async.scraperapi.com
    description: Asynchronous API
  - url: https://datapipeline.scraperapi.com
    description: DataPipeline API
security:
  - ApiKeyAuth: []
paths:
  /:
    get:
      summary: Scrape a URL synchronously
      operationId: scrape
      tags: [Sync]
      parameters:
        - $ref: "#/components/parameters/ApiKey"
        - name: url
          in: query
          required: true
          description: The fully-qualified URL to scrape (place after api_key).
          schema: { type: string, format: uri }
        - name: render
          in: query
          description: Set to true to render JavaScript with a headless browser.
          schema: { type: boolean }
        - name: country_code
          in: query
          description: Geo-target the request (e.g. us, gb, de).
          schema: { type: string }
        - name: premium
          in: query
          description: Use residential/premium proxies.
          schema: { type: boolean }
        - name: session_number
          in: query
          description: Reuse the same IP across requests (15-minute idle TTL).
          schema: { type: integer }
        - name: keep_headers
          in: query
          schema: { type: boolean }
        - name: device_type
          in: query
          description: desktop or mobile.
          schema: { type: string, enum: [desktop, mobile] }
      responses:
        "200":
          description: HTML body of the target page.
          content:
            text/html:
              schema: { type: string }
    post:
      summary: Scrape a URL with a POST body
      operationId: scrapePost
      tags: [Sync]
      parameters:
        - $ref: "#/components/parameters/ApiKey"
        - name: url
          in: query
          required: true
          schema: { type: string, format: uri }
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema: { type: object, additionalProperties: true }
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        "200":
          description: Response of the target site for the proxied POST.
  /structured/google/search:
    get:
      summary: Structured Google search results
      operationId: structuredGoogleSearch
      tags: [Structured]
      parameters:
        - $ref: "#/components/parameters/ApiKey"
        - name: query
          in: query
          required: true
          schema: { type: string }
        - name: country_code
          in: query
          schema: { type: string }
        - name: tld
          in: query
          schema: { type: string }
      responses:
        "200":
          description: JSON-structured SERP.
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
  /structured/amazon/product:
    get:
      summary: Structured Amazon product data
      operationId: structuredAmazonProduct
      tags: [Structured]
      parameters:
        - $ref: "#/components/parameters/ApiKey"
        - name: asin
          in: query
          required: true
          schema: { type: string }
        - name: country
          in: query
          schema: { type: string }
        - name: tld
          in: query
          schema: { type: string }
      responses:
        "200":
          description: JSON-structured Amazon product.
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: ScraperAPI account key, passed as a query parameter.
  parameters:
    ApiKey:
      name: api_key
      in: query
      required: true
      description: ScraperAPI account key.
      schema: { type: string }