Create or update endpoint

Create a new endpoint or replace the configuration of an existing one by external ID.

Create a new endpoint, or update an existing one. The first call for a given externalId creates the endpoint. Later calls replace its configuration (capabilities, subscriptions, and endpoint type).

Authorization

AuthorizationBearer <token>

Agrirouter OAuth2 authentication for QA environment.

In: header

Scope: endpoints:manage

Application-defined external ID of the endpoint. SHOULD be formatted as a URN as defined by RFC 8141 (e.g. urn:my-app:endpoint:42). The urn: prefix itself is optional for backwards compatibility, but the value must always contain a namespace identifier and a namespace-specific string separated by a colon. The URN namespace identifier and namespace-specific string allow applications to scope their endpoint IDs in a stable, globally unique way.

Match^([uU][rR][nN]:)?[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*%/?#]+$

Length3 <= length <= 255

Header Parameters

x-agrirouter-tenant-id*string

The farmer's tenant ID in relation to which communication is done.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Optional name of the endpoint, for easier identification in agrirouter web interface. Does not have to be unique. If not specified, the name would be generated automatically.

When provided, must be 1-200 characters long and may contain letters from any script, digits, spaces, and the following special characters: -, _, ., ,, :, @. Names consisting only of whitespace are not allowed as well, which is not expressed in the regex pattern.

It is not guaranteed that this "application-set" name would be used, because user may override it with "user-set" name in agrirouter web interface. Name send via this API cannot override "user-set" name, but it can update "application-set" name at any time and user can choose to switch name back to "application-set".

Match^[\p{L}\p{N} _.,:@\-]+$

Length1 <= length <= 200

application_id*string

The ID of the application that owns the endpoint

Formatuuid

software_version_id*string

The ID of the software version that owns the endpoint

Formatuuid

capabilities*array<>

The effective capabilities of the endpoint, must be subset of the capabilities of software version.

subscriptions*array<>

endpoint_type*EndpointTypeToCreate

Type of an endpoint that can be created via this G4 API. Legacy types such as communication_unit and telemetry_platform cannot be created here; see EndpointType for the full set that may be observed.

farming_software is accepted as a deprecated alias for cloud_software and will be removed in a future revision.

Value in"cloud_software" | "virtual_communication_unit" | "farming_software"

allow_delete_by_user?boolean

Flag indicating whether the user is allowed to delete this endpoint. Note that even when this flag is not set, the user can still force deletion of the endpoint. Applications must handle the ENDPOINT_DELETED event on a best-effort basis. It is also possible that an endpoint is deleted immediately after creation due to a race with the user disconnecting the entire application, so applications should not rely on this flag to prevent endpoint deletion entirely.

Defaultfalse

connections_uri?string

URI pointing to where the user can manage the entity connected to this endpoint, e.g. to disconnect or delete equipment from an equipment vendor. When provided, this URI will be shown when the user attempts to delete the endpoint, instead of the usual deletion dialog, directing them to the vendor's management page.

Formaturi

owner_endpoint_external_id?string

Optional external ID of the endpoint that should own (be the parent of) this endpoint. The referenced owner endpoint must belong to the same tenant and the same application as this endpoint, otherwise the request is rejected. When the owner endpoint is deleted, the endpoints it owns are deleted as well. Note that the owner endpoint must already be processed internally. Since endpoint state is propagated asynchronously, an owner endpoint that was just created may not yet be resolvable

Response Body

`application/json`

curl -X PUT "https://api.agrirouter.com/endpoints/string" \  -H "x-agrirouter-tenant-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",    "software_version_id": "bf49a8b1-ef30-484c-a74f-431a9921fa41",    "capabilities": [      {        "message_type": "iso:11783:-10:taskdata:zip",        "direction": "SEND"      }    ],    "subscriptions": [      {        "message_type": "iso:11783:-10:taskdata:zip"      }    ],    "endpoint_type": "cloud_software"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "external_id": "string",
  "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",
  "software_version_id": "bf49a8b1-ef30-484c-a74f-431a9921fa41",
  "endpoint_type": "cloud_software",
  "tenant_id": "string",
  "capabilities": [
    {
      "message_type": "iso:11783:-10:taskdata:zip",
      "direction": "SEND"
    }
  ],
  "allow_delete_by_user": false,
  "connections_uri": "http://example.com",
  "owner_endpoint_external_id": "string"
}

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "external_id": "string",
  "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",
  "software_version_id": "bf49a8b1-ef30-484c-a74f-431a9921fa41",
  "endpoint_type": "cloud_software",
  "tenant_id": "string",
  "capabilities": [
    {
      "message_type": "iso:11783:-10:taskdata:zip",
      "direction": "SEND"
    }
  ],
  "allow_delete_by_user": false,
  "connections_uri": "http://example.com",
  "owner_endpoint_external_id": "string"
}

{
  "message": "string"
}

{
  "message": "string"
}

{
  "message": "string"
}

{
  "message": "string"
}

Owner (parent) endpoint

An endpoint can be given an owner (parent) endpoint by setting the optional owner_endpoint_external_id field to the external ID of another endpoint. This models a parent–child relationship between two endpoints — for example a platform endpoint that owns the machine endpoints it manages.

The referenced owner endpoint must belong to the same tenant and the same application as the endpoint being created or updated. If it does not — or if the external ID cannot be resolved — the request is rejected with 400.

Because PUT replaces the endpoint's full configuration, the owner is treated like any other attribute: send owner_endpoint_external_id on every request that should keep the owner, and omit it to leave the endpoint without an owner (which also clears a previously set owner).

Endpoint state is propagated asynchronously, so an owner endpoint that was just created may not be resolvable immediately. The gateway retries resolution for a few seconds before giving up. If the request still fails with 400, retry it once the owner endpoint has been created.

Deleting an owner endpoint also deletes all endpoints it owns. See Delete endpoint and the endpoint lifecycle.

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Owner (parent) endpoint

On this page

Create or update endpoint

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

403application/json

413application/json

500

502

503

504

Owner (parent) endpoint

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`