For the base URL, authentication and errors, see the REST API overview.
GET /v1/domains
- Request: GET /v1/domains
- Operation: ListDomains
- Operation ID:
Domain_List - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Example request
bash
curl 'https://YOUR_SERVER/v1/domains' \
-H 'Authorization: Bearer YOUR_TOKEN'Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
Response example (200)
json
[
{
"created": 1792263090747,
"description": "Console and API for Example customers",
"domain": "iot.example.com",
"modified": 1792263090747
}
]POST /v1/domains
- Request: POST /v1/domains
- Operation: CreateDomain
- Operation ID:
Domain_Create - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Request body (application/json, required)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
description | string | no | ||
domain | string | yes | Pattern: ^([a-zA-Z0-9-_]+\.)*[a-zA-Z0-9][a-zA-Z0-9-_]+\.[a-zA-Z]{2,11}?$ | Hostname to serve with its own TLS certificate, e.g. iot.example.com. Before verifying, point it to this server (A/AAAA record to its IP, or CNAME to its hostname) and make sure port 80 is reachable from the internet: POST /v1/domains/{domain}/verify gets a Let's Encrypt certificate through an HTTP-01 challenge (a *.wildcard needs the DNS-01 challenge, only on Thinger-hosted servers). Certificates renew automatically while the DNS keeps pointing here. Brand the console on it by creating a brand with the same id. |
name | string | no |
Example request: Custom domain
bash
curl -X POST 'https://YOUR_SERVER/v1/domains' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"description": "Console and API for Example customers",
"domain": "iot.example.com"
}'Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
GET /v1/domains/{domain}
- Request: GET /v1/domains/
- Operation: ReadDomainConfig
- Operation ID:
Domain_ReadConfig - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domain | path | string | yes |
Example request
bash
curl 'https://YOUR_SERVER/v1/domains/YOUR_DOMAIN' \
-H 'Authorization: Bearer YOUR_TOKEN'Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
Response example (200, Custom domain)
json
{
"created": 1792263090747,
"description": "Console and API for Example customers",
"domain": "iot.example.com",
"modified": 1792263090747
}PUT /v1/domains/{domain}
- Request: PUT /v1/domains/
- Operation: UpdateDomain
- Operation ID:
Domain_Update - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domain | path | string | yes |
Request body (application/json, required)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
description | string | no | ||
name | string | no |
Example request: Full Update
bash
curl -X PUT 'https://YOUR_SERVER/v1/domains/YOUR_DOMAIN' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"description": "Console and API for Example customers",
"domain": "iot.example.com"
}'Example body: Update 'description'
json
{
"description": "Console and API for Example customers"
}Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
DELETE /v1/domains/{domain}
- Request: DELETE /v1/domains/
- Operation: DeleteDomain
- Operation ID:
Domain_Delete - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domain | path | string | yes |
Example request
bash
curl -X DELETE 'https://YOUR_SERVER/v1/domains/YOUR_DOMAIN' \
-H 'Authorization: Bearer YOUR_TOKEN'Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
POST /v1/domains/{domain}/verify
- Request: POST /v1/domains/{domain}/verify
- Operation: VerifyDomain
- Operation ID:
Domain_Verify - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domain | path | string | yes |
Request body (application/json, required)
A JSON object.
Example request (skeleton generated from the schema: required fields only, neutral values)
bash
curl -X POST 'https://YOUR_SERVER/v1/domains/YOUR_DOMAIN/verify' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{}'Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |