Send Your First Message

With an active endpoint in place, you can send data through agrirouter. This page covers composing and sending a message.

Prerequisites

Before you begin, make sure you have:

An active endpoint with capabilities configured (see Your First Endpoint)
A valid access token from the client credentials flow (see Your First Endpoint)
The endpoint ID (agrirouter-generated UUID) and tenant ID from the endpoint creation response
A second endpoint to receive the message. The IO-Tool is a good fit.
Your environment URLs (see Environment URLs)

Use the IO-Tool as your test receiver. It acts as a receiving endpoint, so you can verify delivery without standing up a second fully integrated application.

Sending a message

Compose and send

The API uses HTTP headers for message metadata and a binary body for the payload. Send a POST request to the messages endpoint:

POST/messagesOpen API reference

Accepts a single message with metadata carried in headers and the payload as a raw binary body.

Request headers

Authorization: Bearer eyJhbGciOiJFUzI1NiIs...

Content-Type: application/octet-stream

x-agrirouter-endpoint-id: 9f8e7d6c-5b4a-3210-fedc-ba0987654321

x-agrirouter-tenant-id: 12345678-abcd-ef01-2345-6789abcdef01

x-agrirouter-message-type: iso:11783:-10:taskdata:zip

x-agrirouter-is-publish: false

x-agrirouter-direct-recipients: a1b2c3d4-0000-1111-2222-333344445555

x-agrirouter-context-id: my-first-message-001

x-agrirouter-sent-timestamp: 2026-03-20T10:30:00Z

content-length: 102400

Request body

<binary payload: the raw file bytes, not JSON>

Response 200

Empty body. A 200 confirms that agrirouter has accepted the message for delivery.

The message headers consist of:

x-agrirouter-endpoint-id: the agrirouter-generated UUID of your sending endpoint (from the endpoint creation response)
x-agrirouter-tenant-id: the tenant UUID (also from the endpoint creation response)
x-agrirouter-message-type: the message type being sent, which must match a capability declared by your endpoint
x-agrirouter-is-publish: false for direct addressing, true for publishing
x-agrirouter-direct-recipients: comma-separated agrirouter endpoint UUIDs of the recipients. Typically set for direct addressing, usually omitted when publishing. See Choose an addressing mode.
x-agrirouter-context-id: a per-payload application-side identifier, required on every send (max 50 characters). Generate a new value for each payload you send; reuse the same value only when retrying the exact same payload after a failure.
x-agrirouter-sent-timestamp: client-side timestamp in ISO 8601 format. For records collected from in-field devices, this is the timestamp when the record was captured on the machine, not the time the message reaches agrirouter. Devices that buffer data for later transmission should preserve the original capture timestamp.
x-agrirouter-teamset-context-id (optional): identifies the set of physically connected machines (typically a tractor and its connected implements) the payload belongs to. Required in practice for EFDI device descriptions and time logs, optional and usually omitted for everything else. The same identifier is also called the TeamSet ID or context ID in EFDI documentation. See TeamSet Context ID for the full reference.

Choose an addressing mode

There are two ways to address messages:

Direct addressing: set x-agrirouter-is-publish: false and provide x-agrirouter-direct-recipients with one or more endpoint UUIDs. The message is delivered only to the named endpoints.
Publishing: set x-agrirouter-is-publish: true and usually omit x-agrirouter-direct-recipients. The message is delivered to every endpoint that has subscribed to the message type and is permitted to receive it by the account's routes.

Pick the mode based on who triggers the send:

Interactive processes, where a user initiates the transfer to a specific target (for example, sending an application map from an FMIS to a specific machine), are a good fit for direct addressing.
Automated processes with an open-ended set of receivers (for example, telemetry data streamed from machines to any subscribed platform), are a good fit for publishing.

A publishing send can also carry a list of recipients in x-agrirouter-direct-recipients, in which case those recipients receive the message in addition to any subscribers. This is uncommon and is not a separate addressing mode, just a quirk of the two headers interacting: the conceptual model is still direct or publish.

Message delivery requires three conditions to all be true:

The sender has a capability to send the message type
The recipient has a capability to receive the message type
A route exists from sender to recipient for that message type

Routes are configured by the account owner in the agrirouter UI. Your application cannot create them. If messages are not being delivered, check the routing configuration before debugging your code.

Understand the response

A 200 response means agrirouter has accepted the message and validated the addressing and routing. This is the only feedback the sender gets: there is no asynchronous delivery confirmation or delivery status event.

If the request fails, common causes include:

400: invalid request (malformed headers, missing required fields, unsupported message type), or no route exists from your endpoint to a specified direct recipient
403: the endpoint ID in the request header does not belong to a tenant your access token is authorized for
413: payload exceeds the 256 MB size limit

The response body is always a JSON object with a single message field. See the Errors reference for the complete status code list.

agrirouter does not notify the sender whether recipients have actually received or confirmed the message. To verify delivery during development, check the receiving side: for example, use the IO-Tool, or listen for MESSAGE_RECEIVED events on the recipient endpoint.

Next steps

Now that you have sent a message, receive one on the other side.

Receive Your First Message4 min