SDKs
Thin clients, and an escape hatch that actually works
Types from the same schema the API validates against, retries that honour the rate headers, and signature verification you would otherwise get subtly wrong. Everything else is a raw request away.
- Typed from
- The API schema
- Major version
- Tracks /v1
- Raw requests
- Always available
Definition
What does a passport API client library give you?
Types generated from the schema the API validates against, so a wrong field fails at compile time rather than as a runtime error. Retry and backoff that honour rate limit headers. Webhook signature verification over the raw body. And an escape hatch for requests the client does not model.
None of it is essential. Every payload is JSON following a published standard, so an integration written with an HTTP client and no SDK at all is a completely reasonable choice — and one some security policies require.
Clients
What is available
| Language | Typical use | Notes |
|---|---|---|
| TypeScript / Node.js | Storefronts, webhook receivers, serverless issuing | Types generated from the schema; works in edge runtimes |
| Python | Data pipelines, PLM and ERP integration jobs | Fits where the sustainability data work already happens |
| Go | High-throughput event ingestion services | For services writing events continuously rather than in batches |
| Anything else | Direct HTTP | JSON, GS1 and W3C standards — no client required |
Shape
What using one looks like
import { CirculeID } from '@circuleid/sdk';
const circuleid = new CirculeID({ apiKey: process.env.CIRCULEID_API_KEY });
const passport = await circuleid.passports.create({
gtin: '09506000134352',
productGroup: 'textiles',
level: 'model',
record: { name: 'Merino Crew Knit' },
});
// The gap report is part of the response, not a separate call:
// which fields the delegated act still requires for this group.
console.log(passport.gaps);
// Escape hatch — same auth, same retries, no abstraction in the way.
await circuleid.request('POST', '/v1/events', { body: epcisEvent });What they handle
The parts worth not writing yourself
Generated types
From the same schema the API validates against, so the two cannot drift.
Retry and backoff
Reads the rate limit headers and applies jitter, so parallel workers behave.
Signature verification
Over the raw body, in constant time — the two details people get wrong.
Pagination
Cursor handling for long event histories, exposed as an async iterator.
Escape hatch
Arbitrary requests with the same auth and retry behaviour as the typed calls.
Predictable versioning
Major tracks the API version; minor adds, never redefines.
Answers
Frequently asked questions
What do the SDKs do beyond wrapping HTTP?
Three things worth having: types generated from the same schema the API validates against, so a wrong field is a compile error rather than a 400; retry and backoff that honour the rate limit headers; and webhook signature verification, which is easy to implement subtly wrong by hashing a re-serialised body instead of the raw one.
Can I still make raw requests?
Yes, and the clients are built to allow it. Every one exposes an escape hatch that sends an arbitrary request with the same authentication and retry behaviour. An SDK that forces you through its abstractions is one you will fight the first time you need something it did not anticipate.
How are SDK versions related to API versions?
The major version tracks the API version, so a v1 client speaks to /v1. Minor releases add endpoints and fields as the API grows. A client will not silently change behaviour under you within a major version — new fields appear, existing ones do not change meaning.
Which language should we use for the issuing pipeline?
Whichever your ops team already runs. The issuing path is a scheduled job talking to your PLM and to us; it is not performance sensitive and it will be maintained by whoever maintains your other integrations. Choosing a language nobody there knows is the most common avoidable mistake here.
Are the clients open source?
The clients are generated from a published schema, and the generated source is readable and vendorable. If you need to fork one to satisfy an internal policy, nothing in the wire protocol depends on our client — every payload follows GS1 or W3C standards you could implement directly.
Next step
Start in the language your team already runs
The issuing pipeline will be maintained by whoever maintains your other integrations. Optimise for that, not for novelty.