DocumentationAgent and server API reference

Agent and server API reference

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-Agent carries the agent version, X-DLPIA-Capabilities declares its capabilities.
  • Timestamps: every response carries RFC 7231 Date; the agent uses it for its monotonic marker.
  • Idempotency: event uploads are de-duplicated by id on the server.

mTLS authentication

  1. 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.
  2. It posts the request to POST /api/v1/devices/enroll with its enrolment token.
  3. The server signs a 12-month client certificate and returns the validation chain.
  4. The agent automatically renews at the two-thirds point of the certificate validity, around 8 months in.
  5. The server certificate is validated against the CA declared in configuration, not the Windows store.

Agent endpoint catalog

Endpoints the agent calls on /api/v1/*.
MethodPathRoleAuth
POST/devices/enrollInitial enrolment, client certificate issuance.Token
POST/events/batchEvent upload in zstd NDJSON.mTLS
GET/events/{id}/ackCheck an event has been acknowledged.mTLS
POST/anchorsSubmit an integrity chain anchor.mTLS
GET/config?version=<hash>Ed25519 JWS endpoint configuration.mTLS
GET/catalog?version=<hash>JWS AI service catalog.mTLS
GET/licenseSigned license and revocation list.mTLS
GET/models?id=<id>&min-version=<v>Ed25519 signed BLOB model.mTLS
GET/certificate/renewClient certificate renewal.mTLS
POST/statusAgent heartbeat with internal metrics.mTLS
WS/notifyLong-lived push notification channel.mTLS
POST/diagnosticsDiagnostic 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

Four upload modes, configurable per event type.
ModeBehaviourTypical use
Real timeStreamed, batched at most 1 s.Small fleets, alerts.
Periodic batchEvery N minutes, default 15.Recommended default.
DeferredWithin a time window, or on non-metered network.Nomadic endpoints, low bandwidth.
On demandTriggered 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.

Notification types pushed by the server.
TypePayloadExpected agent action
config_availableversionDownload /config after a 0-10 min random delay.
catalog_availableversionDownload /catalog.
model_availableid, versionDownload /models.
license_availableissued_atDownload /license.
update_availableversion, delay_maxDownload the agent update.
diag_requestedcorrelation_idProduce 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: kid identifies the client key, x5c is 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

Two token families, two uses.
FamilyPrefixDurationScopeVisibility
Endpoint enrolmentmge_24 to 72 h, single useA single endpoint enrolment.Shown once, SHA-256 stored.
Public APImgs_1 to 366 daysNarrow scopes: events.read, alerts.read, etc.Secret shown once, SHA-256 stored.
License servicemgls_1 to 366 daysNarrow scopes: tenants.read, tenants.write.Secret shown once.

HTTP status codes

Standard HTTP codes used by the API.
CodeMeaningTypical case
200Success.Standard operation.
201Created.Enrolment successful.
202Accepted.Event batch accepted.
304Not modified.Up-to-date config or catalog.
400Bad request.Invalid JSON or NDJSON syntax.
401Unauthenticated.Missing mTLS certificate, invalid token.
403Forbidden.Insufficient scopes.
404Unknown resource.Unknown model or dashboard.
409Conflict.Endpoint already enrolled.
413Too large.Batch over 1 MB compressed.
422Unprocessable.Invalid configuration signature.
429Too many requests.Quota or brute-force detected.
503Service unavailable.Retry per Retry-After.

Shared data models

  • UsageEvent — see the Events and audit reference.
  • License — JWS payload, see the License reference.
  • Catalog — array of ServiceEntry signed 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.