Machine API

The machine API is for a SIEM, a SOAR or a script. It is never used with a user session: every call carries a machine access credential, and every call is scoped to that credential’s client.

Create machine access

In Settings > API & Webhooks, the super administrator creates machine access. It returns:

• a client ID (avc_…);
• a secret (avs_…), shown once and kept only as a hash;
• the API address;
• the scopes granted. Nothing is granted by default.

Optionally, the access can be restricted to origin networks and given an expiry date. The secret can be rotated at any time. Creating and rotating need a sign-in less than 10 minutes old.

Authenticate

Two headers:

curl -sS https://aarview.example.org/api/v1/ext/whoami \
  -H "X-AarView-Client-Id: avc_..." \
  -H "X-AarView-Client-Secret: avs_..."

HTTP Basic authentication (id:secret) is accepted too. The whoami answer gives the access’s client, its name and its scopes.

An unknown, expired or disabled credential, or one used from a network it is not allowed from, gets the same 401 answer, with no distinction.

Scopes

Scope	Allows
ingest:alerts	pushing alerts
incidents:read	reading incidents
incidents:comment	adding a note to an incident
stats:read	reading statistics
archive:read	archiving its own events and alerts (on-site archive tool)

Endpoints

Base: https://<your domain>/api/v1/ext

Method and path	Scope	Purpose
GET /whoami	none	who the credential is, its scopes
POST /alerts	ingest:alerts	push alerts
GET /incidents	incidents:read	list incidents
GET /incidents/{id}	incidents:read	read one incident
POST /incidents/{id}/notes	incidents:comment	add a note
GET /stats	stats:read	the client’s statistics
GET /archive	archive:read	a window of events or alerts, for the on-site archive

List incidents

Parameters: page, per_page (200 at most), status (open, in_progress, resolved, closed), severity (critical, high, medium, low), kind (case or alert), since (ISO 8601 date), rule_id.

curl -sS "https://aarview.example.org/api/v1/ext/incidents?status=open&severity=critical" \
  -H "X-AarView-Client-Id: avc_..." \
  -H "X-AarView-Client-Secret: avs_..."

Add a note

visibility is internal (stays with your team, the default) or client (shown to the client). The text is 5,000 characters at most.

curl -sS https://aarview.example.org/api/v1/ext/incidents/<id>/notes \
  -H "X-AarView-Client-Id: avc_..." \
  -H "X-AarView-Client-Secret: avs_..." \
  -H "Content-Type: application/json" \
  -d '{"body": "Host reimaged by the systems team.", "visibility": "internal"}'

Statistics

GET /stats?days=30: the Statistics view’s figures for the credential’s client, over 1 to 365 days.

Push alerts

POST /api/v1/ext/alerts takes a list of alerts, 100 at most per call.

Field	Required	Content
title	yes	512 characters at most
source	yes	your tool’s name, 64 characters at most
source_ref	no	your id for the alert; it is how a duplicate is recognised
severity	no	from 1 (low) to 4 (critical)
source_level	no	the source tool’s level, from 0 to 15, converted by AarView instead of severity
description	no	20,000 characters at most
alert_type	no	your category
tags	no	list of tags
observables	no	list of {"data_type": "ip", "data": "203.0.113.7"}
observed_at	no	ISO 8601 date of the observation
tlp	no	from 0 to 3, 2 by default
raw	no	the original event

curl -sS https://aarview.example.org/api/v1/ext/alerts \
  -H "X-AarView-Client-Id: avc_..." \
  -H "X-AarView-Client-Secret: avs_..." \
  -H "Content-Type: application/json" \
  -d '[{"title": "SSH login from an unknown address", "source": "my-tool",
        "source_ref": "evt-2041", "severity": 3,
        "observables": [{"data_type": "ip", "data": "203.0.113.7"}]}]'

The answer gives how many alerts were received, created and recognised as duplicates, and the ids created. The client is never read from the body: it comes from the credential. Sending the same alert again (same source, same reference) does not create a second incident.

Generic format

For a tool that can only send its own JSON, create a connected source with the generic format instead. AarView reads:

Data	Fields read, in order
title	title, name, rule, rule_name, alert
severity	severity, level, priority: a word (low, medium, high, critical…), a number from 1 to 4, or a score out of 10 or 100
reference	id, ref, alert_id, uuid
description	description, message, details
date	timestamp, time, @timestamp
observables	observables (type and value, or data_type and data), and values found in fields or event
tags	tags

An alert without a title is rejected; a missing or unknown severity becomes “medium”.