API Evangelist enrichment overlay for the Wego API

overlay: 1.0.0
info:
  title: API Evangelist enrichment overlay for the Wego API
  version: 1.0.0
extends: openapi/wego-api-openapi.json
x-generated: '2026-09-04'
x-method: derived
x-source: >-
  openapi/wego-api-openapi.json plus the Wego documentation pages that state rules the spec
  itself does not carry (https://docs.wego.com/api/errors,
  https://docs.wego.com/api/rate-limits, https://docs.wego.com/api/how-search-works,
  https://docs.wego.com/api/ids-expire, https://docs.wego.com/api/fares-rates-partners,
  https://docs.wego.com/overview)
x-note: >-
  This overlay records API Evangelist's enrichment of the Wego contract. It never mutates the
  original spec on disk. Every action below carries information Wego publishes in its own
  documentation but does NOT encode in the machine contract - which is exactly the gap an
  agent falls into when it reads the spec alone.
actions:
- target: $.info
  description: Attach the repository's artifact index and the Research Preview status the spec omits.
  update:
    x-apis-io-artifacts:
      authentication: authentication/wego-authentication.yml
      scopes: scopes/wego-scopes.yml
      errors: errors/wego-problem-types.yml
      rate-limits: rate-limits/wego-rate-limits.yml
      conventions: conventions/wego-conventions.yml
      lifecycle: lifecycle/wego-lifecycle.yml
      data-model: data-model/wego-data-model.yml
      mcp: mcp/wego-mcp.yml
      tool-crosswalk: mcp/wego-tool-crosswalk.yml
      cli: cli/wego-cli.yml
      skills: skills/_index.yml
      conformance: conformance/wego-conformance.yml
    x-lifecycle-stage: research-preview
    x-lifecycle-note: >-
      Endpoints and response shapes can change; Wego tells callers to pin nothing they cannot
      re-check. There is no SLA and no deprecation policy.
- target: $.info
  description: Record the runtime semantics documented outside the contract.
  update:
    x-idempotency:
      coverage: none
      note: No Idempotency-Key header or replay window is documented or declared.
    x-reversibility:
      grade: na
      note: >-
        No consequential write surface. Searches are ephemeral snapshots and no booking,
        payment or charge happens through this API.
    x-error-envelope:
      format: rfc9457
      media_type: application/problem+json
      branch_on: code
      closed_enum: true
    x-rate-limit-headers:
    - RateLimit
    - RateLimit-Policy
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    - X-RateLimit-Reset
    - X-RateLimit-Resource
    - Retry-After
- target: $.paths['/v1/flights/searches'].post
  description: Record the async settlement rule and the per-operation quota, neither of which is in the spec.
  update:
    x-async-settlement:
      terminal_flag: null
      read_until: metadata.snapshotFareCount holds steady across two consecutive reads and
        metadata.snapshotTripCount is above zero
      backoff: 300ms to 3s
    x-rate-limit:
      quota_name: createFlightSearch
      windows:
      - limit: 10
        window: 60s
      - limit: 100
        window: 3600s
      - limit: 500
        window: 86400s
- target: $.paths['/v1/hotels/searches'].post
  description: Record the dual quota name and the settlement rule.
  update:
    x-async-settlement:
      terminal_flag: searchComplete
      note: >-
        searchComplete:true is terminal; false is advisory. Poll
        metadata.snapshotCandidateCount until it holds steady at a non-zero value.
    x-rate-limit:
      quota_name_city_or_geo: createHotelSearch
      quota_name_with_hotel_id: createHotelSearchScoped
      note: >-
        One operation, two quota names. A create carrying hotelId is metered as
        createHotelSearchScoped (30/60s, 300/3600s, 1500/86400s); a city or geo create is
        metered as createHotelSearch (10/60s, 100/3600s, 500/86400s). Match on the name the
        RateLimit header carries, not on the operationId.
- target: $.paths['/v1/hotels/{hotelId}/rates'].get
  description: Record the 409 precondition and its quota.
  update:
    x-precondition:
      requires: a searchId created with hotelId
      failure: 409 rates_require_hotel_search
      note: >-
        A city or geo search is rejected. Only a hotel-scoped search prices the full room
        list; re-reading a city search never deepens its sample.
    x-rate-limit:
      quota_name: getHotelRates
      windows:
      - limit: 60
        window: 60s
      - limit: 600
        window: 3600s
      - limit: 3000
        window: 86400s
- target: $.paths['/v1/flights/fares/{fareId}/options'].get
  description: Record the fare-kind precondition and the covers semantics.
  update:
    x-precondition:
      requires: a fare whose kind is "wego"
      failure: 400
      note: Airline and partner fares are fulfilled by the provider and do not work here.
    x-covers-semantics:
      values: [trip, leg]
      positive_witness: true
      note: >-
        "trip" means pass exactly one fareOptionId; "leg" means pass one id per leg
        (comma-separated, at most 8, none repeated). Absent means the upstream did not let
        Wego attribute the option - never that it covers the trip. Passing a single "leg" id
        is rejected by nothing and opens a booking page priced on one leg of a round trip.
- target: $.paths['/v1/places'].get
  description: Record the disambiguation rule.
  update:
    x-ambiguity:
      field: metadata.hasAmbiguity
      note: >-
        When true, ask the traveler which place they meant rather than taking the top row.
        An agent that resolves silently books the wrong Cambridge.
- target: $.components.securitySchemes.oauth2
  description: Record the discovery documents that make this flow self-configuring for agents.
  update:
    x-discovery:
      authorization_server_metadata: https://api.wego.com/.well-known/oauth-authorization-server
      protected_resource_metadata: https://api.wego.com/.well-known/oauth-protected-resource/mcp
      dynamic_client_registration: https://api.wego.com/mcp/register
      openid_configuration: null
      openid_configuration_note: >-
        An `openid` scope is offered but no /.well-known/openid-configuration is served on any
        Wego host, so OIDC discovery is unavailable.