Reference
API reference
One REST API plus a live event stream — everything DirectStudio does, your scripts can do.
Basics
Base URL: https://api.directos.dev/api. Requests and responses are JSON; workflow definitions are validated before they are saved, so a malformed definition is rejected with a clear error instead of failing at run time.
Authenticate with authorization: Bearer <token> — either a session token from POST /auth/login or a personal API key from POST /auth/api-keys (see the Quickstart). Each route needs a minimum role: viewer < editor < admin. A missing or expired token gets 401, too low a role gets 403.
Auth
| Endpoint | Role | Description |
|---|---|---|
POST /auth/login | public | Email + password → a 30-day session token. |
POST /auth/logout | any role | Revoke the session behind the current token. |
GET /auth/me | any role | The signed-in user and role. |
POST /auth/api-keys | any role | Mint a personal API key — the token is returned once. |
GET /auth/api-keys | any role | List your API keys (no secrets). |
DELETE /auth/api-keys/:id | any role | Revoke one of your API keys. |
GET /auth/users | admin | List accounts. |
POST /auth/users | admin | Create an account with a role. |
PATCH /auth/users/:id/role | admin | Change an account's role. |
DELETE /auth/users/:id | admin | Delete an account. |
GET /audit | admin | Audit trail of user, API-key and credential actions. |
Workflows
| Endpoint | Role | Description |
|---|---|---|
GET /workflows | any role | List workflow summaries. |
POST /workflows | editor | Create a workflow (name + definition). |
GET /workflows/:id | any role | One workflow with its definition. |
PUT /workflows/:id | editor | Update name, description, definition or the active flag — every definition change is saved as a new version. |
DELETE /workflows/:id | editor | Delete a workflow. |
POST /workflows/:id/run | editor | Start an execution; body { "input": … }. Returns { executionId } immediately. |
GET /workflows/:id/versions | any role | Version history. |
GET /workflows/:id/versions/:version | any role | One past version. |
POST /workflows/:id/versions/:version/restore | editor | Roll back to a version. |
Executions
| Endpoint | Role | Description |
|---|---|---|
GET /executions | any role | Recent executions; filter with ?workflowId=. |
GET /executions/:id | any role | Status, timing, per-node results and output. |
POST /executions/:id/cancel | editor | Abort a running execution. |
GET /executions/:id/pending-approvals | any role | Approval nodes currently waiting for a decision. |
POST /executions/:id/nodes/:nodeId/resume | editor | Approve or reject a paused approval node — { "approved": true, "note"? }. |
Webhooks & nodes
| Endpoint | Role | Description |
|---|---|---|
POST /hooks/:path | public | Starts every active workflow whose webhook trigger listens on the path. |
GET /node-types | any role | The node catalog — palette entries and parameter forms. |
POST /node-types/test | editor | Dry-run a single node against a sample input. |
Agents
| Endpoint | Role | Description |
|---|---|---|
GET /agents | any role | List agents. |
POST /agents | editor | Create an agent — model, instructions, tools. |
GET /agents/:id | any role | One agent. |
PUT /agents/:id | editor | Update an agent. |
DELETE /agents/:id | editor | Delete an agent. |
POST /agents/:id/run | editor | Run the agent loop to completion and return the result. |
GET /agents/tools | any role | Node types an agent may use as tools. |
GET /agents/runs | any role | Run history; filter with ?agentId=. |
GET /agents/runs/:id | any role | One run, including delegated sub-runs. |
GET /agents/:id/inbox | any role | An agent's message mailbox. |
POST /agents/:id/messages | editor | Leave a message for an agent. |
Memory & knowledge bases
| Endpoint | Role | Description |
|---|---|---|
POST /memory/:namespace/remember | editor | Embed and store a memory item. |
GET /memory/:namespace/recall | any role | Semantic search — ?q=&limit= |
POST /memory/:namespace/summarize | editor | Compact a long namespace now. |
POST /rag/:namespace/ingest | editor | Parse, chunk, embed and store a document. |
GET /rag/:namespace/query | any role | Hybrid search with cited chunks — ?q=&limit= |
GET /rag/:namespace/documents | any role | Documents in a knowledge base. |
Usage & operations
| Endpoint | Role | Description |
|---|---|---|
GET /stats/usage | any role | Cost, tokens and calls by model, provider and day. |
GET /gateway/calls | any role | Recent LLM gateway calls. |
GET /gateway/cost-by-project | any role | Gateway spend per client project. |
GET /benchmarks/runs | any role | Past model benchmark runs. |
POST /benchmarks/run | editor | Benchmark models on latency, cost and success. |
GET /credentials | admin | Stored credentials — names and types, never secrets. |
POST /credentials | admin | Store a credential, encrypted at rest. |
DELETE /credentials/:id | admin | Delete a credential. |
GET /health | public | Liveness probe. |
Run a workflow from a script
# start a run with input
curl -X POST https://api.directos.dev/api/workflows/<workflow-id>/run \
-H "authorization: Bearer $DIRECTOS_KEY" \
-H 'content-type: application/json' \
-d '{"input": {"customerId": 42}}'
# → {"executionId": "<execution-id>"}
# poll the result
curl https://api.directos.dev/api/executions/<execution-id> \
-H "authorization: Bearer $DIRECTOS_KEY"
A workflow’s id is in its editor URL (/workflows/<id>). Execution status is one of queued, running, success, failed or canceled.
Live events
The API also exposes a socket.io namespace, /events. Each execution streams into the room execution:{id}: execution.started, node.started / finished / failed / skipped / log and execution.finished. This is what DirectStudio’s live node statuses consume — the final snapshot is also persisted, so polling GET /executions/:id works without a socket.