← Developers

API

Versioned REST under /api/v1. See OpenAPI 1.1.0.

Compatibility policy

• v1 is the stable Developer API contract.
• Backward-compatible additions may be introduced without a new version.
• Breaking changes require a new API version (/api/v2). We will not silently break v1 clients.

Response contract

Success: { "data": … }
List:    { "data": { "products": […] }, "pagination": { "nextCursor", "hasMore", "limit" } }
Error:   { "error": { "code", "message", "details?", "requestId" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Mutations accept Idempotency-Key. On 429: Retry-After.

In-memory rate limiting (RATE_LIMIT_BACKEND=memory) is not multi-instance safe. Use Redis in production.

Core endpoints

• GET /api/v1/context
• GET /api/v1/store
• GET /api/v1/products?limit=&cursor=
• GET /api/v1/collections
• GET /api/v1/orders (read-only)
• GET/POST /api/v1/themes
• GET /api/v1/themes/schema
• POST /api/v1/themes/:id/batch
• POST /api/v1/themes/:id/sections
• POST /api/v1/themes/:id/preview-token
• POST /api/v1/themes/:id/publish
• GET/POST /api/v1/media
• GET/PATCH /api/v1/navigation
• POST /api/v1/mcp

Commerce write APIs are intentionally absent.

AI guide: AI Integration