API basics

UnitOps exposes a REST API for integrations and automation.

Environment	Base URL
Production	https://api.unitops.datalakehouse.io
Staging	https://staging-api.unitops.datalakehouse.io

Interactive schema documentation is served by the API itself at /docs on the API host, and the OpenAPI document at /openapi.json.

Authentication

Send a bearer token from the identity provider:

curl -s "$API/api/v1/locations" \
  -H "Authorization: Bearer $TOKEN"

The token carries your organization, role, and location scope. Every endpoint applies the same authorization rules as the UI, so an API caller can never read more than the same user could in the browser.

Commonly used endpoints

Area	Endpoint	Purpose
Documents	POST /api/v1/documents/search	Search indexed document chunks
Documents	POST /api/v1/documents/{id}/index	Index a document for AI search
Custom dashboards	POST /api/v1/custom-dashboards	Create a dashboard from a YAML spec
Custom dashboards	POST /api/v1/custom-dashboards/{id}/publish	Publish a dashboard
Custom dashboards	POST /api/v1/custom-dashboards/{id}/embed	Mint an embed token and iframe snippet
Notifications	GET /api/v1/notifications/admin/channel-configs	Inspect per-organization channel providers
Notifications	PUT /api/v1/notifications/admin/channel-configs/{kind}	Set a channel provider
Notifications	POST /api/v1/notifications/admin/custom-rules	Create a custom rule
Notifications	GET /api/v1/notifications/admin/dead-letters	List permanently failed deliveries
Notifications	GET /api/v1/notification-channels/delivery-health	Recent deliveries and why each one was delivered, failed, or skipped
Notifications	POST /api/v1/notifications/admin/group-subscriptions	Fan a rule out to an email group

Example: create a custom alert rule

curl -s -X POST "$API/api/v1/notifications/admin/custom-rules" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "kind": "clone",
    "key": "ops.pacing_below_forecast.acme_strict",
    "name": "Pacing - Acme strict (5%)",
    "description": "Tighter pacing alert for executive review",
    "base_rule_key": "ops.pacing_below_forecast",
    "thresholds": {"gap_pct": 5.0},
    "severity": "critical",
    "default_channels": ["in_app", "email", "slack"],
    "cadence_cron": "*/15 * * * *"
  }'

Example: search documents

curl -s -X POST "$API/api/v1/documents/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"query": "closing checklist", "top_k": 5}'

Conventions

• All endpoints are versioned under /api/v1.
• Timestamps are ISO 8601 in UTC.
• Errors return a JSON body with a detail field and a conventional HTTP status.
• Rate limits apply to scheduler trigger endpoints and return 429 with Retry-After.

Versioning

Breaking changes ship behind a new version prefix. Additive fields can appear without a version bump, so parse defensively and ignore unknown fields.