API Reference

Direktor exposes a REST + streaming API that powers the web UI, the MCP adapter, and any third-party integration you want to build.

Base URL

Production: https://api.direktor.tech
Self-hosted: http://localhost:8001 (cto-gui-libvirt-backend)

Authentication

Every request must include one of:

Session cookie — issued by Google OAuth sign-in; used by the web UI.
Bearer JWT — for API access. Mint via /api/auth/api-keys.
Per-node MCP token (of_dkmcp_*) — used by the direktor-mcp when forwarding to /api/org/*.

All endpoints are scoped by the authenticated user’s workspace memberships. Cross-workspace access is rejected with 403.

Key surfaces

Endpoint family	Purpose	Docs
`/api/org/chat/*`	Send a message to a node, stream the response. The main workhorse — every UI chat, MCP `do()`, and channel inbound flows through here.	Org Chat
`/api/org/knowledge/*`	Skill catalog, knowledge-base entries, artifacts.	Org Knowledge
`/api/org-activity/*`	Timeline events, decisions, milestones.	Org Activity
`/api/org/structures/*`	Workspace + node CRUD, org-chart structure.	Org Structures

Rate limits

60 req/min per authenticated user (burst of 10).
do() equivalents (chat endpoints) count as 1 req at entry + 1 req per streamed response regardless of length.
MCP tool calls share the same budget as REST calls from the same user.

Versioning

The current API is versioned in the URL path prefix (/api/... implicit v1). Breaking changes will be shipped under /api/v2/... and both versions will coexist for at least 90 days. Non-breaking additions happen in-place.

Errors

All errors return JSON with:


{
  "error": "<machine-readable code>",
  "message": "<human-readable explanation>",
  "details": { ... }
}

Common codes:

Code	HTTP	Meaning
`unauthenticated`	401	No valid credential.
`forbidden`	403	Authenticated but can’t access this scope.
`not_found`	404	Resource doesn’t exist or you can’t see it.
`validation_error`	422	Input failed schema validation.
`rate_limited`	429	Back off.
`internal_error`	500	Our fault. Check status .