Alerts REST API
Everything the Alerts screen does goes through the alert service, so you can do the same from any language. Send your token in the Authorization header as for every REST call.
https://api.opendatadsl.com/api/alert/v1/{source}
| Source | Alerts |
|---|---|
private | Your alerts, in the data environment of the request |
common, public | Shared alerts |
Your alerts belong to a data environment. Send x-odsl-environment: test1 (for example) to work in an environment other than production.
Requests
| Method | Path | What it does |
|---|---|---|
| GET | v1/{source} | List alerts. Takes _filter, _sort, _skip, _limit, _count and _project |
| GET | v1/{source}/{id} | One alert with its timeline |
| POST | v1/{source} | Raise an alert (your alerts only: use private) |
| POST | v1/{source} with the alert's _id in the body | Change that alert, like PATCH. This is what ODSL save and the Python SDK's update do |
| PATCH | v1/{source}/{id} | Change an alert |
| POST | v1/{source}/{id}/comment | Add a comment |
| PATCH | v1/{source}/{id}/comment/{entry} | Edit a comment |
| DELETE | v1/{source}/{id}/comment/{entry} | Delete a comment |
| DELETE | v1/{source}/{id} | Delete an alert (administrators only; alerts are normally closed, not deleted) |
Every request that changes an alert returns the alert as it now is.
List alerts
GET alert/v1/private?_filter={"status":"open","agent":"client"}&_sort={"created.at":-1}&_limit=50&_count=true
With _count=true, the x-total-count response header holds the number of matching alerts. Lists include each alert's timeline (leave it out with _project, for example {"timeline":0}, when you do not need it). On a shared alert, your team's own comments are only merged into the timeline when you read that one alert.
Useful filters:
| Filter | Finds |
|---|---|
{"status":"open"} | Open alerts |
{"agent":"client"} | Alerts waiting on your team |
{"severity":{"$in":["critical","high"]}} | Critical and high alerts |
{"subject.id":"ICE.NDEX.NLB"} | Alerts about a dataset or other item |
{"issue":"completeness"} | Alerts of one type |
{"key":"dataset/ICE.NDEX.NLB/2026-10-27/completeness"} | The alerts with a key |
{"created.at":{"$gte":"2026-10-01T00:00:00"}} | Alerts raised since a date |
Raise an alert
POST alert/v1/private
{
"title": "NGE.BROKER.NBP prices look stale since Monday",
"message": "The broker NBP Day-ahead and Month+1 have not changed for three days",
"severity": "high",
"issue": "quality",
"agent": "opendatadsl",
"subject": {"service": "dataset", "id": "NGE.BROKER.NBP"},
"key": "northgate/stale/NGE.BROKER.NBP",
"comment": "Tom Clarke is the contact on our side"
}
Only title is required. See Raise an alert for the fields and defaults, and for what a key does. The response is the new alert, or the open alert with the same key with one more occurrence.
A program running as a process can say which run it is part of with these headers. An alert it raises is then a root alert about the run, and everything it saves is traced to the run:
| Header | Value |
|---|---|
x-odsl-trace | The trace: the process execution id, or the trace the run was started with |
x-odsl-process | The process name |
x-odsl-execution | The process execution id |
x-odsl-ondate | The date the run is for (yyyy-mm-dd, optional) |
Problems folded into root causes
The problems recorded on root causes are kept apart from the alerts. Reading a root cause by id includes them (impacts, impactCount, openImpactCount and their timeline entries), and lists give impactCount and openImpactCount. To list them across root causes:
GET alert/v1/private?_function=impacts&from=2026-11-02&to=2026-11-02
GET alert/v1/private?_function=impacts&trace=7a1c2e90-1f44-4d0b-9b0e-5c2b8e6f1d31
GET alert/v1/private?_function=impacts&root=ALR-2026-000412
| Parameter | Meaning |
|---|---|
trace | The problems of one run, by its trace id |
root | The problems folded into one root cause |
from, to | Problems first seen, or recovered, in the period. A date (2026-11-02) or a date and time; to is included when it is a date |
At least one is needed. The result is newest first, at most 2,000, with the fields of the impacts of a root cause (see the Reference) plus root and rootSource. You see your own problems, and on shared root causes only yours.
Link an alert to a root cause
PATCH alert/v1/private/ALR-2026-000415/cause
{"root": "ALR-2026-000412"}
rootSource (private, common or public) is taken from the root cause's id when it is left out. Send {"root": null} to remove the link. The response is the alert. A private root cause must be yours, in the same data environment; a root cause cannot be linked to another. On shared alerts only OpenDataDSL can link.
Change an alert
PATCH alert/v1/private/ALR-2026-000402
{
"status": "closed",
"resolution": "Loader fixed by OpenDataDSL; file reloaded at 10:15",
"comment": "Checked against the broker run",
"_version": 5
}
| Field | Values |
|---|---|
status | open or closed. Closing needs resolution. Reopening is possible for 7 days after closing |
resolution | What was wrong and what was done |
agent | client (your team), opendatadsl, or a data vendor's name |
severity | critical, high, medium or low |
comment | A comment added with the change |
title, description, assignee | Text |
tags | An array of text |
_version | The version you read. If the alert has changed since, the request is refused with HTTP 409: read it again and repeat the change. Leave it out to change the alert as it is now |
On a shared alert (common or public) you can only add comments; any other change is refused.
Comments
POST alert/v1/common/ALC-2026-000407/comment
{"text": "Our month-end report waits for this file"}
PATCH alert/v1/private/ALR-2026-000401/comment/2
{"text": "Our settlement run needs the Dec-26 and Jan-27 contracts"}
DELETE alert/v1/private/ALR-2026-000401/comment/2
The {entry} is the id of the comment's timeline entry: a number on your own alerts, and an id starting t- for your team's comments on a shared alert. Comments can be changed by their author, an administrator of your company, or OpenDataDSL.
Errors
A refused request has an HTTP error status and the reason in the x-odsl-error response header, for example:
| Status | Reason |
|---|---|
| 400 | A missing or wrong field, for example Missing parameter: title, Missing parameter: resolution (closing without a resolution) or severity must be one of [low, medium, high, critical] |
| 403 | You do not have the security policy for the alert service, or the change is for OpenDataDSL only (changes to shared alerts other than comments) |
| 404 | The alert does not exist, or is not yours |
| 409 | The alert has been changed by someone else since you read it |