SenseOn Connect API Reference

SenseOn Connect is a bidirectional API that allows programmatic interaction with most data within the SenseOn platform.

API Capabilities

The API currently supports the following functionalities:

• Read security cases: Retrieve details of security cases.
• Update security cases: Include comments and update 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: Obtain raw telemetry data for deeper analysis.
• Write security observations: This feature requires approval from SenseOn.
• AI case summaries: Access and generate AI-powered case summaries through the API.

Create an API Token

To interact with the SenseOn Connect on your platform, you will need to create an access token. Navigate to Settings > Integrations > API Configuration.

On this page, you can view all tokens that have been created (including those that have been deleted), who created the token, their permissions, status, and last usage.

To create a new token, press the Create token button, and a popup will guide you through the process.

Once displayed, the token cannot be accessed again. If lost, a new token will need to be created.

Test the API

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

The documentation is protected with HTTP basic auth. To access it, enter any username and use the API token you generated as the password.

Authorise your API key with the documentation website by clicking Authorise.

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

Each API feature can be explored in detail. By pressing Try it out and then Execute, you can submit real queries to the API and receive real responses. A cURL output is provided to facilitate easier integration with other tools.

AI Case Summaries

AI case summaries can be accessed and managed through the SenseOn Connect API:

• POST /v1/cases - Includes any AI summaries that have been generated already on cases
• POST /v1/cases/{case_id}/summary - Generates (or regenerates) a new LLM summary for a specific case
• GET /v1/cases/{case_id} - Retrieves case details including summaries, but only if they've been generated already

For more information about AI case summaries, see the AI Generated Case Summaries documentation.

Personal Access Token API Endpoints

Personal Access Tokens (PATs) can be managed programmatically through the Customer Accessible API (CAA). See Personal Access Tokens for guidance on creating and scoping tokens via the UI.

Endpoints

Method	Path	Description
GET	/senseonapi/caa/pats/scopes	List all available scopes that can be assigned to a token
POST	/senseonapi/caa/pats	Create a new Personal Access Token
GET	/senseonapi/caa/pats	List tokens owned by the authenticated user
GET	/senseonapi/caa/pats/all	List tokens for all users (requires ui/caa_pat/admin permission)
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": "2026-12-31T23:59:59Z",
  "scopes": ["cases:read", "devices:read"]
}

The response includes the pat_id (UUID) and the token value. The token value is returned only once and cannot be retrieved again.

---

HTTP Status Codes

The API uses standard HTTP status codes. The following table covers codes 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 has been queued)
204 No Content	Successful deletion (for example, a PAT was revoked)
400 Bad Request	Invalid input — check the response body for a VALIDATION_ERROR detail
401 Unauthorized	Not authenticated — check your token 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 required before this action can proceed — re-authenticate and retry
500 Internal Server Error	Unexpected server error — contact support if this persists
503 Service Unavailable	The service is temporarily unavailable
504 Gateway Timeout	A database query timed out — try a more specific query or retry later

---

Error Codes

Error responses include a machine-readable code field in the JSON body:

Code	Description
VALIDATION_ERROR	One or more request fields failed 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 (wrong OS, unsupported agent version, etc.)
INVALID_SCRIPT_INPUT	One or more script parameters failed validation
FORBIDDEN	The authenticated user does not have permission for this action

---

Rate Limiting

Certain endpoints enforce rate limits to protect platform stability:

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

Requests exceeding these limits receive a 429 Too Many Requests response. Wait for the limit window to pass before retrying.

---

Creating Observations

Observations can be created using the API, but this action requires prior approval from SenseOn. The review process will assess:

• The impact on any managed services.
• How the data will correlate with other observations.
• The volume of observations expected.

Contact the SenseOn support team to initiate this review process.