Skip to main content
API docs by Redocly

ServiceRadar API (1.0)

Download OpenAPI specification:Download

API Support: [email protected] URL: https://serviceradar.cloud/support License: Apache 2.0 Terms of Service

HTTP API for the ServiceRadar platform, served by the ServiceRadar web application (web-ng).

The API is JSON over HTTPS. Most endpoints require an authenticated request. There are two ways to authenticate:

  • Session — when the request originates from a logged-in browser session, the existing session cookie is used.
  • Bearer token — for CLI tools and external integrations, send an Authorization: Bearer <token> header. Tokens are issued from the ServiceRadar UI under Settings → API Credentials (/settings/api-credentials).

The data-plane endpoints under /api (for example /api/query and /api/devices) accept either form of authentication. Some admin and onboarding endpoints additionally accept an X-API-Key header.

See the published API Reference documentation page for an authentication walkthrough and SRQL query examples.

SRQL

ServiceRadar Query Language endpoints

Execute an SRQL query

Executes a ServiceRadar Query Language (SRQL) query and returns the result set. SRQL is read-only: only SELECT/WITH statements are produced and executed.

Results are subject to the caller's authorization scope.

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
required
query
required
string

The SRQL query to execute.

limit
integer

Maximum number of rows to return.

cursor
string

Opaque pagination cursor returned by a previous response.

direction
string
Enum: "next" "prev"

Pagination direction relative to the cursor.

mode
string

Optional execution mode hint.

Responses

Request samples

Content type
application/json
{
  • "query": "show devices order by last_seen desc",
  • "limit": 50
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    },
  • "viz": { },
  • "error": "string"
}

Devices

Device inventory

List devices

Returns a paginated list of devices from the inventory. Pagination is offset based; use the next_offset value from the response to fetch the next page.

Authorizations:
bearerAuthsessionAuth
query Parameters
limit
integer <= 500
Default: 100

Maximum number of devices to return (default 100, max 500).

offset
integer
Default: 0

Number of devices to skip for pagination (default 0).

search
string

Free-text search across device identity fields.

status
string
Enum: "online" "offline"

Filter by availability status.

gateway_id
string

Filter devices reported by a specific gateway.

device_type
string

Filter by device type.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get a device by UID

Returns a single device identified by its OCSF uid.

Authorizations:
bearerAuthsessionAuth
path Parameters
uid
required
string

The device's unique identifier (OCSF uid).

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Export devices in OCSF format

Exports devices as OCSF v1.7.0 Device objects (Device Inventory Info, class UID 5001). Supports filtering by device type, time range, and offset pagination.

Authorizations:
bearerAuthsessionAuth
query Parameters
type_id
integer

Filter by OCSF device type_id.

first_seen_after
string <date-time>

Only include devices first seen after this ISO 8601 timestamp.

last_seen_after
string <date-time>

Only include devices last seen after this ISO 8601 timestamp.

limit
integer <= 1000
Default: 100

Maximum number of devices to return (default 100, max 1000).

offset
integer
Default: 0

Number of devices to skip for pagination (default 0).

Responses

Response samples

Content type
application/json
{
  • "ocsf_version": "1.7.0",
  • "class_uid": 5001,
  • "class_name": "Device Inventory Info",
  • "devices": [
    ],
  • "count": 0,
  • "pagination": {
    }
}

System

System health and status

Readiness probe

Returns the application's readiness, including database connectivity. Responds with 200 ready when healthy and 503 not ready otherwise. This endpoint is unauthenticated. (/health/ready is an alias and /health/live is a lightweight liveness probe.)

Responses

Admin

Administrative endpoints (require admin privileges)

List users

Lists user accounts. Requires admin privileges.

Authorizations:
bearerAuthsessionAuth
query Parameters
limit
integer
Default: 100

Maximum number of users to return (default 100).

role
string

Filter by role.

status
string

Filter by account status.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a user

Creates a new user account. Requires admin privileges.

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
required
email
required
string
display_name
string
role
string
password
string

Optional password for a local account.

role_profile_id
string

Optional RBAC role profile to assign.

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "display_name": "Jane Doe",
  • "role": "viewer",
  • "password": "string",
  • "role_profile_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "string",
  • "display_name": "string",
  • "role": "string",
  • "role_profile_id": "string",
  • "status": "string",
  • "has_password": true,
  • "has_external_id": true,
  • "confirmed_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "last_auth_method": "string",
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a user

Returns a single user account by ID. Requires admin privileges.

Authorizations:
bearerAuthsessionAuth
path Parameters
id
required
string

The user's unique identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "string",
  • "display_name": "string",
  • "role": "string",
  • "role_profile_id": "string",
  • "status": "string",
  • "has_password": true,
  • "has_external_id": true,
  • "confirmed_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "last_auth_method": "string",
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a user

Updates a user account. Requires admin privileges.

Authorizations:
bearerAuthsessionAuth
path Parameters
id
required
string

The user's unique identifier.

Request Body schema: application/json
required
display_name
string
role
string
role_profile_id
string

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "role": "string",
  • "role_profile_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "string",
  • "display_name": "string",
  • "role": "string",
  • "role_profile_id": "string",
  • "status": "string",
  • "has_password": true,
  • "has_external_id": true,
  • "confirmed_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "last_auth_method": "string",
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List role profiles

Lists configured RBAC role profiles. Requires admin privileges.

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the RBAC permission catalog

Returns the catalog of RBAC permissions and resources available when building role profiles. Requires admin privileges.

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{ }

Get the live admin OpenAPI document

Returns the OpenAPI document generated from the running web application for the admin API surface. Requires admin privileges. A published copy is also available unauthenticated at /api/docs/v1/admin/openapi.json.

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{ }