Legacy API
Documentation for the legacy agrirouter API, kept for existing integrations and migration reference
The legacy agrirouter API is still available for integrations that have not yet migrated to the current API. It supports MQTT and REST, with protobuf-encoded messages on both.
New integrations should use the current API. The legacy API remains available for existing integrations.
Key Differences from the Current API
| Aspect | Legacy API | API |
|---|---|---|
| Protocols | MQTT and REST | REST only (SSE for events) |
| Message format | Protobuf-encoded with envelope structure | JSON request bodies |
| Onboarding | Separate onboarding/reonboarding/revoke REST endpoints | Unified endpoint management |
| Architecture | Multiple endpoints per protocol | 4 gateway endpoints |
MQTT Communication
MQTT gives you two-way, real-time communication with agrirouter. After onboarding, you receive two MQTT topics:
- Measures topic: used to send messages to agrirouter
- Commands topic: used to receive messages and acknowledgements from agrirouter
Your application maintains a persistent MQTT connection and publishes or subscribes to these topics as needed.
REST Communication
The legacy REST protocol uses a one-way polling model:
- Send messages by posting to the outbox URL provided during onboarding.
- Receive messages by polling the inbox URL at regular intervals.
Your application polls for new messages rather than receiving them in real time.
Message Format
All legacy messages use Protocol Buffers (protobuf) encoding with the following header fields:
| Field | Description |
|---|---|
ApplicationMessageId | Unique ID assigned by your application |
ApplicationMessageSeqNo | Sequence number for ordering |
technicalMessageType | The type of message being sent (e.g., iso:11783:-10:device_description:protobuf) |
recipients | Target endpoint IDs |
chunkInfo | Chunking metadata for large messages |
The message envelope wraps the header and the protobuf-encoded payload together for transport.
Error Responses
Legacy responses carry numeric error codes (SYS_*, VAL_*) in the protobuf envelope alongside a human-readable message. These codes remain for partners maintaining legacy integrations. The current API strips them and returns only { "message": "..." }.
Migration Path
Switching gateways between MQTT and HTTP is now allowed in agrirouter 2.0, but data loss is possible during the switch. Plan the transition carefully and make sure no critical messages are in transit.
- New integrations should use the current API exclusively.
- Existing integrations can continue using the legacy API without changes.
- Switching gateways (MQTT to HTTP or vice versa) is supported in agrirouter 2.0 but requires caution.
SDKs
Several SDKs cover the legacy API:
SDKs and Libraries1 min