Skip to main content

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}
SourceAlerts
privateYour alerts, in the data environment of the request
common, publicShared alerts

Your alerts belong to a data environment. Send x-odsl-environment: test1 (for example) to work in an environment other than production.


Requests​

MethodPathWhat it does
GETv1/{source}List alerts. Takes _filter, _sort, _skip, _limit, _count and _project
GETv1/{source}/{id}One alert with its timeline
POSTv1/{source}Raise an alert (your alerts only: use private)
POSTv1/{source} with the alert's _id in the bodyChange that alert, like PATCH. This is what ODSL save and the Python SDK's update do
PATCHv1/{source}/{id}Change an alert
POSTv1/{source}/{id}/commentAdd a comment
PATCHv1/{source}/{id}/comment/{entry}Edit a comment
DELETEv1/{source}/{id}/comment/{entry}Delete a comment
DELETEv1/{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:

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

HeaderValue
x-odsl-traceThe trace: the process execution id, or the trace the run was started with
x-odsl-processThe process name
x-odsl-executionThe process execution id
x-odsl-ondateThe 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
ParameterMeaning
traceThe problems of one run, by its trace id
rootThe problems folded into one root cause
from, toProblems 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.


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
}
FieldValues
statusopen or closed. Closing needs resolution. Reopening is possible for 7 days after closing
resolutionWhat was wrong and what was done
agentclient (your team), opendatadsl, or a data vendor's name
severitycritical, high, medium or low
commentA comment added with the change
title, description, assigneeText
tagsAn array of text
_versionThe 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:

StatusReason
400A 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]
403You do not have the security policy for the alert service, or the change is for OpenDataDSL only (changes to shared alerts other than comments)
404The alert does not exist, or is not yours
409The alert has been changed by someone else since you read it

Next​

Notifications and automations