API · 0.1-draft
The bearing data API, as a contract first.
These endpoints describe the API we intend to build. Nothing here can be called today, and the examples are static text, not responses from a server.
Proposed contract — no live endpoints
Endpoints
Proposed endpoints
Generated from the draft OpenAPI file. The rollout column is intent, not a date.
| Endpoint | Purpose | Planned order |
|---|---|---|
GET /v1/products | Search public products | First, after real data |
GET /v1/products/{id} | Get a versioned product record with attributes, evidence, missing fields and relationships | First, after real data |
GET /v1/schemas/{family} | Get a family schema release with applicability rules | First |
POST /v1/resolve | Resolve identifiers to exact or candidate products with explanations | Second |
POST /v1/catalog-audits | Create an authorized private audit job | Later (private) |
POST /v1/enrichment-jobs | Start a scoped enrichment job with explicit source permissions | Later (private) |
GET /v1/jobs/{id} | Job status, counters, errors and result access for the authorized tenant | Later (private) |
GET /v1/suppliers | Source-backed supplier identities and relationships (when available) | When feeds exist |
Example
Resolving a messy identifier
Resolution returns candidates and what is missing — it never invents an exact match.
POST /v1/resolve
Authorization: Bearer <token>
Content-Type: application/json
{
"items": [
{ "ref": "row-17", "description": "DEMO 101 brg open", "attributes": { "bore": "25" } }
]
}200 OK
{
"schema_version": "0.1-draft",
"data_version": "<dataset version>",
"results": [
{
"ref": "row-17",
"status": "multiple_candidates",
"candidates": [
{ "product_id": "demo-product-001", "designation": "DEMO-101-OPEN",
"supports": ["series token", "closure: open"],
"missing": ["manufacturer confirmation", "clearance class"] },
{ "product_id": "demo-product-002", "designation": "DEMO-101-SEALED",
"conflicts": ["closure: sealed vs. open"] }
],
"explanation": "Series matches two variants; closure favours the first but evidence is insufficient to accept."
}
]
}Design requirements
Rules the API will follow
Auth and tenant isolation
Bearer tokens with scopes. Private results are authorized, not merely hidden behind unguessable IDs.
Bounded input, cursor pages
Limits on query length and batch size; cursor pagination for lists.
Explicit versions
Every response states schema and data versions plus timestamps.
Idempotent jobs
Mutating job endpoints require an Idempotency-Key; retries never duplicate work or overwrite reviewed values.
Async for large work
Audits and enrichment are queued jobs with status, counters and partial results.
Honest errors
Stable error codes, rate-limit signalling and request IDs.
429 Too Many Requests
{ "error": { "code": "rate_limited", "message": "Retry after 30 seconds.", "request_id": "req_..." } }
Want early access
when it goes live?
Tell us which endpoints and volumes you need. We will contact you when real access exists — not before.