Introduction

Level's public REST API lets you read and manage devices, groups, automations, alerts, updates, tags, custom fields, and other Level resources from your own integrations.

The API uses resource-oriented URLs, JSON request and response bodies, and standard HTTP status codes.

Full endpoint reference: developers.level.io

⚙️ PREREQUISITES

Level administrator access to create and manage API keys.
A secure place to store the API key.
An HTTP client that can send request headers and read JSON responses.

Public API

Generate an API key

Every API request requires an API key.

In Level, go to Settings → API keys.
Click + Create API key.
Enter a Description that identifies the integration, such as Monitoring dashboard or Asset sync.
Choose an access level:
- Read-only can retrieve data.
- Read and write can also create, update, and delete supported resources.
Click Create key.
Copy the key and save it in your secret manager.

💡 TIP: Create one key per integration. You can revoke or replace one integration's access without interrupting the others.

⚠️ WARNING: Treat an API key like a password. Do not commit it to source control, place it in a browser application, or print it in shared logs.

Send your first request

The base URL is:

https://api.level.io

Current public endpoints use the v2 path. Send the raw API key in the Authorization header. Do not add a Bearer prefix.

The following shell example lists devices:

curl --request GET 'https://api.level.io/v2/devices?limit=20' \
  --header 'Authorization: YOUR_API_KEY'

A successful list response has this general shape:

{
  "data": [
    { "id": "..." }
  ],
  "has_more": true
}

For requests with a JSON body, include:

Content-Type: application/json

Use the Level Developer Documentation for each endpoint's path, HTTP method, parameters, request body, and response schema.

ℹ️ NOTE: The API uses the key value directly in Authorization. An Authorization: Bearer ... header does not authenticate a Level API key.

Using the API

Current endpoints use these HTTP methods:

GET retrieves resources.
POST creates resources or starts supported actions.
PATCH updates resources.
DELETE removes supported resources.

Read-only keys can use read endpoints. A write request made with a read-only key returns 403 Forbidden.

Pagination

Paginated list endpoints accept:

Parameter	Purpose
`limit`	Number of records to return. The default is 20 and the maximum is 100.
`starting_after`	Return records after the supplied resource ID.
`ending_before`	Return records before the supplied resource ID.

When has_more is true, use the ID of the last record as starting_after to request the next page:

curl --request GET 'https://api.level.io/v2/devices?limit=100&starting_after=LAST_ID' \
  --header 'Authorization: YOUR_API_KEY'

Use the first returned ID with ending_before when paging in the opposite direction.

Common responses

Status	Meaning
`200 OK`	The request succeeded.
`201 Created`	A resource was created.
`400 Bad Request`	The request body or JSON could not be parsed.
`401 Unauthorized`	The API key is missing or invalid.
`403 Forbidden`	The key lacks write access, or the resource is outside its organization.
`404 Not Found`	The requested resource does not exist.
`422 Unprocessable Entity`	One or more parameters or values failed validation.
`429 Too Many Requests`	The organization exceeded the current request rate. Wait for the period in `Retry-After` before retrying.

Validation-error bodies vary by endpoint. Read the JSON error or errors value before retrying the request.

Manage API keys

Go to Settings → API keys to review active keys, copy a key, change its description or access level, or delete it.

Delete a key to revoke it immediately. Any integration using that key will begin receiving authentication errors.

⚠️ WARNING: Before deleting a key, identify every service that uses it. Create and deploy a replacement key first when the integration must remain available.

For the complete key-management workflow, see API Keys Settings.

Security practices

Keep keys in a secret manager or protected environment variable.
Use a separate key for each integration and environment.
Choose Read-only unless the integration needs to change Level data.
Do not expose keys in client-side JavaScript, mobile applications, screenshots, or support logs.
Delete a key immediately if you believe it has been exposed.
Validate resource IDs and API responses before issuing write or delete requests.

FAQ

Where is the endpoint reference? See developers.level.io.
Which API version should I use? Current public endpoints use paths beginning with /v2/.
Does the Authorization header use Bearer? No. Send the API key itself as the Authorization header value.
Can a read-only key create or update resources? No. Write requests made with a read-only key return 403 Forbidden.
How do I retrieve more than one page? Read has_more. When it is true, send the last returned ID as starting_after.
What should I do if a key is compromised? Delete it at Settings → API keys, create a replacement, and update the affected integration.

Public API: Getting Started