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

GET /v1/hosts

• Request: GET /v1/hosts
• Operation: ListHosts
• Operation ID: Host_List
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Example request

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

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

POST /v1/hosts

• Request: POST /v1/hosts
• Operation: CreateHost
• Operation ID: Host_Create
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Request body (application/json, required)

Field	Type	Required	Constraints	Description
description	string	no
host	string	yes	Pattern: ^([a-zA-Z0-9-_]+\.)*[a-zA-Z0-9][a-zA-Z0-9-_]+(?:\.[a-zA-Z]{2,11})?$	Hostname of the server. Hosts register themselves when they start.

Example request (skeleton generated from the schema: required fields only, neutral values)

curl -X POST 'https://YOUR_SERVER/v1/hosts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "host": ""
}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

GET /v1/hosts/{host}

• Request: GET /v1/hosts/
• Operation: ReadHostConfig
• Operation ID: Host_ReadConfig
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
host	path	string	yes

Example request

curl 'https://YOUR_SERVER/v1/hosts/YOUR_HOST' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

PUT /v1/hosts/{host}

• Request: PUT /v1/hosts/
• Operation: UpdateHost
• Operation ID: Host_Update
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
host	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
description	string	no

Example request: Describe the host

curl -X PUT 'https://YOUR_SERVER/v1/hosts/YOUR_HOST' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Primary server, eu-west-1"
}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

DELETE /v1/hosts/{host}

• Request: DELETE /v1/hosts/
• Operation: DeleteHost
• Operation ID: Host_Delete
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
host	path	string	yes

Example request

curl -X DELETE 'https://YOUR_SERVER/v1/hosts/YOUR_HOST' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

GET /v1/hosts/{host}/logs

• Request: GET /v1/hosts/{host}/logs
• Operation: ReadHostLogs
• Operation ID: Host_ReadLogs
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Server output (stdout and stderr) of the host. A websocket upgrade streams new lines live; a plain GET returns the last lines as text/plain. Reads the logs of the Docker container the server runs in (deployment.container_name, default "thinger"); other cluster hosts are proxied.

Parameters

Name	In	Type	Required	Description
host	path	string	yes
lines	query	integer	no	Plain GET: number of last lines (1-5000, default 200).
timestamps	query	boolean	no	Plain GET: prefix each line with its timestamp.
since	query	integer	no	Plain GET: only lines after this unix timestamp, or this many seconds ago when below 31536000.

Example request

curl 'https://YOUR_SERVER/v1/hosts/YOUR_HOST/logs' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

POST /v1/hosts/{host}/restart

• Request: POST /v1/hosts/{host}/restart
• Operation: UpdateHostState
• Operation ID: Host_UpdateStateRestart
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
host	path	string	yes

Request body (application/json, required)

A JSON object.

Example request (skeleton generated from the schema: required fields only, neutral values)

curl -X POST 'https://YOUR_SERVER/v1/hosts/YOUR_HOST/restart' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

GET /v1/hosts/{host}/settings

• Request: GET /v1/hosts/{host}/settings
• Operation: ReadHostSettings
• Operation ID: Host_ReadSettings
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
host	path	string	yes

Example request

curl 'https://YOUR_SERVER/v1/hosts/YOUR_HOST/settings' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

PUT /v1/hosts/{host}/settings

• Request: PUT /v1/hosts/{host}/settings
• Operation: UpdateHostSettings
• Operation ID: Host_UpdateSettings
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
host	path	string	yes

Request body (application/json, required)

Merged (RFC 7386 merge patch: null removes a key) into the host custom settings, on top of the provider settings. Changes apply after POST /v1/hosts/{host}/restart. Ports are strings: numbers are ignored by the server. On cloud instances (configured by a subscription), database, plugins, rate_limiter, http_server.hosts, accounts.limits.{accounts,brands,domains,members} and deployment.container_name belong to the plan: sending them returns 403, and stored ones are ignored.

