API Reference
Complete REST API reference for the dxflow engine with endpoints, authentication, and integration examples
dxflow provides a comprehensive REST API with consistent response formats and automatic streaming optimization.
Modern REST API: All endpoints are prefixed with
/api and follow RESTful design with chunked responses and automatic streaming for performance.Authentication
dxflow uses a three-tier authentication system based on endpoint security requirements:
Public Access
Rate-Limited Only
No authentication required, only rate limiting applied:
- Engine health checks
- Authentication challenge/verify endpoints
- Public file proxy access
Standard Access
JWT Token Required
Bearer token authentication for most operations:
- File system operations
- Workflow management
- System monitoring
- Network services
Permission-Based Access
JWT Token + Specific Permissions
Operations requiring granular permission control:
- Administrative functions
- Resource-specific operations
- Service management
- System configuration
API Permissions
Each JWT token includes specific permissions that control access to different API endpoints:
| Permission | Scope | Description |
|---|---|---|
| MASTER | Administrative | Engine config, key management, restart, file system management |
| WORKFLOW | Container Operations | Docker compose, logs, container lifecycle |
| RUNTIME | Container Runtimes | Docker, Podman, Singularity, and Apptainer images, containers, and instances |
| BRIDGE | Network Connectivity | Tunnel management, port forwarding |
| PROXY | HTTP Services | Forward/reverse proxy, load balancing |
| SHELL | Shell Access | Shell session creation and management |
| ARTIFACT | File Operations | File upload, download, directory listing |
| READ_ONLY | Limited Access | Read-only operations across all endpoints |
Advanced Authentication: See Authentication & Authorization for detailed permission management, key registration, and security configuration.
Authentication Flow
Standard RSA challenge/response authentication:
# 1. Request authentication challenge
curl "http://localhost/api/auth/challenge/"
# 2. Sign challenge with private key and verify
curl -X POST "http://localhost/api/auth/verify/" \
-H "Content-Type: application/json" \
-d '{"identity":"your-key-id", "signature":"signed-challenge", "lifetime":"1h"}'
# Returns JWT token for subsequent requests
Include JWT token in Authorization header:
# Standard API calls with JWT token
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
"http://localhost/api/engine/ping/"
# Verify token is still valid
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
"http://localhost/api/auth/inspect/"
Response Format
All responses use consistent chunked structure:
[
{"type": "status", "payload": {"code": 200, "message": "OK"}},
{"type": "total", "payload": 150},
{"type": "entity", "payload": {"id": "item-1", "name": "example"}}
]
Detailed Format: See Streaming for complete response structure, chunk types, and streaming vs buffered behavior.
Quick Examples
# Health check
curl "http://localhost/api/engine/ping"
# List files
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost/api/artifact/?path=/home"
# Stream workflow logs
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost/api/workflow/logs/my-app?stream=true"