API Reference
Everything the CLI and the console do goes through this API. Endpoints are prefixed with /api, return a JSON array of typed chunks, and can stream that array incrementally on request.
Collections
| Name | Path |
|---|---|
| Auth | /api/auth/ |
| Engine | /api/engine/ |
| Shell | /api/shell/ |
| Runtime | /api/runtime/ |
| Workflow | /api/workflow/ |
| Agent | /api/agent/session/ |
| Artifact | /api/artifact/ |
Authentication
Endpoints fall into three tiers. Each page states its own requirement under Auth and Notes.
| Tier | Requires | Endpoints |
|---|---|---|
| Public | Rate limiting only | Engine healthcheck and lookup, the auth challenge / verify / pair-request endpoints, and the presigned artifact share endpoints |
| Token | Authorization: Bearer <jwt> | Most reads and mutations — artifacts, workflows, shells, monitoring |
| Permission | A JWT carrying a specific permission | Key management, engine restart, historical statistics, and other administrative calls |
Permissions
A JWT carries the permissions of the key that signed in, or of the pairing session that issued it.
Functional (combinable): SHELL, ARTIFACT, WORKFLOW, RUNTIME, AGENT
Modifiers: READ_ONLY blocks create, modify, and delete; MASTER grants full administrative access, including key management and engine restart.
Getting a token
RSA challenge/response — request a nonce, sign it with your private key, exchange the signature for a JWT:
# 1. Request a challenge
curl "http://localhost/api/auth/challenge/"
# 2. Sign it and exchange the signature for a token
curl -X POST "http://localhost/api/auth/verify/" \
-H "Content-Type: application/json" \
-d '{"identity":"your-key-id", "signature":"signed-challenge", "lifetime":"1h"}'
# Use it
curl -H "Authorization: Bearer $TOKEN" "http://localhost/api/engine/ping/"
# Check it is still valid
curl -H "Authorization: Bearer $TOKEN" "http://localhost/api/auth/inspect/"
dxflow engine token prints one directly on the engine host, and dxflow engine pair issues a single-use code for a browser.
Response format
Every response is a JSON array of chunks. A status chunk is always first, an optional total chunk follows, and entity chunks carry the data:
[
{ "kind": "status", "payload": { "code": 200, "message": "OK" } },
{ "kind": "total", "payload": { "value": 150 } },
{ "kind": "entity", "payload": { "id": "item-1", "name": "example" } }
]
Errors use the same shape, with the code and message on the status chunk.
?stream=true (or Accept: application/stream+json) and the same array arrives chunk by chunk as results are produced. See Streaming for chunk kinds and when it is worth using.Quick examples
# Health check — rate-limited, no token needed
curl "http://localhost/api/engine/healthcheck/"
# List files
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost/api/artifact/?directory=/home"
# Stream workflow logs
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost/api/workflow/logs/?identity=my-app&stream=true"