Migrating from Legacy
Map legacy agrirouter terms and concepts to their equivalents in the current API
If you are coming from an earlier integration or older documentation, this page outlines how migrating an existing integration to the current API works, and maps the legacy vocabulary that no longer appears in the current API to its current counterparts.
Migration process
The exact migration path is still being finalized, but the outline below already holds. We will support you along the full migration process.
A migration is seamless:
- No interaction is required by end users.
- Only very little downtime (a few minutes), with no message loss.
The migration alternates between actions on your side and actions on ours. It roughly looks like this:
Create OAuth client credentials (partner)
Create OAuth client credentials for your existing application.
Shut down the old implementation (partner)
Auto-authorize existing users (agrirouter team)
We auto-authorize all of your existing users for the new client.
Move endpoints to the current gateway (agrirouter team)
We configure all of your existing endpoints to be served via the current gateway ("gateway 4").
Start the new implementation (partner)
Migrating your own data is up to you. The stable identifiers — endpoint IDs, external IDs, and tenant IDs — carry over unchanged, so you can either perform a database-level migration of your existing records or resync from scratch based on GET /tenants.
The migration should of course be tested beforehand.
Terminology
The rest of this page maps legacy terms and concepts to their current counterparts.
Renamed concepts
The concept still exists under a different name.
| Legacy term | Now called | Notes |
|---|---|---|
| Onboarding | Endpoint Creation | The flow that registers a new endpoint for an application. See Endpoints. |
| Reconfiguration | Endpoint Update | Updating an existing endpoint, for example changing its capabilities or subscriptions. |
| Routing rule(s) | Route(s) | See Routing on the Messaging concept page. |
| Data types | Message types | The technical message-type identifiers (for example, iso:11783:-10:taskdata:zip) that classify payloads and drive capability declarations. |
| Farming Software | cloud_software | farming_software is still accepted for backward compatibility, but new integrations should register as cloud_software. |
| Telemetry Platform | virtual_communication_unit per machine | The telemetry-platform framing, in which a cloud platform acted as a concentrator for a fleet of machines, is gone. Each machine is now registered directly as its own virtual_communication_unit endpoint under the tenant. |
CU and VCU: not the same thing
The abbreviations look similar and both relate to machines, but they refer to different integrations.
| Term | Surface | What it is | Who creates it |
|---|---|---|---|
CU (Communication Unit, communication_unit) | Legacy API only | A physical hardware device on a machine (terminal, telemetry box, ISOBUS gateway) that connects to agrirouter directly. | Hardware manufacturers, via the legacy onboarding flow. See the Communication Unit guide. |
VCU (Virtual Communication Unit, virtual_communication_unit) | Current API | A regular endpoint that represents a single physical machine in an end user's account. Not hardware: a cloud application that manages the machine creates and operates the VCU on the user's behalf. | Cloud applications, via PUT /endpoints/{externalId} with endpoint_type: "virtual_communication_unit". See the Virtual Communication Units guide. |
CUs are not an endpoint type in the current API and cannot be created through it. They remain active in the agrirouter ecosystem on the legacy surface, so a current-API integration may still receive messages from a communication_unit sender in its feed.
Removed, replaced by a current primitive
The old idea is no longer exposed as such, but the same integration need is covered by a different mechanism in the current API.
| Legacy term | Now handled by |
|---|---|
| Inbox / Outbox | Endpoints exchange messages through POST /messages for sending and the event stream on GET /events for receiving. |
| Push notifications | Server-Sent Events on GET /events. |
| Chunked messages (1 MB client-side chunking) | Transparent server-side chunking. The payload limit is 256 MB and chunking is handled by agrirouter, so applications no longer split or assemble messages themselves. |
Removed, no equivalent
These concepts were specific to the legacy integration model and have no place in the current API.
| Legacy term | Notes |
|---|---|
| Middleware | Not part of the current integration model. |
| Onion Principle | The current API is built on standard HTTP primitives and no longer uses the layered "onion" framing. |
| ARTS | The ARTS integration is not supported. |
| Certificates (TLS client certificates, mTLS) | Authentication is based on OAuth 2.0 client credentials. See Authorization and Security. |
| Router Devices | Legacy-only concept; the current API does not use Router Devices. |
| Base64 line-break rules, 1-based numbering conventions | These legacy encoding conventions do not apply. |