Docs: API | Omnislice

The API is REST over HTTPS, JSON in and JSON out. Everything the interface does, it does through this API — there is no private surface that the product uses and you cannot.

Authentication

Keys are issued per project and carry an explicit scope list. Send the key as a bearer token.

curl https://api.omnislice.com/v1/products \
  -H "Authorization: Bearer $OMNISLICE_API_KEY" \
  -H "Content-Type: application/json"

Careful

A secret key is a full-access credential for its scopes. Keep it server-side, never ship it in a browser bundle or a mobile app, and rotate it the moment it appears in a log, a screenshot or a support ticket.

Conventions

Authorizationheaderrequired: Bearer <key>. Keys are project-scoped; the project never needs to be repeated in the path.
Idempotency-Keyheader: Accepted on every write. Retrying with the same key returns the original result instead of creating a second record.
expandquery: Comma-separated relations to inline, e.g. expand=variants,media. Everything else comes back as an identifier.
fieldsquery: Trims the response to the fields you name. Worth using on list endpoints over large catalogs.

Timestamps are ISO 8601 in UTC. Money is an integer of minor units plus a currency code — never a float.

Pagination

List endpoints are cursor-paginated. Read next_cursor from the response and pass it back as cursor; a null cursor means you have reached the end.

GET /v1/orders?limit=100&cursor=b3JkZXJfMDFI...&status=confirmed

Offset pagination is not supported on purpose: catalogs and order books change while you page through them, and offsets silently skip and duplicate records when they do.

Errors

Errors return the appropriate HTTP status with a machine-readable body.

{
  "error": {
    "type": "validation_error",
    "message": "variant.sku must be unique within the project",
    "field": "variants[2].sku",
    "request_id": "req_01HQ3M8ZK9"
  }
}

Status	Type	Meaning
400	`validation_error`	The request is malformed or a field is invalid
401	`authentication_error`	Missing, revoked or malformed key
403	`permission_error`	The key's scopes do not cover this call
404	`not_found`	No such record in this project
409	`conflict`	Concurrent modification; re-read and retry
429	`rate_limited`	Back off; see the retry header
5xx	`server_error`	Ours. Retry with backoff and quote the `request_id`

Always log request_id. It is the fastest route to an answer from support.

Rate limits

Limits are per key and communicated on every response, so a well-behaved client never has to guess.

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the window
`X-RateLimit-Remaining`	Requests left
`X-RateLimit-Reset`	Unix seconds until the window resets
`Retry-After`	Seconds to wait, sent with a 429

Bulk work belongs in the bulk endpoints rather than in a loop of single writes — a 5,000-row import is one job, not 5,000 requests.

Versioning

The version is in the path. Additive changes — new fields, new endpoints, new enum values — ship inside a version, so parse defensively and ignore what you do not recognise. Breaking changes get a new version and an announced support window for the old one.

Next: Webhooks, for the events you should not be polling for.