API reference — overview

Umbryx exposes a JSON/HTTP API (~640 endpoints across ~90 routers) plus one WebSocket. This page documents the shared mechanics; per-area endpoint lists follow. Everything below is verified against the current implementation.

Base URL and versioning

• Base path: /api. /api/v1/* is transparently rewritten to /api/* by a middleware — both forms work
• Interactive docs: disabled by default; enable with ENABLE_API_DOCS=true (/docs, /redoc, /openapi.json)

Authentication

All /api/* paths require authentication except a small public set (health, auth login/setup/status/refresh/mfa, OIDC flow, webhooks, workstation/service ingest — each protected by its own mechanism).

Accepted credentials:

1. Authorization: Bearer <access-token> (JWT, HS256)
2. Session cookie rt_auth (httpOnly, what the SPA uses)
3. ?token=<stream-token> — accepted only on the two streaming endpoints (job output-stream, AI chat stream); short-lived (≤120 s), blacklisted on logout, method-restricted

Invalid/expired → 401. Global viewer role → 403 on non-GET.

Authorization

• require_admin — platform administrator
• Project endpoints check membership + a permission string via check_pid_access: non-members get 404 (existence not confirmed), members without the permission get 403
• Permission strings and the 11 roles: Access control

Conventions

• Pagination: limit + offset query parameters (caps vary, max 2000); total count in the X-Total-Count response header
• Errors: single shape — {"code": "...", "message": "...", "detail": "...", "details": [...]}; validation failures return 422 with code: "validation_failed"
• ROE gate: out-of-scope targets → 403 roe_violation; approval-required activities → 202 roe_approval_required
• License gate (EE): mutations during wind-down → 402

Streaming

• Job output: GET /api/projects/{pid}/jobs/{job_id}/output-stream (SSE)
• AI chat: POST /api/projects/{pid}/ai/chats/{cid}/stream (SSE)
• Files (reports, exports): streaming responses with Content-Disposition

WebSocket: ws://<host>/ws/{pid} — session-cookie auth, per-user connection caps, per-recipient permission filtering with secret redaction.

Examples (from the test suite)

# login — sets rt_auth cookie
curl -c jar -X POST http://localhost:3000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<password>"}'
# → {"user":{"id":"u...","username":"admin","role":"platform_admin",...}}

# create a project (creator becomes owner)
curl -b jar -X POST http://localhost:3000/api/projects \
  -H 'Content-Type: application/json' \
  -d '{"name":"Engagement","added":"2026-10-09T00:00:00Z","status":"active"}'
# → 201 {"id":"p...","name":"Engagement",...}

# list hosts (paginated)
curl -b jar 'http://localhost:3000/api/hosts?pid=p...&limit=500&offset=0'
# → 200, X-Total-Count: <n>, [ {...host...} ]

# reveal a credential secret (requires credentials.read_secret; audited)
curl -b jar http://localhost:3000/api/creds/crd.../secret
# → {"secret":"...","ttl":30}

Endpoint groups

Group	Prefix	Highlights	Edition
Auth & MFA	/api/auth	login, setup, refresh rotation, MFA, stream tokens	both
OIDC	/api/auth/oidc, /api/orgs/{id}/oidc-providers, /api/system/oidc-providers	SSO flows + provider CRUD	both (plan-gated)
Users/admin	/api/admin	user CRUD, outbound proxy	both
Projects & members	/api/projects	CRUD, members, invitations, teams, transfer, purge	both
Organizations	/api/orgs	orgs, members, teams	both
Hosts & assets	/api/hosts, /api/networks, /api/host-activities	CRUD, bulk, risk scores, burn	both
Credentials	/api/creds, /api/projects/{pid}/secrets	CRUD, reveal, vault	both
Findings & tasks	/api/findings, /api/tasks…	CRUD, candidates, collections	both
Notes/loot/scope/domains	/api/notes, /api/loots, /api/scopes, /api/domains	CRUD + attachments/uploads	both
ROE	/api/projects/{pid}/roe	get/upsert	both
Scans & watch	/api/projects/{pid}/scans, .../watch	nmap/nuclei/cme/httpx/ffuf/donpapi; surface watches	both
Jobs	/api/projects/{pid}/jobs	list/cancel/retry/approve, SSE stream, artifacts; command/output redacted without credentials.read_secret; stream tokens accepted only on streaming endpoints	both
Bulk & pivots	/api/projects/{pid}/bulk-exec, .../pivots	bulk execution, cred validate/matrix, tunnels	both
C2	/api/c2	integrations, sessions, execute, sync, BOFs	both
C2 Ops	/api/infra-v2/c2	listeners, payload generation	both (core router)
Playbooks & automations	/api/playbooks, /api/projects/{pid}/automations, /api/scheduled-playbooks	CRUD, runs, packs, bundles	both
KB/templates/MITRE	/api/kb, /api/finding-templates, /api/snippets, /api/projects/{pid}/mitre|purple	knowledge + coverage	both
Timeline & audit	/api/timeline, /api/audit, /api/admin/audit	events, undo, verify	both
Reports & export	/api/projects/{pid}/report/*, /api/export/*, CSV, imports	PDF/HTML/MD, ZIP, Nessus/Burp/BloodHound	both
Network map & topology	/api/projects/{pid}/network, .../topology	nodes/links/regions, preview/apply, smart build	both
Attack paths	/api/attack-paths, editor endpoints	paths, steps, nodes/edges/branches, versions	both
Search	/api/search, /api/saved-searches	cross-entity search	both
Modules & plugins	/api/modules, /api/plugins, /api/admin/modules	toggles, objects, upload/sign	both
Workstations	/api/workstations	CRUD, pool, provisioning (EE), executor, actions	both (provisioning EE)
Sync & webhooks	/api/sync, /api/webhooks/{token}	instance sync, C2 ingest	both
AI	/api/ai, /api/projects/{pid}/ai	providers, chats, SSE, audit	both
Firewall & deconfliction & notifications	per-area	config import, claims, notification config	both
Closure	/api/projects/{pid}/close|archive|decommission-report	closure wizard backend	both
System	/api/system	health, logs, metrics, HA, edition, license	both
Platform Ops	/api/infra-v2	providers, stacks, services, links, credentials, VPN	EE
DNS / SSL	/api/infra-v2/dns, /api/infra-v2/ssl	zones, records, ANetExec certs	EE
Managed instances	/api/instance-templates, /api/managed-instances, /api/instance-credentials	k8s pool, claim/release	EE