Programmatic access to your supply chain data. Integrate batches, shipments, and farm records directly into your systems with our RESTful API.
All API requests require a valid API key passed as a Bearer token in the Authorization header. API keys are scoped to your organization and can be created from Settings.
Authorization: Bearer your-api-key-hereAPI keys have scopes that control access. The read scope is required for all GET endpoints.
API requests are rate-limited per key. The default limit is 1,000 requests per hour. Rate limit headers are included in every response.
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1700000000When the limit is exceeded, the API returns a 429 status with a retry_after field in seconds.
/api/v1/batchesRetrieve collection batches with filtering and pagination
/api/v1/shipmentsAccess shipments with readiness scores and compliance data
/api/v1/farmsQuery registered farms with compliance status
Retrieve collection batches for your organization. Supports filtering by status and pagination.
status — Filter by batch status (collecting, completed, aggregated, shipped)
limit — Number of results (default: 100, max: 500)
offset — Offset for pagination (default: 0)
curl -X GET "https://app.origintrace.io/api/v1/batches?status=completed&limit=50" \
-H "Authorization: Bearer fw_abc12345..."{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"farm_id": "...",
"agent_id": "...",
"status": "completed",
"total_weight": 1250.5,
"bag_count": 25,
"notes": null,
"collected_at": "2024-01-15T10:30:00Z",
"created_at": "2024-01-15T10:30:00Z"
}
],
"meta": {
"total": 142,
"limit": 50,
"offset": 0
}
}Retrieve shipments for your organization with readiness scores and compliance decisions.
status — Filter by shipment status (draft, ready, shipped, cancelled)
limit — Number of results (default: 100, max: 500)
offset — Offset for pagination (default: 0)
curl -X GET "https://app.origintrace.io/api/v1/shipments?status=ready" \
-H "Authorization: Bearer fw_abc12345..."{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"shipment_code": "SHP-ORG1-ABC123",
"status": "ready",
"destination_country": "Netherlands",
"destination_port": "Rotterdam",
"buyer_company": "Barry Callebaut",
"commodity": "Cocoa",
"total_weight_kg": 25000,
"total_items": 50,
"readiness_score": 92,
"readiness_decision": "go",
"estimated_ship_date": "2024-02-15",
"created_at": "2024-01-20T08:00:00Z"
}
],
"meta": {
"total": 12,
"limit": 100,
"offset": 0
}
}Retrieve registered farms for your organization with compliance status.
compliance_status — Filter by compliance status (pending, approved, rejected)
limit — Number of results (default: 100, max: 500)
offset — Offset for pagination (default: 0)
curl -X GET "https://app.origintrace.io/api/v1/farms?compliance_status=approved&limit=100" \
-H "Authorization: Bearer fw_abc12345..."{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"farmer_name": "Adebayo Ogundimu",
"farmer_id": "NGA-12345",
"phone": "+2348012345678",
"community": "Ondo West",
"area_hectares": 3.5,
"commodity": "cocoa",
"compliance_status": "approved",
"created_at": "2024-01-10T12:00:00Z"
}
],
"meta": {
"total": 320,
"limit": 100,
"offset": 0
}
}API keys can be managed through the internal API (requires session authentication as an admin user).
curl -X POST "https://app.origintrace.io/api/keys" \
-H "Content-Type: application/json" \
-H "Cookie: <session-cookies>" \
-d '{
"name": "Production Integration",
"scopes": ["read"],
"expires_in_days": 365,
"rate_limit_per_hour": 2000
}'
// Response includes the full key ONLY on creation:
{
"key": { "id": "...", "key_prefix": "a1b2c3d4", "name": "Production Integration", ... },
"secret": "a1b2c3d4e5f6...full-64-char-key",
"message": "Store this key securely. It will not be shown again."
}curl "https://app.origintrace.io/api/keys" \
-H "Cookie: <session-cookies>"
// Response (key hash is never returned):
{
"keys": [
{
"id": "...",
"key_prefix": "a1b2c3d4",
"name": "Production Integration",
"scopes": ["read"],
"last_used_at": "2024-01-20T15:30:00Z",
"status": "active",
"created_at": "2024-01-01T00:00:00Z"
}
]
}curl -X DELETE "https://app.origintrace.io/api/keys?id=key-uuid-here" \
-H "Cookie: <session-cookies>"
// Response:
{ "success": true, "message": "API key revoked" }The API uses standard HTTP status codes. All error responses include a JSON body with an error field.
401Invalid or missing API key403Insufficient scope for the requested resource429Rate limit exceeded — check retry_after field500Internal server error{
"error": "Invalid or expired API key"
}