Endpoints

For the base URL, authentication and errors, see the REST API overview.

`GET /v1/endpoints/templates`

Request: GET /v1/endpoints/templates
Operation: ListEndpointTemplates
Operation ID: Endpoint_ListTemplates
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Example request

bash

curl 'https://YOUR_SERVER/v1/endpoints/templates' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/endpoints/templates/{endpoint}`

Request: GET /v1/endpoints/templates/
Operation: ReadEndpointTemplateConfig
Operation ID: Endpoint_ReadTemplateConfig
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`endpoint`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/endpoints/templates/YOUR_ENDPOINT' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/endpoints`

Request: GET /v1/users/{user}/endpoints
Operation: ListEndpoints
Operation ID: Endpoint_List
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/endpoints' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

Response example (200)

json

[
  {
    "created": 1792263090703,
    "description": "Email Endpoint",
    "enabled": true,
    "endpoint": "email_endpoint",
    "modified": 1792263090703,
    "name": "Email",
    "type": "email"
  },
  {
    "created": 1792263090703,
    "description": "HTTP Request",
    "enabled": true,
    "endpoint": "http_request",
    "modified": 1792263090703,
    "name": "HTTP",
    "type": "http_request"
  },
  {
    "created": 1792263090703,
    "description": "HTTP request",
    "enabled": true,
    "endpoint": "http_request",
    "modified": 1792263090703,
    "name": "HTTP",
    "type": "http_request"
  }
]

`POST /v1/users/{user}/endpoints`

Request: POST /v1/users/{user}/endpoints
Operation: CreateEndpoint
Operation ID: Endpoint_Create
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes

Request body (application/json, required)

An endpoint is an outgoing action: type 'email', 'http_request' (webhooks, REST APIs), 'virtual' (no-op, for testing) or the id of an endpoint template (GET /v1/endpoints/templates lists them with their parameters; config is then {template, parameters}). Templates in config use {{payload}} (the data of the call) and its fields, e.g. {{payload.temperature}}. Called from the API (POST .../call), devices, product flows and alarm notifications.

Field	Type	Required	Constraints	Description
`config`	object	no		Settings of the endpoint type; not needed for 'virtual'.
`description`	string	no	Maximum length: 255
`enabled`	boolean	no
`endpoint`	string	yes	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`name`	string	no	Maximum length: 255
`type`	string	yes	Length: 1 to 255

Example request: Email

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/endpoints' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "config": {
    "body": "<p>The current temperature and humidity are: {{temperature}}, {{humidity}}</p>",
    "body_type": "html",
    "recipient": "user@example.com",
    "reply_to": "user@example.com",
    "subject": "Endpoint Testing"
  },
  "description": "Email Endpoint",
  "enabled": true,
  "endpoint": "email_endpoint",
  "name": "Email",
  "type": "email"
}'

Example body: HTTP Request

json

{
  "config": {
    "body": "",
    "body_type": "json",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer xyz"
      }
    ],
    "method": "POST",
    "url": "https://api.acme.com/sensor"
  },
  "description": "HTTP Request",
  "enabled": true,
  "endpoint": "http_request",
  "name": "HTTP",
  "type": "http_request"
}

Example body: HTTP Request Custom Body

json

{
  "config": {
    "body": "{\n    \"val1\" : {{temperature}},\n    \"val2\": {{humidity}}\n}",
    "body_type": "custom",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ],
    "method": "POST",
    "url": "https://api.acme.com/sensor"
  },
  "description": "HTTP request",
  "enabled": true,
  "endpoint": "http_request",
  "name": "HTTP",
  "type": "http_request"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/endpoints/{endpoint}`

Request: GET /v1/users/{user}/endpoints/
Operation: ReadEndpointConfig
Operation ID: Endpoint_ReadConfig
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`endpoint`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/endpoints/YOUR_ENDPOINT' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

Response example (200, Email)

json

{
  "config": {
    "body": "<p>The current temperature and humidity are: {{temperature}}, {{humidity}}</p>",
    "body_type": "html",
    "recipient": "user@example.com",
    "reply_to": "user@example.com",
    "subject": "Endpoint Testing"
  },
  "created": 1792263090703,
  "description": "Email Endpoint",
  "enabled": true,
  "endpoint": "email_endpoint",
  "modified": 1792263090703,
  "name": "Email",
  "type": "email"
}

Response example (200, HTTP Request)

json

{
  "config": {
    "body": "",
    "body_type": "json",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer xyz"
      }
    ],
    "method": "POST",
    "url": "https://api.acme.com/sensor"
  },
  "created": 1792263090703,
  "description": "HTTP Request",
  "enabled": true,
  "endpoint": "http_request",
  "modified": 1792263090703,
  "name": "HTTP",
  "type": "http_request"
}

Response example (200, HTTP Request Custom Body)

json

{
  "config": {
    "body": "{\n    \"val1\" : {{temperature}},\n    \"val2\": {{humidity}}\n}",
    "body_type": "custom",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ],
    "method": "POST",
    "url": "https://api.acme.com/sensor"
  },
  "created": 1792263090703,
  "description": "HTTP request",
  "enabled": true,
  "endpoint": "http_request",
  "modified": 1792263090703,
  "name": "HTTP",
  "type": "http_request"
}

`PUT /v1/users/{user}/endpoints/{endpoint}`

Request: PUT /v1/users/{user}/endpoints/
Operation: UpdateEndpoint
Operation ID: Endpoint_Update
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`endpoint`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints
`config`	object	no
`description`	string	no	Maximum length: 255
`enabled`	boolean	no
`name`	string	no	Maximum length: 255
`type`	string	no	Length: 1 to 255

Example request: Full Update

bash

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/endpoints/YOUR_ENDPOINT' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "config": {
    "body": "<p>The current temperature and humidity are: {{temperature}}, {{humidity}}</p>",
    "body_type": "html",
    "recipient": "user@example.com",
    "reply_to": "user@example.com",
    "subject": "Endpoint Testing"
  },
  "description": "Email Endpoint",
  "enabled": true,
  "endpoint": "email_endpoint",
  "name": "Email",
  "type": "email"
}'

Example body: Update 'config'

json

{
  "config": {
    "body": "<p>The current temperature and humidity are: {{temperature}}, {{humidity}}</p>",
    "body_type": "html",
    "recipient": "user@example.com",
    "reply_to": "user@example.com",
    "subject": "Endpoint Testing"
  }
}

Example body: Update 'description'

json

{
  "description": "Email Endpoint"
}

Example body: Update 'enabled'

json

{
  "enabled": true
}

Example body: Update 'name'

json

{
  "name": "Email"
}

Example body: Update 'type'

json

{
  "type": "email"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`DELETE /v1/users/{user}/endpoints/{endpoint}`

Request: DELETE /v1/users/{user}/endpoints/
Operation: DeleteEndpoint
Operation ID: Endpoint_Delete
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`endpoint`	path	string	yes

Example request

bash

curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/endpoints/YOUR_ENDPOINT' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`POST /v1/users/{user}/endpoints/{endpoint}/call`

Request: POST /v1/users/{user}/endpoints/{endpoint}/call
Operation: CallEndpoint
Operation ID: Endpoint_Call
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`endpoint`	path	string	yes

Request body (application/json, required)

Optional JSON payload, available to the endpoint templates as {{payload}} (e.g. the body of a webhook or the content of an email). The response is what the endpoint answered.

Example request: Alert payload

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/endpoints/YOUR_ENDPOINT/call' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "device": "greenhouse_01",
  "message": "Temperature above 30",
  "temperature": 31.2
}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/endpoints/{endpoint}/clone`

