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": {
    }
}

Resolve a device identity from an address

Returns the canonical sr: device UID at an address, without probing the device. The IP is authoritative; an optional MAC corroborates it. A MAC no device holds is ignored, and a MAC held by a different device is reported as a conflict rather than used as a tiebreak. No identity is ever created.

Composite check validation runs resolve identity too, but additionally re-probe the device from every vantage-point agent on a named check. Use this endpoint when you want the identifier and not the scan.

Requires the identity.resolve permission.

Authorizations:
bearerAuthsessionAuth
query Parameters
ip
required
string
Example: ip=192.168.1.55

The address to resolve.

partition
string
Default: "default"

The partition to resolve within. Defaults to default.

mac
string
Example: mac=aa:bb:cc:dd:ee:ff

Optional MAC to corroborate the address. Ignored when no device holds it; a conflict when another device does.

Responses

Response samples

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

Resolve several device identities from their addresses

The batch form of the resolve endpoint, taking the same devices shape composite check validation runs accept, with the same limit of 128 per request.

Returns 200 and reports each address separately: one address that cannot be resolved does not fail the request, because a caller resolving a long list still needs the entries that worked. Every entry echoes the address it is for, so results can be matched to the request without relying on ordering.

Requires the identity.resolve permission.

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
required
partition
string
Default: "default"

Partition applied to every entry that does not name its own. Defaults to default.

required
Array of objects <= 128 items

The addresses to resolve. At most 128.

Responses

Request samples

Content type
application/json
{
  • "partition": "default",
  • "devices": [
    ]
}

Response samples

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

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
{ }