API Reference
API reference for the agrirouter gateway API: endpoints, authentication, and request patterns
The agrirouter API is a small REST surface for managing endpoints, exchanging messages, and receiving events.
If you are maintaining an existing integration that uses the legacy protocol, see the Legacy API documentation.
Gateway Endpoints
The API exposes five endpoints:
| Method | Path | Purpose |
|---|---|---|
PUT | /endpoints/{externalId} | Create or update an endpoint |
POST | /messages | Send messages to other endpoints |
GET | /events | Receive events via Server-Sent Events (SSE) |
DELETE | /endpoints/{externalId} | Delete an endpoint |
POST | /confirmations | Confirm received messages |
Base URLs
The API is available in two environments:
| Environment | Base URL |
|---|---|
| QA | https://api.qa.agrirouter.farm |
| Production | https://api.agrirouter.com |
See the URLs appendix for the complete list of environment URLs.
Authentication
Every request requires a Bearer token in the Authorization header. Applications obtain this token via the OAuth2 client credentials flow (see Authorization & Security).
Common Headers
| Header | Value | Description |
|---|---|---|
Content-Type | application/json | All request bodies are JSON |
Authorization | Bearer <token> | JWT from client credentials or endpoint credentials |
Request and Response Patterns
- Request bodies are JSON-encoded.
- Events come in over a Server-Sent Events (SSE) stream from
GET /events. Keep a persistent connection open to receive them in real time. - Payloads arrive inline in events or via a
payload_urithe client downloads directly.