API reference
Every endpoint, grouped by resource
Passports, events, credentials and resolution. The error contract, pagination and idempotency rules below apply uniformly across all four.
- Base URL
- api.circuleid.com
- Version
- /v1
- Auth
- Bearer
Definition
What endpoints does the passport API expose?
Four groups. Passport endpoints issue, read, update and version the product record. Event endpoints append and query EPCIS 2.0 supply chain events. Credential endpoints issue, verify and revoke signed claims. Resolution endpoints serve the public GS1 Digital Link path that a scanned data carrier follows.
If you have not read the API model yet, start there. The relationships between these four decide which one you should be calling, and that is the choice most integrations get wrong first.
Endpoints
Passports
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/passports | Issue a passport against a GS1 identifier |
| GET | /v1/passports/{id} | Read the full record your key is entitled to |
| PATCH | /v1/passports/{id} | Update the record; material changes are versioned |
| GET | /v1/passports/{id}/gaps | Fields the product group’s delegated act still requires |
| GET | /v1/passports/{id}/versions | The record’s version history |
| GET | /v1/passports | List and filter passports in your tenant |
Endpoints
Events
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/events | Append one EPCIS 2.0 event |
| POST | /v1/events/bulk | Asynchronous bulk ingestion; returns a job |
| GET | /v1/events | Query by object identity, business step or time |
| GET | /v1/jobs/{id} | Status of a bulk ingestion job |
Endpoints
Credentials
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/credentials | Issue a signed claim against a passport |
| GET | /v1/credentials/{id} | Retrieve a credential and its status |
| POST | /v1/credentials/{id}/revoke | Revoke; verification fails from this point |
| POST | /v1/credentials/verify | Verify a credential you were presented |
Endpoints
Resolution
| Method | Path | Purpose |
|---|---|---|
| GET | /01/{gtin} | GS1 Digital Link resolution — the path a scan takes |
| GET | /01/{gtin}/21/{serial} | Resolution for an item-level passport |
Conventions
Errors, pagination and idempotency
# Validation errors return every problem at once.
HTTP/1.1 422 Unprocessable Entity
{
"error": "validation_failed",
"problems": [
{ "field": "materials[0].share", "constraint": "must sum to 1.0" },
{ "field": "carbonFootprint.method", "constraint": "required for this group" }
]
}
# Pagination is cursor-based: an offset would skip or repeat
# records as new events arrive while you are reading.
GET /v1/events?object=01/09506000134352&cursor=ev_8f21...
# Send an idempotency key on any write you might retry.
POST /v1/passports
Idempotency-Key: 6f1c9a7e-... # a repeat returns the original resultAnswers
Frequently asked questions
What does an error response look like?
A conventional HTTP status with a structured body naming the error, the field that failed and the constraint it violated. Validation errors are returned in full rather than one at a time, so a malformed product record surfaces every problem in one response instead of over five round trips.
How is pagination handled?
Cursor-based, not offset-based. Event histories grow while you are reading them, and an offset would silently skip or repeat records as new events arrive. The cursor is opaque and stable; pass the one returned by the previous page and stop when none comes back.
Are writes idempotent?
They can be, and should be. Send an idempotency key on any write you might retry, and a repeat with the same key returns the original result rather than creating a second passport or a duplicate event. Without one, a network timeout on a write leaves you unable to tell whether it applied.
What is the difference between reading a passport and resolving one?
Reading is authenticated and returns what your API key entitles you to. Resolving is what a scan does: public, anonymous, cacheable, and returning the tier the caller’s credentials allow — which for most callers is the public tier. They are separate paths with different performance and privacy properties.
Next step
Issue one against a sandbox key
The fastest way to judge an API is to send it a real product record and read what comes back.