API Overview

API Overview

flow8 provides a comprehensive REST API for all platform operations.

Base URL

http://your-host:4454/api/

All endpoints return application/json. All request bodies must be Content-Type: application/json.

Authentication

Two methods are supported:

Session cookie (for browser clients):

curl -c cookies.txt -X POST http://host:4454/api/auth/login \
  -d '{"email":"user@example.com","password":"password"}'
# Use cookies.txt in subsequent requests with -b cookies.txt

API key (for programmatic access):

curl -H "Authorization: Bearer eyJ..." http://host:4454/api/flows

See the Authentication page for creating and managing API keys.

Pagination

List endpoints support pagination via query parameters:

GET /api/flows?page=0&size=25

Parameter	Default	Max	Description
page	0	—	Zero-based page number
size	25	100	Items per page

Response includes pagination metadata:

{
  "data": [...],
  "total": 142,
  "page": 0,
  "size": 25,
  "pages": 6
}

Error Format

{
  "error": "FLOW_NOT_FOUND",
  "message": "Flow with ID 65abc123 not found",
  "statusCode": 404
}

Common error codes: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, INTERNAL_ERROR.

Endpoint Index

Authentication

Method	Path	Description
POST	/api/auth/login	Session login
POST	/api/auth/logout	End session
GET	/api/auth/me	Current user info
POST	/api/auth/api-keys	Create API key
GET	/api/auth/api-keys	List API keys
DELETE	/api/auth/api-keys/:id	Revoke API key

Flows

Method	Path	Description
GET	/api/flows	List flows
POST	/api/flows	Create flow
GET	/api/flows/:id	Get flow
PUT	/api/flows/:id	Update flow
DELETE	/api/flows/:id	Delete flow
POST	/api/flows/:id/run	Trigger execution
GET	/api/flows/:id/layers	List flowlets
POST	/api/flows/:id/layers	Add flowlet
PUT	/api/flows/:id/layers/:layerId	Update flowlet
DELETE	/api/flows/:id/layers/:layerId	Delete flowlet

Executions (Plays)

Method	Path	Description
GET	/api/plays	List all plays
GET	/api/plays/:id	Get play detail
GET	/api/plays/:id/layers	Get play layer results
POST	/api/plays/:id/approve	Approve a pending step
DELETE	/api/plays/:id	Cancel a running play

Groups

Method	Path	Description
GET	/api/groups	List groups
POST	/api/groups	Create group
PUT	/api/groups/:id	Update group
DELETE	/api/groups/:id	Delete group

KV Store

Method	Path	Description
GET	/api/kv	List KV entries
POST	/api/kv	Set KV value
DELETE	/api/kv/:id	Delete KV entry

Channels

Method	Path	Description
GET	/api/channels	List channels
POST	/api/channels	Create channel
GET	/api/channels/:id	Get channel
PUT	/api/channels/:id	Update channel
DELETE	/api/channels/:id	Delete channel

Schedules

Method	Path	Description
GET	/api/schedules	List schedules
POST	/api/schedules	Create schedule
PUT	/api/schedules/:id	Update schedule
DELETE	/api/schedules/:id	Delete schedule

WebSocket

Protocol	Path	Description
WS	/api/ws	Real-time execution events