Endpoints
What endpoints are, endpoint types, and the endpoint lifecycle in agrirouter
An endpoint is a connection point inside an end user's agrirouter account that an application manages. Every software installation or machine that connects to agrirouter becomes an endpoint. Endpoints are the building blocks of agrirouter: all messaging, routing, and data exchange happens between endpoints.
Endpoint Types
When creating an endpoint through the API, you specify one of three types:
| Type | Represents |
|---|---|
cloud_software | A cloud-hosted application acting on behalf of an end user |
virtual_communication_unit | A single physical machine (or group of machines) participating in ISOBUS data exchange |
farming_software | Legacy alias for a direct-to-user application, deprecated, use cloud_software instead |
All three types use the same API and the same lifecycle described below. What differs is what each type represents in the real world: software installations versus individual machines. A VCU is a full-fledged endpoint, registered via its own PUT /endpoints/{externalId} call, with its own external ID, capabilities, and subscriptions.
farming_software is kept for backward compatibility only. New applications should register as cloud_software. The two behave identically today, and farming_software may be removed in a future version of the API.
Communication Units (legacy)
Communication Units (CUs) are physical hardware devices (terminals, telemetry boxes, ISOBUS gateways) that connect to agrirouter using the legacy API. CUs use the communication_unit endpoint type, which is not available in the current API.
As a developer using the current API, you do not need to create CU endpoints. However, you will receive messages from CUs: they remain active participants in the agrirouter ecosystem. When you see a communication_unit sender in your feed, this is a hardware device on a machine sending telemetry data, GPS positions, or device descriptions.
If you are a hardware manufacturer building a physical device, see the Communication Unit integration guide.
Endpoint Lifecycle
Every endpoint goes through a defined lifecycle from creation to removal.
Authorization
The end user must authorize the application before any endpoint can be created in their account. This is an OAuth2-based flow where the user logs into agrirouter and approves the application.
Authorization is a one-time action per end-user account. Once the end user has authorized your application, you can create and manage any number of endpoints in their account, of any type, without prompting them again. If the end user revokes the authorization, all endpoints the application created in that account are deleted and the application can no longer touch the account. To start over, the user has to authorize the application again.
See Authorization and Security for the full authorization flow.9 minEndpoint Creation
Endpoint Creation is a single atomic step: one PUT /endpoints/{externalId} request that creates the endpoint and applies its initial configuration in one go. The request provides everything agrirouter needs:
- A unique external ID (as the path parameter) that identifies this particular instance
- The application and software version the endpoint belongs to, as UUIDs (
application_id,software_version_id) that were registered beforehand in the Developer Portal - The endpoint type (
cloud_software,virtual_communication_unit, or legacyfarming_software) - Capabilities, the technical message types the endpoint can send and receive
- Subscriptions, the message types it wants to receive when other endpoints broadcast (publish) messages
agrirouter responds with the endpoint's assigned endpoint ID. The application stores this ID and uses it in the x-agrirouter-endpoint-id header to identify itself when sending messages. The application's credentials for authenticating to the API come from the separate OAuth client credentials flow, not from this call.
Endpoint Update
After creation, the same PUT /endpoints/{externalId} call can be made again at any time to update the endpoint's capabilities and subscriptions. This is an idempotent operation: each call replaces the endpoint's entire configuration with the new values.
Every PUT request replaces all existing capabilities and subscriptions. Always send the complete set of capabilities and subscriptions in each request to avoid silently losing parts of your configuration.
Communication
Once created, the endpoint can send and receive messages through agrirouter. This is the steady-state phase where the endpoint participates in agricultural data exchange according to the routes configured by the end user.
Deletion
An endpoint can be deleted through two paths:
- The application calls
DELETE /endpoints/{externalId}. - The end user removes it manually from the agrirouter UI.
Either way, the endpoint is removed from the agrirouter account along with all its data, including feed entries and routes.
External IDs
Every endpoint is identified by an external ID: a string that uniquely identifies a specific software instance or machine. The external ID is provided by the application at creation time and is used for:
- Re-creation after deletion: creating the endpoint again with the same external ID after a previous deletion, to resume with the same identity
- Identification: correlating an agrirouter endpoint with the corresponding software instance or machine
The recommended format for external IDs is a URN (Uniform Resource Name), for example urn:mycompany:my-app:user-12345. It gives you global uniqueness and stays readable.
Uniqueness Scope
External ID uniqueness is scoped to the tenant (account). This means:
- The same external ID can be used in different accounts
- But an external ID cannot be used twice within the same account, even by different applications
API Reference
Endpoints are created, updated, and removed through two operations. Open them in the API playground to see the request and response shapes:
Create or update endpoint1 min Delete endpoint1 min