overlay: 1.0.0
info:
  title: API Evangelist enhancements — Epsilon Retail Media Integration API
  version: 1.0.0
extends: openapi/epsilon-retail-media-integration-openapi.json
x-generated: '2026-08-12'
x-method: generated
x-source: >-
  Generated by the API Evangelist enrichment pipeline from the spec this
  overlay extends, plus the Epsilon Retail Media developer hub at
  https://developers.citrusad.com/integration/reference/. The original spec is
  never mutated; every enhancement below is expressed as an Overlay action.
actions:
  - target: $.info
    description: Record where this contract came from and how it was assembled.
    update:
      x-apievangelist-source: https://developers.citrusad.com/integration/reference/
      x-apievangelist-harvest: >-
        Assembled verbatim from the per-operation OpenAPI 3.1.0 documents the
        provider publishes inside each API reference page (fetched as .md). The
        provider does not publish a single combined document for this API.
      x-apievangelist-harvested: '2026-08-12'
  - target: $.info
    description: Cross-link the runtime-semantics artifacts OpenAPI cannot express.
    update:
      x-apievangelist-conventions: conventions/epsilon-conventions.yml
      x-apievangelist-authentication: authentication/epsilon-authentication.yml
      x-apievangelist-errors: errors/epsilon-problem-types.yml
      x-apievangelist-rate-limits: rate-limits/epsilon-rate-limits.yml
      x-apievangelist-lifecycle: lifecycle/epsilon-lifecycle.yml
      x-apievangelist-data-model: data-model/epsilon-data-model.yml
      x-apievangelist-sandbox: sandbox/epsilon-sandbox.yml
  - target: $.servers
    description: >-
      Record what the published server URL actually is. The host is assigned by
      Epsilon at onboarding and the published value is a template, so a consumer
      cannot call this API from the spec alone.
    update:
      x-apievangelist-server-note: >-
        Tenant/region-assigned host. Verified live regional ad-serving hosts at
        probe time (2026-08-12): eu-ads, eu-tracking, us-east-ads and apac-ads
        under rmn.dotomi.com. The citrusad.com hosts named in servers[] do not
        resolve on the public internet.
  - target: $.paths['/ads/generate'].post
    description: Tag and classify generate for discovery and agent safety.
    update:
      x-apievangelist-consequence: write
      x-apievangelist-idempotent: false
      x-apievangelist-idempotency-note: >-
        No Idempotency-Key mechanism is supported by this API. Safe retry is
        the caller's problem.
  - target: $.paths['/ads/bannerx'].post
    description: Tag and classify bannerx for discovery and agent safety.
    update:
      x-apievangelist-consequence: write
      x-apievangelist-idempotent: false
      x-apievangelist-idempotency-note: >-
        No Idempotency-Key mechanism is supported by this API. Safe retry is
        the caller's problem.
  - target: $.paths['/orders'].post
    description: Tag and classify report-an-order for discovery and agent safety.
    update:
      x-apievangelist-consequence: write
      x-apievangelist-idempotent: false
      x-apievangelist-idempotency-note: >-
        No Idempotency-Key mechanism is supported by this API. Safe retry is
        the caller's problem.
  - target: $.paths['/orders'].get
    description: Tag and classify retrieve-a-list-of-orders for discovery and agent safety.
    update:
      x-apievangelist-consequence: read
      x-apievangelist-idempotent: true
  - target: $.paths['/orders/{orderId}'].get
    description: Tag and classify retrieve-an-order for discovery and agent safety.
    update:
      x-apievangelist-consequence: read
      x-apievangelist-idempotent: true
  - target: $.paths['/catalogs'].post
    description: Tag and classify create-or-update-a-catalog for discovery and agent safety.
    update:
      x-apievangelist-consequence: write
      x-apievangelist-idempotent: false
      x-apievangelist-idempotency-note: >-
        No Idempotency-Key mechanism is supported by this API. Safe retry is
        the caller's problem.
  - target: $.paths['/catalog-products'].post
    description: Tag and classify create-or-update-a-product for discovery and agent safety.
    update:
      x-apievangelist-consequence: write
      x-apievangelist-idempotent: false
      x-apievangelist-idempotency-note: >-
        No Idempotency-Key mechanism is supported by this API. Safe retry is
        the caller's problem.
  - target: $.paths['/catalog-products'].get
    description: Tag and classify retrieve-a-list-of-products for discovery and agent safety.
    update:
      x-apievangelist-consequence: read
      x-apievangelist-idempotent: true
  - target: $.paths['/catalog-products/{catalogId}/{gtin}'].get
    description: Tag and classify retrieve-a-product for discovery and agent safety.
    update:
      x-apievangelist-consequence: read
      x-apievangelist-idempotent: true
  - target: $.paths['/customers'].post
    description: Tag and classify create-or-update-a-customer for discovery and agent safety.
    update:
      x-apievangelist-consequence: write
      x-apievangelist-idempotent: false
      x-apievangelist-idempotency-note: >-
        No Idempotency-Key mechanism is supported by this API. Safe retry is
        the caller's problem.
  - target: $.paths['/customers'].get
    description: Tag and classify retrieve-a-list-of-customers for discovery and agent safety.
    update:
      x-apievangelist-consequence: read
      x-apievangelist-idempotent: true
  - target: $.paths['/customers/{customerId}'].get
    description: Tag and classify retrieve-a-customer for discovery and agent safety.
    update:
      x-apievangelist-consequence: read
      x-apievangelist-idempotent: true
  - target: $.paths['/customers/manage-segments'].post
    description: Tag and classify manage-customers-and-segments for discovery and agent safety.
    update:
      x-apievangelist-consequence: write
      x-apievangelist-idempotent: false
      x-apievangelist-idempotency-note: >-
        No Idempotency-Key mechanism is supported by this API. Safe retry is
        the caller's problem.