Documentation surfaces
This page now renders the registry-backed versioned OpenAPI document from /api/v1/docs/openapi, which is the canonical JSON spec surface for the current published API contract. Authenticated viewers can also use /api/v1/docs/swagger for the hosted Swagger shell. The companion /api/v1/docs/changelog route serves the JSON-wrapped changelog sourced from docs/api/changelog.md. The older unversioned surfaces at /api/docs/openapi.json and /api/docs/openapi.yaml still exist as compatibility docs endpoints, but they are no longer the primary docs entrypoints.
Canonical business integrations should still prefer /api/v1/** routes, but the app intentionally keeps a small set of non-versioned ingress and compatibility surfaces outside that namespace. Current examples include public Shopify install initiation at /api/shopify/install, compatibility proxy callbacks at /api/shopify/oauth/callback and /api/shopify/callback that both forward to /api/v1/shopify/oauth/callback, canonical webhook ingress at /api/shopify/webhooks, and the remaining compatibility Shopify connection-management routes. Operational endpoints such as /api/health, /api/health/ready, /api/health/migrations, /api/health/stripe, /api/webhooks/*, and /api/metrics intentionally keep route-local JSON, text, or header-centric contracts and should not be assumed to follow the default /api/v1 success envelope. In particular, POST /api/shopify/webhooks is a header-driven ingress contract: 200 means no retry was requested, while 503 plus Retry-After is reserved for retryable durability or fatal-authenticity paths. Use the generated Webhooks details and docs/api/SHOPIFY_WEBHOOKS.md for the current x-ingress-* semantics.
Loading API Documentation...