Request: GET /v1/users/{user}/endpoints/{endpoint}/clone
Operation: CloneEndpointConfig
Operation ID: Endpoint_CloneConfig
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`endpoint`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/endpoints/YOUR_ENDPOINT/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`POST /v1/users/{user}/endpoints/{endpoint}/clone`

Request: POST /v1/users/{user}/endpoints/{endpoint}/clone
Operation: CloneEndpoint
Operation ID: Endpoint_Clone
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`endpoint`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
`description`	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
`enabled`	boolean	no
`endpoint`	string	yes	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`name`	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.

Example request: Copy with a new id

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/endpoints/YOUR_ENDPOINT/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint": "copy_of_endpoint"
}'

Example body: Copy with name and description

json

{
  "description": "Same configuration as the original, for production line 2",
  "endpoint": "line_2_endpoint",
  "name": "Line 2 copy"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`PUT /v1/users/{user}/endpoints/{endpoint}/projects`

Request: PUT /v1/users/{user}/endpoints/{endpoint}/projects
Operation: UpdateEndpointProjects
Operation ID: Endpoint_UpdateProjects
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`endpoint`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
`(body)`	array of string	no		Projects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project.

Example request: No projects

bash

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/endpoints/YOUR_ENDPOINT/projects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[]'

Example body: One project

json

[
  "YOUR_USER@greenhouse"
]

Example body: Two projects

json

[
  "YOUR_USER@greenhouse",
  "YOUR_USER@maintenance"
]

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

REST API

Arduino library

CLI

Dashboard SDK

VS Code extension

Endpoints

`GET /v1/endpoints/templates`

`GET /v1/endpoints/templates/{endpoint}`

`GET /v1/users/{user}/endpoints`

`POST /v1/users/{user}/endpoints`

`GET /v1/users/{user}/endpoints/{endpoint}`

`PUT /v1/users/{user}/endpoints/{endpoint}`

`DELETE /v1/users/{user}/endpoints/{endpoint}`

`POST /v1/users/{user}/endpoints/{endpoint}/call`

`GET /v1/users/{user}/endpoints/{endpoint}/clone`

`POST /v1/users/{user}/endpoints/{endpoint}/clone`

`PUT /v1/users/{user}/endpoints/{endpoint}/projects`

REST API

Arduino library

CLI

Dashboard SDK

VS Code extension

GET /v1/endpoints/templates ​

GET /v1/endpoints/templates/{endpoint} ​

GET /v1/users/{user}/endpoints ​

POST /v1/users/{user}/endpoints ​

GET /v1/users/{user}/endpoints/{endpoint} ​

PUT /v1/users/{user}/endpoints/{endpoint} ​

DELETE /v1/users/{user}/endpoints/{endpoint} ​

POST /v1/users/{user}/endpoints/{endpoint}/call ​

GET /v1/users/{user}/endpoints/{endpoint}/clone ​

POST /v1/users/{user}/endpoints/{endpoint}/clone ​

PUT /v1/users/{user}/endpoints/{endpoint}/projects ​

`GET /v1/endpoints/templates`

`GET /v1/endpoints/templates/{endpoint}`

`GET /v1/users/{user}/endpoints`

`POST /v1/users/{user}/endpoints`

`GET /v1/users/{user}/endpoints/{endpoint}`

`PUT /v1/users/{user}/endpoints/{endpoint}`

`DELETE /v1/users/{user}/endpoints/{endpoint}`

`POST /v1/users/{user}/endpoints/{endpoint}/call`

`GET /v1/users/{user}/endpoints/{endpoint}/clone`

`POST /v1/users/{user}/endpoints/{endpoint}/clone`

`PUT /v1/users/{user}/endpoints/{endpoint}/projects`