The Thinger.io REST API gives you access to everything in your account: devices, data buckets, dashboards, products and the rest of the console. This reference lists its 375 operations in 26 groups, generated from the OpenAPI document of the Thinger.io server 7.4.0.

Base URL

Every path in this reference is relative to your server:

https://YOUR_SERVER

YOUR_SERVER is iot.thinger.io on the free Cloud account, or your own domain on a private instance. For example, GET /v1/users/{user}/devices is https://YOUR_SERVER/v1/users/YOUR_USER/devices.

Authentication

Operations that need authentication carry a token in the Authorization header with the Bearer scheme:

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

When you cannot set a header, for example in a link, pass the token in the authorization query parameter (lowercase): ?authorization=YOUR_TOKEN. The header takes precedence when both are present.

The OpenAPI document declares two security schemes for the same token: bearerAuth (HTTP bearer, a JWT) and oauth (OAuth2 password flow with the token URL https://YOUR_SERVER/oauth/token and the scope basic). Each operation of the reference says whether it needs a token or is public.

Access tokens

Access tokens are the tokens you create in Access Tokens or with the Access Tokens operations. Use them for scripts, integrations and devices:

• Each one is scoped: it grants only the resources and actions you allow, for example writing to one data bucket.
• They don't expire. Disable or delete a token to revoke it.

Sign in with a username and password

POST /oauth/token exchanges the credentials of an account for an access token and a refresh token. The body is form-encoded, not JSON:

curl -X POST 'https://YOUR_SERVER/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username=YOUR_USER&password=YOUR_PASSWORD'

{
  "access_token": "YOUR_TOKEN",
  "expires_in": 7200,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": null,
  "token_type": "bearer"
}

• The access token is valid for 2 hours (expires_in, in seconds).
• The refresh token is valid for 61 days and can be used once.
• Wrong credentials answer 401 with {"error":{"message":"invalid username or password"}}.
• If the account has multi-factor authentication enabled, the answer is 403 with "error": "mfa_required" and the methods available to complete the sign-in.
• After too many failed attempts from the same address, the answer is 429 for a while.

Refresh the access token

Before the access token expires, exchange the refresh token for a new pair. The old refresh token stops working:

curl -X POST 'https://YOUR_SERVER/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN'

The answer has the same fields as the sign-in. An invalid or used refresh token answers 401.

Requests and responses

• Request bodies are JSON: send Content-Type: application/json. A body with another content type, or JSON that does not parse, answers 400.
• A body that does not match the schema of the operation answers 400 with the first validation error.
• Responses are JSON, except operations that return files or binary data.

Errors

Errors answer with an HTTP status and, in most cases, a JSON body with a message:

{
  "error": {
    "message": "not authorized"
  }
}

Status	When
400	The request or its body is not valid.
401	The operation needs a token and it is missing, invalid or expired (unauthorized).
403	The token is valid but does not grant this operation (not authorized).
404	The route does not exist. The body is empty.
429	A rate limit applies, for example after too many failed sign-in attempts.
500	Unexpected server error.

OpenAPI document

Download the OpenAPI 3.1 document of this reference: openapi.json. Use it with OpenAPI tools, such as client generators or API explorers.

Your own instance serves the document for its version at GET /openapi.json, and also at GET /v1/server/swagger.json unless the instance administrator disabled it.

Groups

Group	Operations	Description
Authentication	1	Get access and refresh tokens for an account. The overview of the REST API shows the form-encoded body this operation expects.
User Accounts	40	Manage user accounts and their profile, password, email, timezone, multi-factor authentication and passkeys.
Devices	45	Create and configure devices, call their resources, and manage their tokens, properties, callbacks and files.
Dashboards	8	Create, read, update, clone and delete dashboards.
Data Buckets	17	Create data buckets, write and read their data, and manage tags, exports and imports.
Endpoints	11	Create and call endpoints, and list the endpoint templates.
Alarms	18	Manage alarm rules and alarm instances, and test rules and their notifications.
Access Tokens	8	Create, read, update, clone and delete access tokens.
Assets	1	Read the locations of the assets of an account.
Asset Types	17	Manage asset types, their properties and the locations of their assets.
Asset Groups	17	Manage asset groups, their properties and the locations of their assets.
File Storages	19	Create file storages and upload, read, rename and delete their files.
Products	38	Manage products and their profile, properties, firmwares and services.
Projects	27	Manage projects and their members, roles and properties.
Plugins	23	List plugins, manage their state and properties, read their logs and call their endpoints.
Syncs	13	Manage syncs and their locks.
Claims	10	Configure claims and request the claim of a device.
Account Properties	8	Manage the properties of a user account.
Roles	7	Manage the roles of a user account.
Cluster Hosts	9	Manage the cluster hosts of an instance, their settings, logs and restarts.
Domains	6	Add and verify custom domains for the console.
Brands	7	Manage the brands of an instance and test their email settings.
OAuth2 Clients	5	Manage the OAuth2 clients registered on an instance.
Identity Providers	5	Manage the identity providers users can sign in with.
Proxies	5	Manage the proxies that give external access to services of an instance.
Server	10	Read the version, health, settings, statistics and OpenAPI document of the server.