Services

List, create, update and delete the services of your organization (service and asset inventory with criticality and responsible team), and how incidents are assigned to them.

GET /api/im/services · POST /api/im/services · GET /api/im/services/:id · PATCH /api/im/services/:id · DELETE /api/im/services/:id

A service is something your organization runs and that an incident can affect, for example "Web shop", "Customer portal" or "Mail". Each service has a criticality (critical, high, medium, low), an optional responsible team, and the monitors it consists of. This is the service and asset inventory NIS-2 asks for (Implementing Regulation (EU) 2024/2690, Annex 12 and 5.2).

Every incident carries serviceId (null = no service). It is set in two ways:

Automatically when an incident is opened by the built-in monitoring bridge and its monitor belongs to exactly one service of your organization. A monitor in two services is ambiguous and leaves serviceId empty; alerts from any other source (webhooks, email, API) are never assigned automatically.
By hand with Set Incident Service.

:id accepts the numeric id or the publicId.

Authentication

Reading is open to every IM-eligible role (admin, editor, responder) and to organization-wide API tokens, see Authentication. Creating, updating and deleting require the organization admin role; an API token runs with the role of the user who created it. Other roles get 403 imServiceWriteDenied.

The service object

Field	Type	Description
`id`	integer	Internal ID.
`publicId`	string (UUID)	Public ID.
`organizationId`	integer	Owning organization.
`name`	string	1 to 200 characters, unique per organization regardless of case.
`description`	string \| null	At most 2000 characters.
`criticality`	string	`critical`, `high`, `medium` or `low`.
`ownerTeamId`	integer \| null	Responsible team; becomes `null` when the team is deleted.
`monitors`	object[]	`{ monitorType, monitorId, monitorName }`, sorted by name. A monitor that was deleted no longer appears.
`createdAt` / `updatedAt`	string (ISO 8601)

monitorType is one of website (also heartbeat and browser monitors), dns, icmp, smtp, ssh, tcp, ftp, imap_pop. Each type has its own IDs, so a monitor is always identified by the pair monitorType + monitorId.

List services

GET /api/im/services

Parameter	Type	Default	Description
`page`	integer	`1`	Page number.
`perPage`	integer	`50`	Page size, at most `200`.

curl "$BASE_URL/api/im/services" \
  -H "Authorization: Bearer $TOKEN"

200 OK, sorted by name:

{
  "items": [
    {
      "id": 4,
      "publicId": "0d7c6a0e-6f43-4d3b-9b1e-2a8f1d1c5e77",
      "organizationId": 1,
      "name": "Web shop",
      "description": "Storefront and checkout",
      "criticality": "critical",
      "ownerTeamId": 3,
      "monitors": [
        { "monitorType": "website", "monitorId": 46, "monitorName": "shop.example.com" },
        { "monitorType": "dns", "monitorId": 9, "monitorName": "example.com DNS" }
      ],
      "createdAt": "2026-10-25T08:00:00.000Z",
      "updatedAt": "2026-10-25T08:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 50
}

Get a service

GET /api/im/services/:id returns one service in the same shape.

Create a service

POST /api/im/services

Field	Type	Required	Description
`name`	string	Yes	1 to 200 characters, unique per organization regardless of case (`409 imServiceNameTaken`).
`description`	string \| null	No	At most 2000 characters.
`criticality`	string	No	`critical`, `high`, `medium` (default) or `low`.
`ownerTeamId`	integer \| null	No	A team of your organization (`404 imTeamNotFound`).
`monitors`	object[]	No	`{ monitorType, monitorId }`, at most 500. Every monitor must belong to your organization (`404 imServiceMonitorNotFound`, `data.monitors` lists the ones that do not).

Unknown fields are rejected with 400 invalidRequestBody.

curl -X POST "$BASE_URL/api/im/services" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Web shop",
    "criticality": "critical",
    "ownerTeamId": 3,
    "monitors": [{ "monitorType": "website", "monitorId": 46 }]
  }'

201 Created with the service.

Update a service

PATCH /api/im/services/:id

Merge patch: send only the fields to change (same fields and rules as on create). null clears description or ownerTeamId. monitors replaces the whole set; [] removes every monitor. Answers 200 OK with the service.

curl -X PATCH "$BASE_URL/api/im/services/4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "criticality": "high" }'

Delete a service

DELETE /api/im/services/:id answers 204 No Content. Its monitor assignments go with it; incidents stay and lose the reference (serviceId becomes null).

Every create, update and delete is written to the organization audit log with the changed fields.

Common errors

401 Unauthorized when not authenticated
403 Forbidden (imAccessDenied, imNotEnabled) without IM access or when Incident Management is not enabled
403 Forbidden (imServiceWriteDenied) when a non-admin creates, updates or deletes
400 Bad Request (invalidRequestBody) for unknown fields or wrong types; (invalidIdentifier) when :id is neither an ID nor a UUID
404 Not Found (imServiceNotFound) when the service does not exist or belongs to another organization
404 Not Found (imTeamNotFound, imServiceMonitorNotFound) for a team or monitor outside your organization
409 Conflict (imServiceNameTaken) when the name is already in use

Services

AuthenticationCopy Anchor Link

The service objectCopy Anchor Link

List servicesCopy Anchor Link

Get a serviceCopy Anchor Link

Create a serviceCopy Anchor Link

Update a serviceCopy Anchor Link

Delete a serviceCopy Anchor Link

Common errorsCopy Anchor Link

On this page