API reference (v1)¶

Base URL: https://<your-dxdt-host>/api/v1

All endpoints require bearer authentication unless marked otherwise. Responses are JSON. /api/v1 is a stable contract: endpoints documented here won't change incompatibly without a new version prefix.

Scope column

read endpoints work with either scope; read_write endpoints require a read_write token.

Service¶

Method & path	Scope	Description
`GET /api/v1/version`	none	Unauthenticated probe: `{service, api_version, revision}`
`GET /api/v1/me`	read	Identity + tenant for the presented token

Agent¶

Method & path	Scope	Description
`POST /api/v1/ask`	read_write	Run one agent turn, non-streaming. Body: `{"prompt": str, "session_id": str, "selected_tools": [str]?}`. Returns the final reply. Turns can take minutes — use a generous read timeout (the CLI uses 660s).
`GET /api/v1/stream`	read_write	Same, as Server-Sent Events. Query: `prompt`, `session_id`, `selected_tools` (comma-separated). Each event is a JSON object; the SSE `id:` is a monotonically increasing sequence number.
`GET /api/v1/stream/attach`	read_write	Reattach to the latest (possibly still-running) run of a session. Query: `session_id`, `after_seq` — replays events after `after_seq`, then streams live.

Runs are durable server-side: a dropped stream connection does not cancel the run — reattach with stream/attach.

Sessions¶

Method & path	Scope	Description
`GET /api/v1/sessions`	read	List sessions → `{"sessions": [...]}`
`POST /api/v1/sessions`	read_write	Create a named session
`GET /api/v1/history`	read	Message history for a session (`session_id`)
`PATCH /api/v1/sessions/{id}`	read_write	Rename: `{"name": str}`
`DELETE /api/v1/sessions/{id}`	read_write	Delete a session

Pulse¶

Method & path	Scope	Description
`GET /api/v1/pulse/overview`	read	Tenant-level summary: open findings, estimated savings, coverage
`GET /api/v1/pulse/findings`	read	List findings → `{"findings": [...]}`. Filters: `status`, `severity`, `domain`; sorting: `sort_by`, `sort_dir`
`GET /api/v1/pulse/findings/{id}`	read	One finding with evidence and audit trail
`GET /api/v1/pulse/recommendations`	read	Actionable recommendations with savings and effort
`GET /api/v1/pulse/resolved`	read	Resolved clusters with resolver attribution and evidence. Filter: `domain`
`POST /api/v1/pulse/findings/{id}/reinvestigate`	read_write	Re-check a finding's current state

Incidents¶

Method & path	Scope	Description
`GET /api/v1/incidents`	read	List incidents → `{"incidents": [...]}`. Filters: `status`, `severity`, `limit`
`POST /api/v1/incidents`	read_write	Create: `{"title": str, "severity"?, "description"?}` → `201`
`GET /api/v1/incidents/{id}`	read	Incident detail
`GET /api/v1/incidents/{id}/timeline`	read	Timeline events
`POST /api/v1/incidents/{id}/agent-investigate`	read_write	Dispatch an agent investigation of the incident
`POST /api/v1/incidents/{id}/war-room`	read_write	Open (or return) the incident's war room

Infrastructure graph¶

Method & path	Scope	Description
`GET /api/v1/graph/summary`	read	Node/edge counts, health rollup
`GET /api/v1/graph/search`	read	Search mapped resources (`q`)
`GET /api/v1/graph/blast-radius/{id}`	read	Blast radius for a resource, by dependency depth
`GET /api/v1/graph/health`	read	Per-resource health (open findings overlay)
`GET /api/v1/graph/risks`	read	Single points of failure and toxic combinations
`GET /api/v1/graph/drift`	read	Added / removed / changed resources over a window

Triage & resilience¶

Method & path	Scope	Description
`GET /api/v1/triage/overview`	read	Triage pipeline state
`GET /api/v1/triage/events`	read	Recent triage events (`limit`)
`GET /api/v1/triage/rules`	read	Active triage rules
`GET /api/v1/resilience/status`	read	Resilience engine status
`GET /api/v1/resilience/findings`	read	Hypothetical failure-mode findings

Knowledge & memory¶

Method & path	Scope	Description
`GET /api/v1/learnings`	read	Taught facts (`status=active` default)
`POST /api/v1/learnings`	read_write	Teach a durable fact: `{"fact": str, "service"?}`
`GET /api/v1/reports/morning/latest`	read	The latest Morning Report

Notifications, tools & org¶

Method & path	Scope	Description
`GET /api/v1/notifications`	read	Your in-app notifications (`unread`, `limit`)
`POST /api/v1/notifications/read-all`	read_write	Mark all read
`GET /api/v1/tools/available`	read	Agent tools available to your tenant
`GET /api/v1/marketplace/tools`	read	The integration catalog
`GET /api/v1/marketplace/tenant/tools`	read	Integrations installed for your tenant
`GET /api/v1/runbooks`	read	Tenant runbooks
`GET /api/v1/team`	read	Team members and roles
`GET /api/v1/audit`	read	Organization audit log (`limit`)
`GET /api/v1/audit/verify`	read	Verify the audit log's hash-chain integrity

CI¶

Method & path	Scope	Description
`POST /api/v1/plan-review`	read_write	Review a Terraform plan: `{"plan": str}` → risk-ranked annotations. See Plan review

Tokens¶

Method & path	Scope	Description
`GET /api/v1/tokens`	read	List this user's tokens (metadata only — never the secret) → `{"tokens": [...]}`
`DELETE /api/v1/tokens/{id}`	read_write	Revoke a token (a token may revoke itself)

Token creation is deliberately absent: minting requires an interactive browser session — see Authentication.

Conventions¶

Errors: {"detail": "..."} with a conventional status code (401/403/404/429).
Timestamps: UTC, ISO-8601.
Tenancy: every response is scoped to the token's tenant; there is no parameter that changes that.