> For the complete documentation index, see [llms.txt](https://witfy.gitbook.io/clowrk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://witfy.gitbook.io/clowrk/api/service-account-events.md). # Service Account — Events API A REST API that lets a **Service Account** read and act on **Events** (availability/performance incidents raised on Clowrk kanban cards) from outside Clowrk. Use it to integrate a monitoring tool, an ITSM system, or a NOC automation with Clowrk's event lifecycle. ## 1. Prerequisites You need a Service Account. A Clowrk Place administrator creates one from **Manage Place → Access → Generate Service User** — see [Service Account](/clowrk/company/service-account.md) for details. The **username and password are shown only once** at creation time; store them securely. Your Service Account only sees events for the **place** it belongs to, and only for the **boards** it has been added to as a member. Ask your Clowrk administrator to: * Add the account as a member of the relevant board(s). * Optionally configure a **read filter** per board (by event criticality, status, or impact level) to restrict what that board's events the account can retrieve. If no filter is configured, the account sees only **open** events on that board by default, with no criticality restriction. ## 2. Authentication Log in with the Service Account's username and password to get an access token: ``` POST /api/v2/auth/service-account Content-Type: application/json { "username": "", "password": "" } ``` ```json { "accessToken": "eyJhbGciOiJIUzUxMiJ9...", "wsToken": "eyJhbGciOiJIUzUxMiJ9..." } ``` * The token expires in **30 days**. There is no refresh flow for this token — simply log in again before it expires. * `wsToken` is only needed if you also connect over WebSocket/STOMP; it is not used by this REST API. * Send the token on every call below: ``` Authorization: Bearer ``` > **Keep this token confidential.** Treat it like a password — don't embed it in client-side code or commit it to a public repository. If it's ever exposed, ask your Clowrk administrator to remove and recreate the Service Account (see [Service Account](/clowrk/company/service-account.md) — credentials cannot be rotated in place, only recreated). ## 3. Base URL | Environment | Origin | | ----------- | --------------------------- | | Production | `https://itom.app.priax.io` | All paths below are relative to this base URL, e.g. `https://itom.app.priax.io/services/events`. ## 4. Common request headers | Header | Required | Default | Notes | | ----------------- | ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Yes | — | `Bearer ` from §2 | | `Zone-Id` | No (see exception) | `America/Sao_Paulo` | IANA time zone id; controls how date/time fields in the response are rendered. **Required, with no default,** on `GET .../maintenance` (§7) | | `Accept-Language` | No | `pt-BR` | Locale used for system-generated comments (e.g. the note left when an event is acknowledged) | ## 5. Reading events All read endpoints return `200 OK` with a paginated envelope (see [§8](#8-event-object-reference)), except the single-event lookup and the diagnostic endpoint noted below. ### 5.1 `GET /services/events` — list/filter events | Query parameter | Type | Default | Notes | | -------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `page` | number | `0` | | | `pageSize` | number | `100` | | | `sortBy` | string | `createAt` | `createAt` or `solutionDesiredAt` | | `sortDirection` | string | `ASC` | `ASC` or `DESC` | | `periodStartInMilliseconds` | number | — | Filter by event creation date (epoch millis) | | `periodEndInMilliseconds` | number | now | | | `withUnacknowledgedEvents` | boolean | `false` | | | `withAcknowledgedEvents` | boolean | `false` | If both are `true`, returns events regardless of acknowledgement state | | `suppressMaintenance` | boolean | `false` | Exclude events currently in a maintenance window | | `criticality` (repeat the param per value, or pass a single comma-separated `criticalities`) | string\[] | all | `OK`, `ERROR`, `IGNORED`, `INFO`, `WARNING`, `AVERAGE`, `HIGH`, `DOWN`, `UNKNOWN` | | `status` (repeat the param per value, or pass a single comma-separated `statuses`) | string\[] | `OPEN` only, if no read filter is configured (see §1) | `NEW`, `PROCESSING`, `ACCEPTED`, `REJECTED`, `SOLVED`, `CLOSED`, `OPEN`, `REOPEN`, `WAITING_REVISION` — in practice you'll mostly see `OPEN`, `PROCESSING`, `SOLVED`, `CLOSED`, and `WAITING_REVISION` | ```bash curl --location 'https://itom.app.priax.io/services/events?status=OPEN&criticality=INFO,WARNING,AVERAGE,HIGH,DOWN&page=0&pageSize=100' \ --header 'Authorization: Bearer ' ``` > **Default status behavior**: unless your administrator has configured a read filter for the account (§1), results are clamped to **open events only**, regardless of what you pass in `status`/`statuses`. To retrieve resolved/closed events, ask your administrator to configure the account's read filter. ### 5.2 `GET /services/events/withAcknowledgedEvents` Same pagination parameters as §5.1 (`page`, `pageSize`, `sortBy`, `sortDirection`). Shorthand for "acknowledged events, all criticalities". ### 5.3 `GET /services/events/withUnacknowledgedEvents` Same as above, shorthand for "unacknowledged events". ### 5.4 `GET /services/events/{eventId}` Look up a single event by id (scoped to your account's place). Returns: ```json { "status": 200, "body": { "...": "see §8" } } ``` Returns an error response with `"message": "Event not found for criteria"` if the event doesn't belong to your place. ### 5.5 `GET /services/events/{eventId}/diagnostic` Returns the event's KPI diagnostic messages (only available for CMDB-backed events). ```bash curl --location 'https://itom.app.priax.io/services/events/35103/diagnostic' \ --header 'Authorization: Bearer ' ``` ```json [ { "status": "DOWN", "message": "/Common/LB_PORTALV2_PRR_80 Virtual Server Avail State. State is: 4", "ciName": "BIG-IP Virtual Server", "ciDn": "/Common/LB_PORTALV2_PRR_80.vip-gerencia-f5-Cluster(BIG-IP Virtual Server)", "indicatorName": "Availability State" } ] ``` `message` may be `null` if no diagnostic text matches the event's current criticality. ## 6. Acting on events > Write endpoints act on any event in your account's place — they are **not** restricted by the per-board read filter described in §1. If your account can act on a board, it can acknowledge/comment/schedule maintenance on any event on that board, even ones a read filter would otherwise hide from `GET` calls. ### 6.1 `POST /services/events/acknowledge` — acknowledge multiple events ```json { "eventIds": [12583, 12584, 12585], "comment": "Batch acknowledge" } ``` `comment` is optional. Returns `200` with a summary if all succeeded, or an error response listing which ids failed. Unlike the single-event endpoint below, this accepts an event regardless of its current status. ### 6.2 `PUT /services/events/{eventId}/acknowledge` — acknowledge one event Body is plain text — the optional comment: ```bash curl --location --request PUT 'https://itom.app.priax.io/services/events/12572/acknowledge' \ --header 'Content-Type: text/plain' \ --header 'Authorization: Bearer ' \ --data 'Acknowledged via monitoring bot' ``` Returns an error if the event is currently in a **triage/processing** state — it must first move past that stage (automatically or via a user action) before it can be acknowledged through this endpoint. On success, returns the updated event (§8). If a comment is provided, it's added as a system comment on the card (in the language set by `Accept-Language`). ### 6.3 `PUT /services/events/{eventId}/comment` — add a comment (plain text) ```bash curl --location --request PUT 'https://itom.app.priax.io/services/events/57246/comment' \ --header 'Content-Type: text/plain' \ --header 'Authorization: Bearer ' \ --data 'Investigating with the network team' ``` Returns the updated event (§8) on success. ### 6.4 `POST /services/events/{eventId}/comment` — add a comment (JSON) ```json { "createdBy": "monitoring-bot", "comment": "Investigating with the network team", "system": "ZABBIX" } ``` Same effect as §6.3, provided as JSON instead of plain text. Only `comment` is stored — `createdBy` and `system` are accepted for forward-compatibility but currently have no effect; the comment is attributed to the Service Account itself. Prefer §6.3 unless your client specifically needs JSON. ### 6.5 `PUT /services/events/{eventId}/change-external-status` — sync a status from an external system Lets an external ITSM or monitoring tool (e.g. an incident-management system) push its own status change back into Clowrk. ```json { "oldStatus": "Assigned", "newStatus": "Resolved", "comment": "Resolved externally", "system": "HELIX" } ``` * `system` (case-insensitive) must be one of: `PRIAX`, `ZABBIX`, `MICROSOFT`, `HELIX`, `GUACAMOLE`, `NONE`. Any other value returns an error. * `oldStatus`/`newStatus` are free-text labels from the external system's own status vocabulary. * `comment` is accepted but currently has no effect. ### 6.6 `POST /services/events/notified` — not yet available This endpoint is defined but **not implemented** — every call returns an error (`"Service account notification service has not being implemented"`). Don't build against it yet. ## 7. Maintenance windows Suppress notifications for an event during a known/planned outage. | Method | Path | Purpose | | ------ | -------------------------------------------------------- | -------------------------------------- | | GET | `/services/events/{eventId}/maintenance` | List maintenance windows for the event | | PUT | `/services/events/{eventId}/maintenance` | Create a maintenance window | | DELETE | `/services/events/{eventId}/maintenance/{maintenanceId}` | Delete a maintenance window | > The `GET` call **requires the `Zone-Id` header** — it has no default here, unlike every other endpoint in this doc. **Create** — request body: ```json { "startAtInMilliseconds": 1728406800000, "endAtInMilliseconds": 1728421200000, "comment": "Scheduled network maintenance" } ``` `endAtInMilliseconds` is mandatory; `startAtInMilliseconds` defaults to now if omitted; `comment` is optional (max 450 characters). Returns the id of the created maintenance window. **List** — response: ```json [ { "id": 40, "startAt": "2024-10-08T18:00:00", "endAt": "2024-10-08T22:00:00", "startAtMilliseconds": 1728406800000, "endAtMilliseconds": 1728421200000 } ] ``` While an event is inside an active maintenance window, its `maintenance` flag (§8) is `true`. ## 8. Event object reference List endpoints (§5.1–5.3) return this envelope: ```json { "page": 0, "pageMax": 2, "pageSize": 100, "total": 113, "result": [ { "...": "one event per entry, shape below" } ] } ``` > The `page` field in the response currently always reports `0`, regardless of the page you requested. Use `pageMax` and `total` to drive pagination — don't rely on `page` to reflect the request. Each entry in `result` (and the `body` of a single-event lookup, §5.4): | Field | Type | Notes | | ------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------ | | `caseProgressId` | number | The case number shown in the Clowrk UI | | `name` | string | Card/case name | | `boardCardId` | string | Card identifier | | `boardCardLink` | string | Same as `boardCardId` (kept for older clients) | | `boardCardDetailsLink` | string | A shareable URL to view the event in Clowrk | | `currentBoardId` / `currentBoard` | string | Board the card is on | | `currentListId` / `currentList` | string | List (column) the card is on | | `eventId` | number | Use this id with the endpoints in §6 | | `externalEventId` | string | Id of the event in the source monitoring system, if applicable | | `hostname` | string | Affected host, when available | | `rootCauseCIName` / `rootCauseCIType` / `rootCauseCIDN` | string | Root-cause CI identification, when available | | `type` | string | Event source type, e.g. `PRIAX_AVAILABILITY_EVENT`, `PRIAX_PERFORMANCE_EVENT` | | `ack` | boolean | Whether the event has been acknowledged | | `notified` | boolean | Whether at least one notification has gone out for this event | | `maintenance` | boolean | Whether a maintenance window is currently active (§7) | | `eventStatus` | string | See the status list in §5.1 | | `criticality` | string | See the criticality list in §5.1 | | `statusSentence` | string | Reserved for future use — currently always `null` | | `openedAt` | datetime | When the event was admitted into the workflow, in the requested `Zone-Id` | | `solvedAt` | datetime | When the event was first resolved, in the requested `Zone-Id` | | `createdAt` | datetime | Case start date, in the requested `Zone-Id` | | `solutionDesiredAt` | datetime | SLA due date, in the requested `Zone-Id` | | `channels` | string\[] | Notification channels used for this event | | `documentationTitle` / `documentationInstructions` | string | Linked runbook/knowledge-base documentation, if any | | `diagnosticMessage` | string | Last-known root-cause diagnostic message (a snapshot — call §5.5 for the live value) | ## 9. Error handling Most endpoints in this API respond with **HTTP 400** for nearly every failure mode — invalid credentials, an event that doesn't exist, a validation error, or an unexpected server issue all come back as `400 Bad Request` with a `message` field describing the cause. A missing or invalid `Authorization` header returns `401` from the platform's auth layer before it reaches this API. **Always read the `message` field** to understand what went wrong — don't branch your integration logic on HTTP status codes beyond "success vs. failure". ## 10. Known limitations * `POST /services/events/notified` is not implemented (§6.6). * The response envelope's `page` field always reports `0` (§8) — use `pageMax`/`total` instead. * `createdBy` and `system` on `POST .../comment` (§6.4), and `comment` on `PUT .../change-external-status` (§6.5), are accepted but currently have no effect. * Batch acknowledge (§6.1) has no status restriction, while single acknowledge (§6.2) rejects events still in triage — this asymmetry is current behavior, not a bug you need to work around beyond expecting it.