# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
method: generated
overlay: 1.0.0
info:
  title: API Evangelist enhancements for DataForSEO AiOptimization Serp API
  version: 1.0.0
extends: openapi/dataforseo-serp-api-openapi.yml
x-generated: '2026-08-13'
x-method: generated
x-source: >-
  Derived from openapi/dataforseo-serp-api-openapi.yml plus the artifacts in this repo
  (conventions/, errors/, authentication/, lifecycle/, sandbox/, mcp/).
  Never mutates the harvested specification.
actions:
  - target: $.info
    update:
      x-apievangelist-provider: dataforseo
      x-apievangelist-artifacts:
        authentication: authentication/dataforseo-authentication.yml
        conventions: conventions/dataforseo-conventions.yml
        errors: errors/dataforseo-problem-types.yml
        lifecycle: lifecycle/dataforseo-lifecycle.yml
        rate_limits: rate-limits/dataforseo-rate-limits.yml
        sandbox: sandbox/dataforseo-sandbox.yml
        data_model: data-model/dataforseo-data-model.yml
        mcp: mcp/dataforseo-mcp.yml
      x-apievangelist-operation-count: 181
      x-apievangelist-contact: https://dataforseo.com/contact
      x-apievangelist-terms: https://dataforseo.com/terms-of-service/
  - target: $.servers
    update:
      - url: https://api.dataforseo.com
        description: Production. Charged per task against the prepaid balance.
      - url: https://sandbox.dataforseo.com
        description: >-
          Free sandbox. Identical paths and payloads, dummy data, same
          credentials. See sandbox/dataforseo-sandbox.yml.
  - target: $.components.securitySchemes.basicAuth
    update:
      description: >-
        HTTP Basic with the API login and password from
        https://app.dataforseo.com/api-access. The API password is generated by
        DataForSEO and differs from the account password. Credentials cannot be
        passed as URL parameters.
      x-credentials-url: https://app.dataforseo.com/api-access
      x-docs: https://docs.dataforseo.com/v3/auth/
  - target: $.info
    update:
      x-error-semantics:
        note: >-
          This API returns HTTP 200 for nearly every outcome. The authoritative
          result is the numeric status_code / status_message pair, present both
          at the top level of the response envelope and inside each element of
          tasks[]. Branch on status_code, not on HTTP status.
        http_codes_used: [200, 401, 402, 404, 500]
        code_range: 10000-60000
        catalog: errors/dataforseo-problem-types.yml
      x-rate-limit-semantics:
        limit: 2000 requests per minute per account
        exhaustion_status_code: 40202
        concurrency_status_code: 40209
        headers: none
      x-idempotency:
        supported: false
        note: >-
          No idempotency key is documented. Record the task id before POSTing and
          poll tasks_ready / id_list before retrying — retries are billable.