Field	Type	Required	Constraints	Description
accounts	object or null	no		Accounts and limits. Brands can override the sign-up and login keys per domain.
accounts.admin_emails	any	no		Email addresses whose accounts become admins.
accounts.allow_password	boolean or null	no
accounts.allow_passwordless	boolean or null	no
accounts.federated_login	boolean or null	no
accounts.identity_providers	any	no		Identity provider ids offered on login; empty offers every enabled one.
accounts.invalid_email_domains	any	no		Email domains rejected on sign-up.
accounts.invalid_usernames	any	no		Usernames that cannot be registered.
accounts.limits	object or null	no		Per collection: {"<collection>": {"max_count": n}} with -1 = unlimited and 0 = disabled. Collections: access_tokens, buckets, dashboards, devices, endpoints, plugins, projects, projects_members, storages, alarms_rules, alarms_instances, syncs, types, groups, products, proxies, oauth_clients, identity_providers (default 0: set it to enable them). Also buckets.retention {period, unit} and buckets / endpoints min_interval. Accounts can override them with their own limits.
accounts.max_password_length	integer or string or null	no		Default 48.
accounts.min_password_length	integer or string or null	no		Default 8.
accounts.public_sign_up	boolean or null	no
accounts.public_sign_up_role	string or null	no		user or member.
accounts.require_2fa	boolean or null	no
accounts.require_email_verification	boolean or null	no
accounts.required_email_domains	any	no		Only these email domains can sign up.
buckets	object or null	no
buckets.export	object or null	no		Where bucket exports are written: type filesystem ({filesystem: {export_path}}) or s3 ({s3: {bucket_id, aws_access_key_id, aws_secret_access_key, aws_region}}).
buckets.export.type	string or null	no		filesystem or s3.
buckets.storage	object or null	no		Where bucket data is stored: default is mongodb, influxdb or dynamodb, each with its own connection settings (mongodb {connection_string, max_retention, default_retention}, influxdb {host, port, username, password}, dynamodb {table_name, aws_access_key_id, aws_secret_access_key, aws_region}).
buckets.storage.default	string or null	no		mongodb, influxdb or dynamodb.
deployment	object or null	no
deployment.contact_email	string or null	no		The account registered with this email becomes admin; also {{admin}} in email templates.
deployment.content_security_policy	string or null	no
deployment.disable_swagger	boolean or null	no
deployment.x_frame_options	string or null	no		Default SAMEORIGIN.
email	object or null	no		Server mail settings, used when a brand has no custom email.
email.from	string or null	no		Sender address.
email.from_name	string or null	no
email.ses	object or null	no
email.ses.aws_access_key_id	string or null	no
email.ses.aws_region	string or null	no
email.ses.aws_secret_access_key	string or null	no
email.smtp	object or null	no
email.smtp.host	string or null	no
email.smtp.password	string or null	no
email.smtp.port	string or integer or null	no	Pattern: ^[0-9]{1,5}$	As a string, e.g. "587".
email.smtp.secure	boolean or null	no		true: implicit TLS (465); false: STARTTLS (587).
email.smtp.username	string or null	no
email.type	string or null	no		smtp or ses.
http_server	object or null	no		HTTP API and console.
http_server.address	string or null	no		Listening address, e.g. 0.0.0.0.
http_server.enabled	boolean or null	no
http_server.port	string or integer or null	no	Pattern: ^[0-9]{1,5}$	e.g. "80".
http_server.ssl_port	string or integer or null	no	Pattern: ^[0-9]{1,5}$	e.g. "443".
mqtt_server	object or null	no		MQTT broker for devices.
mqtt_server.address	string or null	no
mqtt_server.enabled	boolean or null	no
mqtt_server.port	string or integer or null	no	Pattern: ^[0-9]{1,5}$	e.g. "1883".
mqtt_server.ssl_port	string or integer or null	no	Pattern: ^[0-9]{1,5}$	e.g. "8883".
proxies	object or null	no
proxies.dynamic_port_range_end	integer or null	no		Last one (default 51000).
proxies.dynamic_port_range_start	integer or null	no		First port given to proxies without a fixed port (default 50000).
scripting_engine	object or null	no		{"nodejs": {"enabled": true}}: JavaScript for product scripts.
ssl	object or null	no
ssl.client_ca_certs	string or null	no		PEM certificates to accept as client certificates.
ssl.ssl_ciphers	string or null	no		OpenSSL cipher list.
ssl.ssl_enable_legacy_protocols	boolean or null	no
ssl.ssl_prefer_server_ciphers	boolean or null	no
thing_server	object or null	no		IOTMP server for devices.
thing_server.address	string or null	no
thing_server.enabled	boolean or null	no
thing_server.port	string or integer or null	no	Pattern: ^[0-9]{1,5}$	e.g. "25200".
thing_server.port_v2	string or integer or null	no	Pattern: ^[0-9]{1,5}$	IOTMP v2, default "25204".
thing_server.ssl_port	string or integer or null	no	Pattern: ^[0-9]{1,5}$	e.g. "25202".
thing_server.ssl_port_v2	string or integer or null	no	Pattern: ^[0-9]{1,5}$	IOTMP v2 over TLS, default "25206".

Example request: Change the MQTT ports

curl -X PUT 'https://YOUR_SERVER/v1/hosts/YOUR_HOST/settings' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "mqtt_server": {
    "port": "1884",
    "ssl_port": "8884"
  }
}'

Example body: Enable projects, members and identity providers

{
  "accounts": {
    "limits": {
      "identity_providers": {
        "max_count": 5
      },
      "projects": {
        "max_count": -1
      },
      "projects_members": {
        "max_count": -1
      }
    }
  }
}

Example body: Remove a custom setting (back to the provider value)

{
  "deployment": {
    "x_frame_options": null
  }
}

Example body: Send server emails with SMTP

{
  "email": {
    "from": "noreply@example.com",
    "from_name": "Example IoT",
    "smtp": {
      "host": "smtp.example.com",
      "password": "app-password",
      "port": "587",
      "secure": false,
      "username": "noreply@example.com"
    },
    "type": "smtp"
  }
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden