Cloud Software
How to integrate a cloud-hosted application with agrirouter as a cloud_software endpoint
This is the integration path for cloud-hosted applications that exchange data with agrirouter on behalf of end users, registered as the cloud_software endpoint type. For the conceptual overview, see cloud_software.
If your application also represents physical machines (tractors, implements, ISOBUS units), each machine is registered as a separate virtual_communication_unit endpoint. See the Virtual Communication Units guide for that flow. Any cloud_software application can do this; there is no separate endpoint type for fleet management.
Typical Capabilities
A cloud_software endpoint typically supports these message types:
| Direction | Message Types |
|---|---|
| Receive | TaskData (ISO 11783), EFDI Device Description, EFDI Time Log, GPS positions |
| Send | TaskData (ISO 11783), Shape files |
Your actual capabilities depend on your application's functionality. Declare only the message types you genuinely support.
Integration Steps
Register as an App Provider
Sign up for an agrirouter developer account and register your application. You receive an application_id and a software_version_id that identify your application and its current version on the platform.
Implement the Authorization Flow
Your endpoint requires user authorization via the OAuth2-based consent flow. Users typically find your application through the agrirouter Solution Finder and arrive at your site via the Deep URL you provided during registration. Once the user lands on your site, redirect them to the agrirouter authorization URL. After the user grants access, the browser is redirected back to your redirect_uri with the original state parameter. No authorization code or token is returned; the authorization is recorded server-side.
Create the Endpoint
With a valid access token from the client credentials flow (see Access Tokens), create an endpoint in the user's agrirouter account.
Send a single PUT /endpoints/{externalId} request with:
- A unique
externalIdfor this endpoint instance (in the URL path) - Your client credentials JWT in the
Authorization: Bearerheader - Capabilities: the message types your endpoint can send and receive, with directions
- Subscriptions: the message types your endpoint wants to receive via publish/subscribe
- The
endpoint_typefield set tocloud_software
This single request creates the endpoint with its full configuration. Call the same endpoint again at any time to update capabilities and subscriptions.
Each PUT request replaces all existing capabilities and subscriptions. Always include the complete set of both in every update.
Existing integrations that register endpoints as farming_software continue to work using the steps on this page, but new integrations should use cloud_software. farming_software is a legacy value kept for backward compatibility and may be removed in a future version. See Migrating from the Legacy API for the full mapping.
Configure Routes
The farmer or contractor configures routes in the agrirouter UI to connect your endpoint with their other endpoints.
Routes between two cloud software applications are not auto-created: the end user must create them manually. Managed routes automatically bridge machinery (virtual_communication_unit) and cloud software (cloud_software, or legacy farming_software) endpoints when both declare compatible capabilities. See Data Flow Control for the conceptual model.
Exchange Messages
With capabilities, subscriptions, and routes in place, your application can send and receive messages through agrirouter.
- Receiving: open a Server-Sent Events connection on
GET /eventsto receive incoming messages. - Sending: POST messages to
/messages, addressing them to specific endpoints or publishing them to all subscribers.
Managing a Fleet of Machines
If your application represents physical machines (tractors, implements, ISOBUS units), register each machine as its own virtual_communication_unit endpoint via its own PUT /endpoints/{externalId} call. Each VCU has its own external ID, capabilities, subscriptions, feed, and events stream. Any cloud_software application can do this; there is no separate endpoint type for fleet management.
Testing with IO-Tool
During development, use the IO-Tool to simulate message exchange. It acts as a counterpart endpoint, so you can send test messages to your application and verify that your application sends correctly.
IO-Tool3 minMessage Exchange Patterns
Receiving Telemetry from Machines
A common pattern for cloud software:
- A machine sends EFDI time logs and GPS data to agrirouter, either through a legacy CU or through a VCU endpoint your application registered for that machine.
- The data is routed to your endpoint based on the configured routes.
- Your application receives events on the SSE connection to
GET /eventsand downloads the payloads. - Confirm receipt to remove messages from the feed.
Sending Task Plans to Machines
- Your application creates a TaskData file (ISO 11783 XML).
- Send the TaskData to agrirouter, addressing specific endpoints or publishing to subscribers.
- The CU or VCU receives the task and loads it on the machine.
API Reference
Open the operations a cloud_software integration uses in the API playground: