{"openapi":"3.1.0","info":{"title":"Ettajer Developer API","version":"1.1.0","description":"OAuth/API-key secured platform API for AI tools. Success bodies use `{ data }` (+ optional `pagination`). Errors use `{ error: { code, message, details?, requestId } }`. AI controls presentation (themes); Ettajer controls commerce."},"servers":[{"url":"https://www.ettajer.com"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth access token (eta_…) or API key (etsk_live_…)"}},"schemas":{"ErrorBody":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"},"requestId":{"type":"string"}}}}},"Pagination":{"type":"object","required":["nextCursor","hasMore","limit"],"properties":{"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"integer"}}},"SuccessEnvelope":{"type":"object","required":["data"],"properties":{"data":{},"pagination":{"$ref":"#/components/schemas/Pagination"}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}},"security":[{"bearerAuth":[]}],"paths":{"/api/v1/context":{"get":{"operationId":"getContext","summary":"Safe store context for theme AI","security":[{"bearerAuth":[]}],"x-required-scopes":["store:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/store":{"get":{"operationId":"getStore","summary":"Store profile","security":[{"bearerAuth":[]}],"x-required-scopes":["store:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/store/settings":{"get":{"operationId":"getStoreSettings","summary":"Sanitized store settings","security":[{"bearerAuth":[]}],"x-required-scopes":["settings:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/products":{"get":{"operationId":"listProducts","summary":"List products","security":[{"bearerAuth":[]}],"x-required-scopes":["products:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from previous pagination.nextCursor"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/products/{id}":{"get":{"operationId":"getProduct","summary":"Get product","security":[{"bearerAuth":[]}],"x-required-scopes":["products:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/collections":{"get":{"operationId":"listCollections","summary":"List collections","security":[{"bearerAuth":[]}],"x-required-scopes":["collections:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from previous pagination.nextCursor"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/collections/{id}":{"get":{"operationId":"getCollection","summary":"Get collection","security":[{"bearerAuth":[]}],"x-required-scopes":["collections:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/orders":{"get":{"operationId":"listOrders","summary":"List orders","security":[{"bearerAuth":[]}],"x-required-scopes":["orders:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from previous pagination.nextCursor"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/orders/{id}":{"get":{"operationId":"getOrder","summary":"Get order","security":[{"bearerAuth":[]}],"x-required-scopes":["orders:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/customers":{"get":{"operationId":"listCustomers","summary":"List customers","security":[{"bearerAuth":[]}],"x-required-scopes":["customers:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from previous pagination.nextCursor"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/checkout":{"get":{"operationId":"getCheckout","summary":"Checkout summary (no secrets)","security":[{"bearerAuth":[]}],"x-required-scopes":["checkout:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/media":{"get":{"operationId":"listMedia","summary":"List media","security":[{"bearerAuth":[]}],"x-required-scopes":["media:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from previous pagination.nextCursor"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"uploadMedia","summary":"Upload or register media","security":[{"bearerAuth":[]}],"x-required-scopes":["media:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/navigation":{"get":{"operationId":"getNavigation","summary":"Get navigation","security":[{"bearerAuth":[]}],"x-required-scopes":["navigation:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateNavigation","summary":"Update navigation","security":[{"bearerAuth":[]}],"x-required-scopes":["navigation:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes":{"get":{"operationId":"listThemes","summary":"List private themes","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createTheme","summary":"Create draft theme","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:create"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/schema":{"get":{"operationId":"getThemeSchema","summary":"Canonical theme schema","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/{id}":{"get":{"operationId":"getTheme","summary":"Get theme","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateTheme","summary":"Update draft theme","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"archiveTheme","summary":"Archive theme","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/{id}/duplicate":{"post":{"operationId":"duplicateTheme","summary":"Duplicate theme","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:create"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/{id}/publish":{"post":{"operationId":"publishTheme","summary":"Publish theme","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:publish"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/{id}/preview-token":{"post":{"operationId":"createThemePreviewToken","summary":"Issue signed preview URL","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:read","themes:preview"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/{id}/batch":{"post":{"operationId":"applyThemeBatch","summary":"Batch draft theme mutations (pages/sections/tokens/nav)","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/{id}/pages":{"get":{"operationId":"listThemePages","summary":"List theme pages","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createThemePage","summary":"Create theme page","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:write","pages:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/{id}/pages/{pageId}":{"patch":{"operationId":"updateThemePage","summary":"Update theme page","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:write","pages:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteThemePage","summary":"Delete theme page","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:write","pages:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/{id}/sections":{"get":{"operationId":"listThemeSections","summary":"List theme sections","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:read"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createThemeSection","summary":"Create theme section","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/themes/{id}/sections/{sectionId}":{"patch":{"operationId":"updateThemeSection","summary":"Update theme section","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sectionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteThemeSection","summary":"Delete theme section","security":[{"bearerAuth":[]}],"x-required-scopes":["themes:write"],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sectionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Replay-safe key for POST/PATCH/DELETE mutations (24h TTL)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/mcp":{"post":{"operationId":"mcpJsonRpc","summary":"MCP JSON-RPC (tools/list, tools/call)","security":[{"bearerAuth":[]}],"x-required-scopes":[],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional correlation id (echoed on response)"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"mcpDiscovery","summary":"MCP endpoint discovery","responses":{"200":{"description":"Discovery"}}}},"/api/oauth/token":{"post":{"operationId":"oauthToken","summary":"OAuth token exchange / refresh","security":[],"responses":{"200":{"description":"Tokens"}}}}},"x-ettajer-scopes":[{"scope":"store:read","description":"Read store profile and branding"},{"scope":"products:read","description":"Read products and inventory summaries"},{"scope":"collections:read","description":"Read collections"},{"scope":"orders:read","description":"Read orders (no mutations)"},{"scope":"customers:read","description":"Read customers (no mutations)"},{"scope":"checkout:read","description":"Read checkout configuration summaries"},{"scope":"settings:read","description":"Read non-secret store settings"},{"scope":"themes:read","description":"Read private and active themes"},{"scope":"themes:create","description":"Create private draft themes"},{"scope":"themes:write","description":"Update draft theme layouts, sections, and pages"},{"scope":"themes:publish","description":"Publish a draft theme to the live storefront"},{"scope":"themes:preview","description":"Issue short-lived signed preview URLs for private themes"},{"scope":"pages:read","description":"Read custom pages"},{"scope":"pages:write","description":"Create and update theme pages"},{"scope":"media:read","description":"List media assets"},{"scope":"media:write","description":"Upload and register media assets"},{"scope":"navigation:read","description":"Read navigation menus"},{"scope":"navigation:write","description":"Update theme navigation"}],"x-ettajer-default-theme-scopes":["store:read","products:read","collections:read","settings:read","themes:read","themes:create","themes:write","themes:preview","pages:read","pages:write","media:read","media:write","navigation:read","navigation:write"],"x-ettajer-response-contract":{"success":"{ data: T }","list":"{ data: { <resource>: Item[] }, pagination: { nextCursor, hasMore, limit } }","error":"{ error: { code, message, details?, requestId } }","note":"v1 lists use a named resource key inside data (e.g. products), not a bare array.","headers":["X-Request-Id","X-RateLimit-Limit","X-RateLimit-Remaining","X-RateLimit-Reset","Idempotency-Key (request)","Retry-After (429)"],"compatibility":"v1 is the stable Developer API contract. Backward-compatible additions may be introduced. Breaking changes require a new API version (/api/v2)."}}