Authentication, endpoints, request/response shapes, and error handling - grounded in the same API that powers the Dashboard.
Four things to know before your first request.
Attach your key to the X-API-Key header on every call - the Authentication guide below walks through a full example.
Local development defaults to http://localhost:8000. We'll give you your deployment's base URL when your key is issued.
Look for an /api/v1 prefix before you assume a response shape is locked in - unprefixed paths are the older, pre-versioning endpoints.
Request and response bodies are JSON on every data endpoint - /metrics is the one exception.
Pass your key on the X-API-Key header. Endpoints under System (/live, /health, /ready, /metrics) don't require one.
Example request
curl https://<your-api-host>/api/v1/suppliers \
-H "X-API-Key: YOUR_API_KEY"Example response
{
"success": false,
"error": {
"code": "OCI-AUTH-001",
"message": "Missing API Key",
"category": "authentication",
"details": null
},
"timestamp": "2026-01-14T09:12:00Z",
"request_id": "req_8f21a3"
}The endpoint groups actually mounted on the API today.
Full CRUD over inspection records - quality, risk, and shelf-life analytics come back in the response metadata. /api/v1/inspections
Full CRUD over supplier records, filterable and sortable. /api/v1/suppliers
KPIs, trends, and recommendations - the same data the Executive Dashboard renders. /dashboard
Query how a supplier or market stacks up - each response breaks the score into its underlying components instead of one opaque number. /api/v1/intelligence/supplier, /api/v1/intelligence/market
Arrival outcomes scored against inspection and shipment history. /api/v1/intelligence/arrival
Pull how much a supplier has cost you in claims, and how often, aggregated for reporting. /api/v1/intelligence/claims
Wire these into your uptime monitoring and metrics scraper - they skip the X-API-Key check entirely so infrastructure tooling can reach them without a key. /live, /health, /ready, /metrics
A list request against the Suppliers endpoint, start to finish.
GET /api/v1/suppliers?limit=2
{
"success": true,
"data": [
{
"supplier_id": "sup_1029",
"name": "Rio Verde Farms",
"code": "RVF-01",
"country": "MX",
"email": "ops@example.com",
"is_active": true,
"created_at": "2026-01-14T09:12:00Z",
"metadata": {}
}
],
"meta": {
"limit": 2,
"offset": 0,
"total": 34,
"returned": 1,
"has_more": true
},
"timestamp": "2026-01-14T09:12:00Z",
"request_id": "req_8f21a3"
}Every error response carries one of these codes, not just an HTTP status.
| Code | Category | Meaning |
|---|---|---|
OCI-VAL-001 | Validation | Request body failed validation |
OCI-VAL-002 | Validation | sort_by value isn't supported on this endpoint |
OCI-VAL-003 | Validation | Pagination offset/limit is out of range |
OCI-AUTH-001 | Authentication | X-API-Key header is missing |
OCI-AUTH-002 | Authentication | API key is invalid, inactive, or expired |
OCI-AUTHZ-001 | Authorization | Key doesn't carry the required role |
OCI-BIZ-003 | Business | Resource already exists |
OCI-BIZ-004 | Business | Resource not found |
OCI-SEC-002 | Security | Request body exceeds the size limit |
OCI-RATE-001 | Rate limiting | Per-key or per-IP quota exceeded |
Rate limits are configured per deployment. Applications should honor HTTP 429 responses and Retry-After headers.
Per API key
Each key draws from its own quota - exact limits vary by deployment.
Per IP address
A second, independent quota applies per client IP as an additional layer of protection.
There's no official client library yet - integrate directly against the REST API with any HTTP client that can send headers and parse JSON. Tell us what language you're working in, and we'll help you get started.
Contact EngineeringContact engineering and we'll issue one, scoped to the roles your integration needs.
Success responses wrap your data in {success, data, meta, timestamp, request_id}. Errors use the same envelope with an error object instead - see the examples above.
Your key authenticated fine, but doesn't carry the role that endpoint requires. Contact us if you need broader access.
Look for a 422 status and an OCI-VAL-* code in the error object - see Error codes above for the full catalog.
Not through a separate environment today - there's no staging or sandbox instance yet. Contact us and we'll help you integrate safely.
Book a walkthrough with our team, or explore the live dashboard yourself.