Developer Documentation

API Overview

Connect edge variables, trigger webhooks, and map logistics pipelines. Build robust scripts directly interfacing with the core operating system.

1. Authentication

Every request must present a valid Bearer token in the `Authorization` header. Tokens are requested using standard OAuth2 Client Credentials grant flow and expire after 1 hour.

Authorization Header:Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Token Exchange Snippet
1# Authenticate and retrieve bearer token
2curl -X POST https://api.forma.ag/v1/auth/token \
3 -H class="text-forma-yellow">"Content-Type: application/json" \
4 -d class="text-forma-yellow">'{"client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET"}'

2. Ingest Events

Submit scale metrics, reefer temperature indexes, or labor updates to the processing queue. Event payloads undergo schema validation against the event type.

Valid Event Types
  • • silo_reading (silo weights telemetry)
  • • FCR_log (broiler feed scale logs)
  • • reefer_coordinate (carrier GPS/temp tracker logs)
Push Event Payload Snippet
1# Push edge scale event
2curl -X POST https://api.forma.ag/v1/events \
3 -H class="text-forma-yellow">"Authorization: Bearer YOUR_ACCESS_TOKEN" \
4 -H class="text-forma-yellow">"Content-Type: application/json" \
5 -d '{
6 class="text-forma-yellow">"event_type": class="text-forma-yellow">"silo_reading",
7 class="text-forma-yellow">"facility_id": class="text-forma-yellow">"fac_01hj38",
8 class="text-forma-yellow">"payload": {
9 class="text-forma-yellow">"silo_id": class="text-forma-yellow">"silo_west_04",
10 class="text-forma-yellow">"weight_kg": 4820.5,
11 class="text-forma-yellow">"timestamp": class="text-forma-yellow">"2026-06-03T04:10:00Z"
12 }
13 }'
API Policies

Rate Limits & Webhooks

Standard client rate limits permit up to 10,000 requests per minute. Limits are monitored via HTTP response headers:

• X-RateLimit-Limit: 10000
• X-RateLimit-Remaining: 9942
• X-RateLimit-Reset: 14
SDK Packages

SDK Tools & Full Docs

Official SDK libraries are maintained for Python, Node.js, and Go. All packages include strict TypeScript bindings and telemetry caching nodes.

Full Documentation PortalDownload SDK libraries