API Evangelist enrichment overlay — Medusa Store API

overlay: 1.0.0
info:
  title: API Evangelist enrichment overlay — Medusa Store API
  version: 1.0.0
extends: ../openapi/medusa-store-openapi.yaml
x-provenance:
  generated: '2026-08-26'
  method: generated
  source: >-
    Authored by the API Evangelist enrichment pipeline against
    openapi/medusa-store-openapi.yaml (Medusa Storefront API 2.19.0, harvested verbatim from
    raw.githubusercontent.com/medusajs/medusa). This overlay records OUR annotations only —
    the original spec is never mutated. Every statement below is evidenced by an artifact in
    this repository.
actions:
  - target: $.info
    description: Record the real base-URL situation and the discovery surface.
    update:
      x-apievangelist-base-url-note: >-
        Medusa is self-hosted. The two declared servers are http://localhost:9000 (the local
        development default) and https://api.medusajs.com, which had no DNS A/AAAA record
        when probed on 2026-08-26. The production base URL is the merchant's own deployment
        or Medusa Cloud backend domain.
      x-apievangelist-contract-source: https://raw.githubusercontent.com/medusajs/medusa/develop/www/apps/api-reference/specs/store/openapi.full.yaml
      x-apievangelist-llms-txt: https://docs.medusajs.com/llms.txt
      x-apievangelist-mcp-server: https://docs.medusajs.com/mcp
      x-apievangelist-agent-skills: https://github.com/medusajs/medusa-agent-skills
  - target: $.info
    description: Cross-link the derived runtime-semantics artifacts.
    update:
      x-apievangelist-artifacts:
        conventions: conventions/medusa-conventions.yml
        errors: errors/medusa-problem-types.yml
        authentication: authentication/medusa-authentication.yml
        lifecycle: lifecycle/medusa-lifecycle.yml
        events: asyncapi/medusa-events.yml
        data_model: data-model/medusa-data-model.yml
        rate_limits: rate-limits/medusa-rate-limits.yml
  - target: $.components.securitySchemes.jwt_token
    description: Note the store-side key requirement that the scheme alone does not express.
    update:
      x-apievangelist-note: >-
        Authentication is not sufficient on its own. EVERY /store route also requires an
        x-publishable-api-key header, which scopes the request to one or more sales
        channels. It is a routing/scoping key, not a credential.
  - target: $.paths.*.*.responses.409
    description: Record the fixed CONFLICT message and the retry affordance.
    update:
      x-apievangelist-note: >-
        Medusa replaces the thrown message on a 409 with a fixed string — "The request
        conflicted with another request. You may retry the request with the provided
        Idempotency-Key." — so the body never explains the conflict. Retry with an
        Idempotency-Key; see conventions/medusa-conventions.yml.
  - target: $.paths.*.*
    description: Record the absence of a rate-limit signal.
    update:
      x-apievangelist-rate-limit-signal: >-
        No 429 response, no RateLimit-*/X-RateLimit-* header and no Retry-After is declared
        on any operation in this document. Throttling, if any, is the merchant's own
        infrastructure.