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

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"
}

{
  "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"
}

{
  "message": "string"
}

{
  "message": "string"
}

{
  "message": "string"
}

{
  "message": "string"
}

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

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`