API Evangelist enhancements for the ScrapingAnt Scraping API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the ScrapingAnt Scraping API
  version: 1.0.0
x-provenance:
  generated: '2026-08-29'
  method: generated
  source: >-
    Enhancements derived from https://docs.scrapingant.com/request-response-format,
    https://docs.scrapingant.com/errors and https://docs.scrapingant.com/api-basics, applied
    over openapi/_original/scrapingant-openapi.json (harvested verbatim 2026-08-29).
  extends: openapi/_original/scrapingant-openapi.json
  refined_output: openapi/scrapingant-scraping-api-openapi.yml
  note: >-
    The original document is never mutated. Every action below records a divergence between the
    contract ScrapingAnt publishes and the API ScrapingAnt documents and operates. Four of them
    are defects a code generator would trip over.
x-divergences:
  - id: nonunique-operationids
    severity: high
    detail: >-
      The published spec assigns the SAME operationId
      (scrapingant_general_request_v2_general_post) to all five HTTP methods on /v2/general.
      OpenAPI requires operationId to be unique across the document. Most generators either
      fail or silently emit one method. The refined document assigns method-suffixed ids.
  - id: no-securityschemes
    severity: high
    detail: >-
      components.securitySchemes is empty and no security requirement is declared, yet every
      operation requires x-api-key. A generator reading the spec produces an unauthenticated
      client.
  - id: credential-in-query
    severity: high
    detail: >-
      x-api-key is declared as a required QUERY parameter. The docs and the provider's own code
      samples also accept it as a request header, which is the safer transport, but the contract
      does not describe that option.
  - id: missing-endpoints
    severity: high
    detail: >-
      /v2/markdown, /v2/extract and /v2/extended are documented, live (all return 422 "API
      token is missing" unauthenticated) and absent from the spec. The contract describes 2 of
      5 endpoints.
  - id: no-tags
    severity: medium
    detail: The document declares no tags, so every operation is untagged and ungrouped.
  - id: undeclared-timeout
    severity: medium
    detail: >-
      The `timeout` parameter (5-60s, default 60) is documented at
      docs.scrapingant.com/request-response-format and is missing from every operation.
  - id: response-media-type-mismatch
    severity: medium
    detail: >-
      The 200 response of /v2/general is declared as application/json while the endpoint
      returns text/html page content, as the response description itself states.
actions:
  - target: $.info
    description: >-
      Record that this contract covers only part of the documented ScrapingAnt API surface.
    update:
      x-api-evangelist-coverage: >-
        This document specifies /v2/general and /v2/usage. ScrapingAnt also operates and
        documents /v2/markdown (HTML-to-Markdown), /v2/extract (AI structured extraction) and
        /v2/extended (JSON envelope with cookies, headers, XHRs and iframes). Those three are
        not described by any machine-readable contract.
      x-api-evangelist-mcp: https://api.scrapingant.com/mcp/
  - target: $
    description: Declare the API-key security scheme the API enforces but the contract omits.
    update:
      security:
        - ApiKeyAuth: []
      components:
        securitySchemes:
          ApiKeyAuth:
            type: apiKey
            in: query
            name: x-api-key
            description: >-
              ScrapingAnt API key. Declared in-query to match the published contract; the
              provider documents that the same value is also accepted as an x-api-key request
              header, which should be preferred because query strings are logged.
  - target: $
    description: Declare tags so operations can be grouped.
    update:
      tags:
        - name: Scraping
          description: Fetch and render a target URL through the ScrapingAnt browser and proxy cluster.
        - name: Usage
          description: Account credit metering.
  - target: $.paths['/v2/general'].get
    description: Add the documented timeout parameter and correct the response media type.
    update:
      tags: [Scraping]
      parameters:
        - name: timeout
          in: query
          required: false
          description: >-
            Maximum time in seconds the request may run before it stops. Range 5-60, default
            60. Documented at https://docs.scrapingant.com/request-response-format.
          schema:
            type: integer
            minimum: 5
            maximum: 60
            default: 60
      responses:
        '200':
          content:
            text/html:
              schema:
                type: string
                description: HTML body of the rendered target page.
  - target: $.paths['/v2/general'].post
    description: >-
      Flag that a non-GET method is proxied through to the TARGET site, which makes this
      operation an unguarded third-party write.
    update:
      tags: [Scraping]
      x-agentic-consequence: external-write
      x-api-evangelist-note: >-
        POST/PUT/PATCH/DELETE against /v2/general causes ScrapingAnt to issue that method
        against the caller-supplied target URL. There is no idempotency key, no dry-run and no
        confirmation step. Treat as a write with no reversal path.
  - target: $.paths['/v2/usage'].get
    description: Tag the metering operation and record its agent relevance.
    update:
      tags: [Usage]
      x-api-evangelist-note: >-
        The only way to observe remaining credits. Not exposed as an MCP tool, so an agent on
        the MCP server is blind to its own budget.
  - target: $.paths['/v2/general'].get.responses['423']
    description: Record that no Retry-After accompanies the anti-bot status.
    update:
      x-retry: >-
        Retryable, but no Retry-After header is returned. Change proxy_type to residential or
        set proxy_country before retrying.
  - target: $.paths['/v2/general'].get.responses['403']
    description: Record the ambiguity between a bad key and an exhausted balance.
    update:
      x-disambiguation: >-
        403 covers BOTH an invalid API token and an exhausted credit balance. Call
        GET /v2/usage and read remained_credits to tell them apart.