Oxelone Docs

Search docs and API

Find a guide, a section of one, or an API operation by its name.

Open console (opens in a new tab)

API reference Resources

Alerts

Alerts raised by policies.

2 operations

List alerts

GET/alerts

What a policy's Alert action or a justified override raised, newest first.

Query parameters

fstring · null

The filter expression, e.g. all;outcome~in~undetermined;mode~in~monitor.

The first segment is the join (all or any); each later segment is field~op~values, with op one of in, nin, before, after and values separated by commas. Fields: outcome, mode, severity, policy, machine, service, interaction, at. A malformed segment is ignored; a field this list does not have is a 400 naming it.

cursorstring · null

Where the previous page stopped. Opaque; an unreadable one starts over.

limitinteger · null

Rows wanted. Clamped to 200.

raised_bystring · null

action or justification: narrow to what raised the alert. Anything else is a 400 naming it.

include_removedboolean · null

true also lists alerts whose machine or connection was removed. They are kept as audit history and are left out of the default list.

Response200

alertsAlert[]required
decided_atstringrequired

The decider's clock — what the list is ordered and filtered by, because that is what an operator means by this week.

idstringrequired
outcomestringrequired

passed, alerted, blocked or undetermined.

`undetermined` is not a flavour of `passed`. It says nothing looked, where passed says something looked and was satisfied. A reader that renders them the same has reproduced the placebo failure the outcome was added to make visible.

raised_bystringrequired

What raised it: action (the policy's Alert action) or justification (a justified override). Every alert has one.

recorded_atstringrequired

When the server recorded the alert, by the server's clock. Retention ages alerts by this time, not by decided_at.

referencestringrequired

The support code a stopped person was given, where one was shown.

totalintegerrequired

Every alert the filter matched, across all pages, not only this one.

next_cursorstring · null

Pass back as cursor for the next page. null means this was the last.

Errors

400

The filter names a field or value this surface does not have

401

No valid session

403

Caller lacks alerts:read in this workspace

One alert, by its id

GET/alerts/{alert}

A 404 for an unknown id and for one belonging to another workspace, which is deliberately not a 403: a 403 would confirm the id exists somewhere, which is the one thing a probe wants to learn, and the rest of this API already answers a cross-workspace id this way.

Path parameters

alertstringrequired

Response200

decided_atstringrequired

The decider's clock — what the list is ordered and filtered by, because that is what an operator means by this week.

idstringrequired
outcomestringrequired

passed, alerted, blocked or undetermined.

`undetermined` is not a flavour of `passed`. It says nothing looked, where passed says something looked and was satisfied. A reader that renders them the same has reproduced the placebo failure the outcome was added to make visible.

raised_bystringrequired

What raised it: action (the policy's Alert action) or justification (a justified override). Every alert has one.

recorded_atstringrequired

When the server recorded the alert, by the server's clock. Retention ages alerts by this time, not by decided_at.

referencestringrequired

The support code a stopped person was given, where one was shown.

servicestringrequired
severitystringrequired

The alert's severity: info, low, medium, high or critical. It is the severity the policy's Alert action set, or the outcome's default where the policy named none.

sourcestringrequired

inline, policy or engine. Carried verbatim: a reader must render a value it does not recognise rather than folding the field into a boolean.

connection_idstring · null

The connection whose sync ingested the interaction this alert was made about; null on every alert a machine's interaction produced, and on every alert whose interaction is gone.

endpointstring · null
engine_labelsstring[] · null
engine_run_idstring · null

The run to open, and null once retention has taken it.

Read, not derived from `engine_type`. A run is swept at 30 days by default and an alert is kept for a year, so the link is dead for most of an alert's life; a page that offers it anyway sends the reader to a 404, and the evidence beside it (engine_score, engine_labels) is still true.

engine_scorenumber · null
engine_typestring · null
engine_versionstring · null
hoststring · null
interaction_idstring · null

The interaction this judged. null for a server-side decision whose observation arrives later on a different request, and for a fail-open where there may be none at all — not a sign that anything is missing.

justificationstring · null

The person's own words on a justified alert; null on every other.

machine_idstring · null
machine_namestring · null
methodstring · null
modestring · null

monitor or enforce, as the policy stood when it decided. A monitor alert stopped nothing. null only on some older alerts.

policy_idstring · null
policy_namestring · null

The policy's name as it stands now, for a sentence. null where the policy has been deleted — the version is still named, so the row degrades to an id rather than to nothing.

policy_versioninteger · null

The exact version that decided, not the one that is current. An author may have rewritten the rule since; this is what makes the row evidence rather than a pointer at whatever the policy says today.

reasonstring · null

Why, in the decider's own words. Never customer content.

undetermined_reasonstring · null

Which engine returned no verdict, on an undetermined. Names an engine.

Errors

401

No valid session

403

Caller lacks alerts:read in this workspace

404

No such alert in this workspace