53. API reference

A practical orientation to the REST API — base URL, auth, and the real endpoint groups. Not exhaustive OpenAPI; the live spec is the source of truth.

Everything you can do in the operator app, you can do over HTTP. This chapter is a map of the surface, not a line-by-line specification. For the complete, always-current schema, hit the live OpenAPI document at https://ops.daalu.io/openapi.json (Swagger UI at https://ops.daalu.io/docs).

Base URL and versioning

https://ops.daalu.io/api

Endpoints live under a version namespace — currently /api/v1. Every path in this chapter is relative to that, so /alerts means https://ops.daalu.io/api/v1/alerts.

Authentication

Use a personal access token (PAT). Create one in Settings → API tokens and send it as a bearer token (Chapter 43 covers minting and rotation):

Authorization: Bearer dpat_xxxxxxxxxxxxxxxxxxxxxxxx

Tenant scoping is automatic. The token resolves to a user, the user to a tenant, and every query is filtered to that tenant — you never pass a tenant ID, and you can’t read across tenants. A PAT carries exactly the permissions of the user who minted it.

Note: One endpoint group is the exception to bearer auth: event ingestion (POST /events) uses your tenant’s ingest key in the X-Daalu-Key header instead, so CI and scripts can emit events without a user token. See Chapter 40 — Webhooks.

A worked example

List critical alerts, then acknowledge one:

TOKEN="dpat_xxxxxxxxxxxxxxxxxxxxxxxx"
BASE="https://ops.daalu.io/api/v1"
 
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/alerts?severity=critical"
 
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "$BASE/alerts/$ALERT_ID/acknowledge"

Run a structured query over the timeline and export it as CSV:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"entity": "events", "since_hours": 24}' \
  "$BASE/reports/query/export?format=csv"

Endpoint groups

The table below lists the real router groups. Each row is a family of endpoints; consult the OpenAPI spec for exact request/response shapes.

This is the practical subset. The product ships more routers (agents, workflows, change proposals, clusters, the Assistant copilot, and more); the OpenAPI document enumerates them all.

Pagination

List endpoints return a JSON array and are bounded by query parameters rather than cursors. The common pair:

• since_hours — how far back to look (e.g. events default to 24, capped at two weeks).
• limit — maximum rows to return (e.g. events default to 100, capped at 500).

Narrow with the same filters you’d use in the UI — severity, module, and so on. For anything analytical, prefer POST /reports/query, which is purpose-built for structured queries and has a matching /export for CSV or JSON.

Errors

The API uses standard HTTP status codes, and error bodies carry a detail field:

{ "detail": "token not found" }

A note on scope

Treat this chapter as a starting map. Endpoints, fields, and defaults evolve; the openapi.json document is generated from the running code and is always authoritative. When you build against the API, generate your client from that spec rather than from this table.

Next: Chapter 50 — Troubleshooting