Appearance
API reference
Status: pilot. Draft — generated against the live schema, needs review before publishing.
The OmniCanon API is a REST API over HTTPS.
| Base URL | https://api.omnicanon.com/api/v1/ |
| OpenAPI schema | https://api.omnicanon.com/api/schema/ |
| Interactive docs | https://api.omnicanon.com/api/docs/ |
The schema is the source of truth for field names and types. This reference describes behaviour — the parts the schema does not spell out.
Authentication
Every endpoint except registration and login requires a token. See Authentication.
Error shape
All errors use one envelope. See Errors.
Resources
| Group | Paths |
|---|---|
| Auth | /auth/register/, /auth/token/, /auth/password-reset/, /auth/confirm/ |
| Account | /accounts/me/ |
| Products | /products/, /products/{id}/ |
| Product content | /products/{id}/content/ |
| Product identity | /products/{id}/knowledge/ |
| Product attributes | /products/{id}/attributes/{attribute_id}/ |
| Product images | /products/{id}/images/, /products/{id}/images/{image_id}/ |
| Enrichment | /products/{id}/enrich/, /products/{id}/jobs/, /products/{id}/sources/ |
| Jobs | /jobs/{job_id}/, /jobs/{job_id}/retry/ |
| Reference data | /currencies/, /currencies/{code}/ |
Conventions
- Account isolation. Products and jobs belong to the account that created them. Requesting another account's object returns 404, not 403 — the API does not reveal that the object exists.
- No PATCH, no DELETE on products. A product is edited with
PUT, and it is not deleted through the API. eanis immutable. Changing an EAN would be a different physical product.- Cross-account cache. A product created with an EAN that already has completed content is filled from that record immediately, without enrichment.
- Idempotency.
POST /products/{id}/enrich/accepts anIdempotency-Keyheader. A repeat with the same key returns the same job and does not charge the account twice.
Images
Image URLs are assembled on the client: take the relative file field of ProductImage and prefix it with https://img.omnicanon.com/. The path is built from the product id, so it must never be assembled by hand from ProductImage.id.