SenseOn Connect API Reference
SenseOn Connect is a bidirectional API. It lets you interact programmatically with most data in the SenseOn platform.
API Capabilities
The API supports these functions:
- Read security cases: Retrieve details of security cases.
- Update security cases: Include comments and update the status.
- Read device information: Access information on all registered devices.
- Read all security observations: Access detailed observations related to security incidents.
- Read all raw telemetry: Get raw telemetry data for deeper analysis.
- Write security observations: You must get approval from SenseOn for this feature.
- AI case summaries: Access and generate AI-powered case summaries through the API.
- Read and update appliance settings: Read tenant settings by name or wildcard pattern, and update them programmatically.
- Read environment context: Retrieve the customer-authored environment context, with the built-in sections and any custom blocks.
The API serves all endpoints under https://<your-tenant>.senseon.io/api. For example, a GET /v1/settings request goes to https://<your-tenant>.senseon.io/api/v1/settings. To authenticate, send your token in the Authorization: Bearer <token> header.
Token Scopes
When you create a token, you grant it one or more scopes:
cases/read, cases/write, devices/read, observations/read, observations/write, telemetry/read, settings/read, settings/write
Rate Limiting
Each endpoint is in one of three tiers of rate limits. The low tier is ~10 requests per minute. The medium tier is ~60 requests per minute. The high tier is ~600 requests per minute. If you exceed the limit of a tier, the API returns 429 Too Many Requests.
Create an API Token
To interact with SenseOn Connect on your platform, you must create an access token. Go to Settings > Integrations > API Configuration.
This page shows all the tokens that were created. The list also shows the deleted tokens. For each token, the page shows who created it, its permissions, its status, and when it was last used.

To create a new token, click the Create token button. A popup then guides you through the process.

After the popup shows the token, you cannot get access to the token again. If you lose the token, you must create a new token.

Test the API
Next, you can open the live documentation and test the API token with real data on your system. Click Read the documentation.

HTTP basic auth protects the documentation. To open the documentation, enter any username. Use the API token that you generated as the password.
To authorise your API key with the documentation website, click Authorise.

Then enter your token in the Personal Access Token field. Select Authorise.

You can examine each API feature in detail. To send real queries to the API and get real responses, click Try it out. Then click Execute. The page also gives a cURL output, which makes integration with other tools easier.

