Agent and server API reference
Interfaces between the agent and the aggregation server, mTLS authentication, /api/v1/* endpoints, zstd NDJSON format, signed JWS catalog and config, BLOB models.
The agent talks to the aggregation server over mTLS HTTPS to upload events, pull its configuration, the AI service catalog, detection models, and receive notifications. The server's public API, in turn, exposes a service token to SIEMs and third-party tools.
Base URL and versions
- Base URL:
https://<server>/api/v1/· every resource is versioned in the path. - Agent headers:
User-Agentcarries the agent version,X-DLPIA-Capabilitiesdeclares its capabilities. - Timestamps: every response carries RFC 7231
Date; the agent uses it for its monotonic marker. - Idempotency: event uploads are de-duplicated by
idon the server.
mTLS authentication
- At enrolment, the agent generates a non-exportable key pair in the TPM (or software CNG with SYSTEM-only ACL) and a P-256 certificate request.
- It posts the request to
POST /api/v1/devices/enrollwith its enrolment token. - The server signs a 12-month client certificate and returns the validation chain.
- The agent automatically renews at the two-thirds point of the certificate validity, around 8 months in.
- The server certificate is validated against the CA declared in configuration, not the Windows store.
Agent endpoint catalog
| Method | Path | Role | Auth |
|---|---|---|---|
| POST | /devices/enroll | Initial enrolment, client certificate issuance. | Token |
| POST | /events/batch | Event upload in zstd NDJSON. | mTLS |
| GET | /events/{id}/ack | Check an event has been acknowledged. | mTLS |
| POST | /anchors | Submit an integrity chain anchor. | mTLS |
| GET | /config?version=<hash> | Ed25519 JWS endpoint configuration. | mTLS |
| GET | /catalog?version=<hash> | JWS AI service catalog. | mTLS |
| GET | /license | Signed license and revocation list. | mTLS |
| GET | /models?id=<id>&min-version=<v> | Ed25519 signed BLOB model. | mTLS |
| GET | /certificate/renew | Client certificate renewal. | mTLS |
| POST | /status | Agent heartbeat with internal metrics. | mTLS |
| WS | /notify | Long-lived push notification channel. | mTLS |
| POST | /diagnostics | Diagnostic bundle, when upload is enabled. | mTLS |
Event upload
- Batch size: at most 1,000 events OR 1 MB compressed, whichever comes first.
- Compression: zstd level 3 by default.
- Format: newline-delimited JSON (NDJSON), one event per line.
- Guarantee: at least once; duplicates are de-duplicated server-side by
id. - Retry: exponential backoff with jitter, from 1 s to 1 h.
POST /api/v1/events/batch HTTP/1.1
Host: aggregator.maelgard.example
Content-Type: application/x-ndjson
Content-Encoding: zstd
X-DLPIA-Capabilities: v=2026.10,models=pii;health;finance
Authorization-Context: mTLS
<zstd compressed NDJSON body>{
"acked": [
"018f3b2a-7c6d-7e4a-9f12-0a1b2c3d4e5f",
"018f3b2b-9d1e-7a21-b304-5f6a7b8c9d0e"
],
"rejected": [],
"status": "ok"
}Upload modes
| Mode | Behaviour | Typical use |
|---|---|---|
| Real time | Streamed, batched at most 1 s. | Small fleets, alerts. |
| Periodic batch | Every N minutes, default 15. | Recommended default. |
| Deferred | Within a time window, or on non-metered network. | Nomadic endpoints, low bandwidth. |
| On demand | Triggered by the server or by dlpia-admin. | Investigation, support. |
Notification channel
The server maintains a long-lived WebSocket channel with every agent, /api/v1/notify, that signals the availability of new items.
| Type | Payload | Expected agent action |
|---|---|---|
config_available | version | Download /config after a 0-10 min random delay. |
catalog_available | version | Download /catalog. |
model_available | id, version | Download /models. |
license_available | issued_at | Download /license. |
update_available | version, delay_max | Download the agent update. |
diag_requested | correlation_id | Produce and upload a diagnostic bundle. |
Catalog format
The AI service catalog is an Ed25519 JWS signed by the vendor, extended by the client. Each entry describes an AI service from the interception point of view.
{
"service_id": "openai-api",
"display_name": "OpenAI API",
"channel": "api",
"domains": ["api.openai.com"],
"endpoints": [
{
"method": "POST",
"path": "^/v1/chat/completions$",
"request_kind": "prompt",
"extraction": {
"format": "json",
"fields": ["$.messages[*].content", "$.system"]
}
},
{
"method": "POST",
"path": "^/v1/files$",
"request_kind": "upload",
"extraction": { "format": "multipart", "fields": ["file"] }
}
],
"processes": ["python.exe", "node.exe", "curl.exe"],
"risk": { "profile": "sanctioned", "default_action": "intercept" }
}Configuration format
- Envelope: compact Ed25519 JWS,
cty = maelgard-config. - Header:
kididentifies the client key,x5cis optional for chains. - Payload: see the Deploy section for the parameter list.
- Versioning: every document carries a fingerprint; the agent passes
?version=<hash>to avoid re-downloading.
GET /api/v1/config?version=sha256:9f1b…c3a HTTP/1.1
Host: aggregator.maelgard.example
HTTP/1.1 200 OK
Content-Type: application/jwt
X-DLPIA-Version: sha256:a4c0…9bd
eyJhbGciOiJFZERTQSIsImtpZCI6ImNmZy0yMDI2In0...BLOB models
Detection models are BLOB files signed Ed25519 by the vendor, served by /api/v1/models. The body format is BLOB 0.1.
GET /api/v1/models?id=pii&min-version=1.4.0 HTTP/1.1
Host: aggregator.maelgard.example
HTTP/1.1 200 OK
Content-Type: application/vnd.maelgard.model+blob
X-Model-Id: pii
X-Model-Version: 1.4.2
X-Model-Signature: <base64 Ed25519>
<binary BLOB 0.1 body>- A model is neither downloaded nor loaded if the license does not allow it (see License reference).
- The signature is verified before any load into memory.
- Versions follow SemVer. The agent asks for a major version and accepts the newest within that bound, capped by the license.
- A corrupt or badly signed model is discarded; the previous one stays loaded.
Enrolment and API tokens
| Family | Prefix | Duration | Scope | Visibility |
|---|---|---|---|---|
| Endpoint enrolment | mge_ | 24 to 72 h, single use | A single endpoint enrolment. | Shown once, SHA-256 stored. |
| Public API | mgs_ | 1 to 366 days | Narrow scopes: events.read, alerts.read, etc. | Secret shown once, SHA-256 stored. |
| License service | mgls_ | 1 to 366 days | Narrow scopes: tenants.read, tenants.write. | Secret shown once. |
HTTP status codes
| Code | Meaning | Typical case |
|---|---|---|
| 200 | Success. | Standard operation. |
| 201 | Created. | Enrolment successful. |
| 202 | Accepted. | Event batch accepted. |
| 304 | Not modified. | Up-to-date config or catalog. |
| 400 | Bad request. | Invalid JSON or NDJSON syntax. |
| 401 | Unauthenticated. | Missing mTLS certificate, invalid token. |
| 403 | Forbidden. | Insufficient scopes. |
| 404 | Unknown resource. | Unknown model or dashboard. |
| 409 | Conflict. | Endpoint already enrolled. |
| 413 | Too large. | Batch over 1 MB compressed. |
| 422 | Unprocessable. | Invalid configuration signature. |
| 429 | Too many requests. | Quota or brute-force detected. |
| 503 | Service unavailable. | Retry per Retry-After. |
Shared data models
UsageEvent— see the Events and audit reference.License— JWS payload, see the License reference.Catalog— array ofServiceEntrysigned by the vendor, extended by the client.Config— Ed25519 JWS document from four merged sources.Anchor—(seq, hash)pair signed by the endpoint key.Alert— type, severity, timestamp, device, link to the source event.