API Reference
Developer / API Reference

API Reference

Base URL: https://api.flow.iai.one — Tất cả endpoints yêu cầu session cookie trừ /api/auth/login.

Auth

POST/api/auth/loginLogin with email + password
GET/api/auth/sessionGet current session + user
DELETE/api/auth/sessionLogout (invalidate session)

Flows

GET/api/flowsList flows in workspace → {items:[]}
POST/api/flowsCreate new flow
GET/api/workflows/:idGet flow by ID
PUT/api/workflows/:idUpdate flow
DELETE/api/workflows/:idDelete flow
POST/api/workflows/:id/runTrigger a run of this flow
Flow object
{
  "id": "wf_abc123",
  "name": "My Flow",
  "status": "active",           // draft | active | archived
  "version": 1,
  "workspace_id": "ws_xyz",
  "definition_json": "{...}",   // WorkflowDefinition JSON string
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Runs

GET/api/runsList runs. Query: ?limit=50&status=success
POST/api/runsCreate run record manually
GET/api/runs/:idGet run by ID
GET/api/runs/:id/stepsGet step logs for a run
GET/api/dashboard/runs/latestLatest 8 runs for dashboard → {items:[]}
Run object
{
  "id": "run_abc123",
  "workflow_id": "wf_abc123",
  "workflow_name": "My Flow",
  "status": "success",          // running | success | failed | pending
  "triggered_by": "manual",     // manual | schedule | webhook
  "duration_ms": 1240,
  "started_at": "2026-01-01T00:00:00Z",
  "finished_at": "2026-01-01T00:00:01Z",
  "output": { ... },
  "error_text": null
}

Logs

GET/api/logsList logs. Query: ?run_id=&limit=
POST/api/logsWrite a log entry
GET/api/logs/:runIdGet all logs for a run

Nodes

GET/api/nodesGet node catalog. Query: ?search=&category=

Agents

GET/api/agentsList agent definitions in catalog
POST/api/agent/runRun an agent task
GET/api/agent/logsGet agent run logs. Query: ?agent_id=
GET/api/agent/memoryGet agent memory entries
POST/api/agent/memoryWrite agent memory

Templates

GET/api/templatesList official workflow templates

Metrics

GET/api/metricsGet runtime metrics (total_runs, success_runs, last_run_at)

Health

GET/api/healthHealth check. No auth required.
{ "ok": true, "ts": "2026-01-01T00:00:00Z" }

Error Responses

StatusMeaning
400Bad Request — missing or invalid fields
401Unauthorized — no valid session cookie
403Forbidden — workspace membership mismatch
404Not Found
500Internal Server Error
 
{ "error": "Human-readable error message" }