Zenserp search API enrichment overlay

overlay: 1.0.0
info:
  title: Zenserp search API enrichment overlay
  version: 1.0.0
  x-generated: '2026-08-13'
  x-method: generated
  x-source: openapi/zenserp-search-api-openapi.yml
  x-description: API Evangelist enhancements to the Zenserp OpenAPI. Applies runtime semantics, provenance
    and agent-facing hints that the base document does not carry. Never mutates the base spec.
extends: openapi/zenserp-search-api-openapi.yml
actions:
- target: $.info
  description: 'Record the provenance of this description: the endpoint inventory came from the Zenserp
    documentation SPA bundle and was confirmed against live unauthenticated probes.'
  update:
    x-provenance:
      harvested-by: API Evangelist
      harvested: '2026-08-13'
      source: https://app.zenserp.com/documentation
      method: docs + live probe
      note: Zenserp publishes no OpenAPI. Every path in this document returned application/json on a live
        unauthenticated request (HTTP 403 {"error":"No apikey provided."}), which is how the paths were
        confirmed to exist.
- target: $.info
  description: Point consumers at the runtime semantics that OpenAPI cannot express for this API.
  update:
    x-conventions: conventions/zenserp-conventions.yml
    x-error-catalog: errors/zenserp-problem-types.yml
    x-rate-limits: rate-limits/zenserp-rate-limits.yml
    x-lifecycle: lifecycle/zenserp-lifecycle.yml
- target: $.components.securitySchemes
  description: Zenserp accepts the API key in a third channel -- a form field on POST requests -- which
    OpenAPI 3.0 securitySchemes cannot represent. Recorded as an extension so it is not lost.
  update:
    x-apiKeyFormField:
      x-type: apiKey
      x-in: formData
      x-name: apikey
      description: 'For POST requests the API key may be sent as a form field: curl "https://app.zenserp.com/api/v2/search"
        -F "apikey=<key>". Documented at https://app.zenserp.com/documentation#authentification.'
- target: $.paths.*.*
  description: Flag that Zenserp returns no rate-limit response headers -- quota must be read out of band
    from GET /api/v2/status.
  update:
    x-rate-limit-headers: none
    x-quota-endpoint: GET /api/v2/status
- target: $.paths['/search'].get
  description: Record the documented offset-pagination ceiling, which the parameter schemas alone do not
    convey.
  update:
    x-pagination:
      style: offset
      offset-parameter: start
      page-size-parameter: num
      default-page-size: 10
      max-total-results: 300
      note: Google returns at most 300 results. Set start=100 for results 101-200 and start=200 for 201-300.
        There is no cursor and no trustworthy total; number_of_results is Google's corpus estimate, not
        what is retrievable.
- target: $.paths['/search'].get
  description: 'Record the response-shape switch: which result array is populated depends on tbm and search_engine.'
  update:
    x-response-variants:
      switch:
      - tbm
      - search_engine
      variants:
        (none): organic_results, paid_results, featured_snippet, knowledge_graph, related_questions, related_searches
        isch: image_results
        nws: news_results
        shop: shopping_results
        lcl: map_results
        map: map_results (requires ll=@lat,long,zoomz)
        vid: video_results
        trends: trends_results
        search_engine=bing.com: Bing SERP
        search_engine=yandex.com: Yandex SERP
        search_engine=youtube.com: YouTube results