AI Case Summaries
You can use the SenseOn Connect API to access and manage AI case summaries:
- POST /v1/cases - Includes any AI summaries that were already generated on cases
- POST /v1/cases/{case_id}/summary - Generates (or generates again) a new LLM summary for a specific case
- GET /v1/cases/{case_id} - Retrieves case details with summaries, but only if the summaries were already generated
For more information about AI case summaries, refer to the AI Generated Case Summaries documentation.
Settings API
You can read and update appliance settings programmatically. To read settings, a token must have the settings/read scope. To update settings, a token must have the settings/write scope. A token can access only the settings that the user who created it has permission to see.
| Method | Path | Description |
|---|---|---|
GET |
/v1/settings?names=... |
Read one or more settings. Each name can be exact (senseon.llm.enabled) or a trailing-wildcard pattern (notifications.*). If the token does not have permission to read a setting, the response gives that setting with an error of NOT_AUTHORIZED. Unknown names return NOT_FOUND. |
PUT |
/v1/settings |
Update one or more settings. The body maps setting names to new values. Updates are all-or-nothing. If a setting is unknown, not permitted, or does not pass validation, the API returns a 400. This response maps the names that caused the error to error messages. |
Example read:
curl -H "Authorization: Bearer <token>" \
"https://<your-tenant>.senseon.io/api/v1/settings?names=notifications.*"
Each setting in the response includes its name, current value, kind, friendly_name, and description. It also shows whether your token has update_permission.
Environment Context API
You can read the customer-authored Environment context programmatically. For this endpoint, a token must have the settings/read scope.
| Method | Path | Description |
|---|---|---|
GET |
/v1/environment_context |
Read the environment context: the built-in sections, your custom blocks, and when and by whom it was last saved. If nothing is saved on an appliance, the appliance returns an empty record. |
The response contains:
sections: the three built-in sections (accounts,network_locationsandknown_environment). Each section is a plain-text string.blocks: your custom blocks in display order, each with atitle,contentand a list ofkeywords.updated_at: the last-saved time in milliseconds since the Unix epoch, ornullif the context was never saved.updated_by: the email of the user who last saved it, ornullif the user is not known.
Example read:
curl -H "Authorization: Bearer <token>" \
"https://<your-tenant>.senseon.io/api/v1/environment_context"
Personal Access Token API Endpoints
You can use the Customer Accessible API (CAA) to manage Personal Access Tokens (PATs) programmatically. For information about how to create and scope tokens in the UI, refer to Personal Access Tokens.
Availability: If a path in the table that follows returns
404, use the UI to manage tokens. SenseOn releases the PAT management endpoints with appliance updates. Thus, it is possible that your tenant does not support them yet. You can always manage tokens in the UI at Settings > Integrations > API Configuration.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/senseonapi/caa/pats/scopes |
Return the scopes assigned to the token that authenticates the request (you must send the request with that token) |
POST |
/senseonapi/caa/pats |
Create a new Personal Access Token |
GET |
/senseonapi/caa/pats |
List the tokens that the authenticated user owns |
GET |
/senseonapi/caa/pats/all |
List tokens for all users (the ui/caa_pat/admin permission is necessary) |
DELETE |
/senseonapi/caa/pats/{pat_id} |
Revoke a token by its ID (returns HTTP 204 on success) |
Create token request body
{
"name": "my-integration",
"expiry_at": 1798761599000,
"scopes": ["cases/read", "devices/read"]
}
expiry_at is a timestamp in milliseconds since the Unix epoch. It is not an ISO 8601 string. The timestamp in the example is 2026-12-31T23:59:59Z. This timestamp must be in the future.
The response includes the pat_id (UUID) and the token value. The API returns the token value only once. You cannot retrieve it again.
Service Account API Endpoints
Service accounts are non-human identities. Each service account uses a single token to authenticate to the Customer Accessible API. For information about how to create and manage service accounts in the UI, refer to Service Accounts.
The ui/service_accounts/manage permission is necessary for all service account endpoints. The Admin role has this permission.
Availability: If a path in the table that follows returns
404, use the UI to manage service accounts. SenseOn releases the service account endpoints with appliance updates. Thus, it is possible that your tenant does not support them yet. You can always manage service accounts in the UI at Settings > Service Accounts.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/senseonapi/service_accounts |
List all service accounts |
POST |
/senseonapi/service_accounts |
Create a service account |
GET |
/senseonapi/service_accounts/{user_id} |
Retrieve a single service account |
PATCH |
/senseonapi/service_accounts/{user_id} |
Update a service account (only the fields that you supply change) |
DELETE |
/senseonapi/service_accounts/{user_id} |
Delete a service account and revoke its token (returns HTTP 204 on success) |
POST |
/senseonapi/service_accounts/{user_id}/token |
Issue the token of the account, and revoke the token that the account already has |
DELETE |
/senseonapi/service_accounts/{user_id}/token |
Revoke the active token of the account (returns HTTP 204 on success) |
Create service account request body
{
"name": "SOC Automation",
"description": "Automated case triage"
}
The name must be unique across service accounts. When you create the account, the API derives an email that identifies the account from the name. This email does not change if you rename the account later.
Update service account request body
Only the fields that you supply change. Do not send a field as null. To keep a field unchanged, do not include it in the request.
{
"name": "SOC Automation",
"description": "Automated case triage and export",
"enabled": false
}
Issue token request body
{
"scopes": ["cases/read", "cases/write"],
"expiry_at": 1798761599000
}
expiry_at is a timestamp in milliseconds since the Unix epoch, or null for a token that never expires. The response includes the pat_id, scopes, expiry_at, and the token value. As with a personal access token, the API returns the value only once. If the account is disabled, the API returns a 409 Conflict.
HTTP Status Codes
The API uses standard HTTP status codes. The table that follows gives the codes that are specific to SenseOn behaviour:
| Code | Meaning |
|---|---|
200 OK |
Request succeeded |
201 Created |
Resource created successfully |
202 Accepted |
Asynchronous operation accepted (for example, a Hunt Lab query is in the queue) |
204 No Content |
Successful deletion (for example, a PAT was revoked) |
400 Bad Request |
Invalid input: look for a VALIDATION_ERROR detail in the response body |
401 Unauthorized |
Not authenticated: make sure that your token is correct, or log in again |
403 Forbidden |
Authenticated but not authorised for this action |
404 Not Found |
The requested resource does not exist |
428 Precondition Required |
Step-up authentication is necessary before this action can continue: authenticate again and try again |
500 Internal Server Error |
Unexpected server error: if the error continues, contact support |
503 Service Unavailable |
The service is temporarily not available |
504 Gateway Timeout |
A database query timed out: try a more specific query, or try again later |
Error Codes
Error responses include a machine-readable code field in the JSON body:
| Code | Description |
|---|---|
VALIDATION_ERROR |
One or more request fields did not pass validation |
INTERNAL_SERVER_ERROR |
An unexpected error occurred on the server |
INVALID_PAT_ID |
The specified Personal Access Token ID does not exist or does not belong to the authenticated user |
INVALID_ENDPOINT_ID |
One or more endpoint IDs in the request are invalid |
INVALID_SCRIPT_ID |
The specified script ID does not exist |
INVALID_ACTION_ID |
The specified action ID does not exist |
INVALID_CASE_ID |
The specified case ID does not exist |
INVALID_DEVICES |
One or more devices are not eligible for the requested action (for example, wrong OS or unsupported agent version) |
INVALID_SCRIPT_INPUT |
One or more script parameters did not pass validation |
FORBIDDEN |
The authenticated user does not have permission for this action |
Rate Limiting
Some endpoints enforce rate limits to protect the stability of the platform:
| Endpoint | Limit |
|---|---|
GET /senseonapi/users/resend-invite |
1 request per 30 seconds per user |
POST /senseonapi/users/current/totp |
4 requests per second; 5 requests per 60 seconds |
If a request exceeds these limits, it gets a 429 Too Many Requests response. Wait until the limit window ends before you try again.
Creating Observations
You can use the API to create observations, but SenseOn must approve this action first. The review process examines:
- The impact on any managed services.
- How the data will correlate with other observations.
- The expected volume of observations.
To start this review process, contact the SenseOn support team.