ServerFlows
API Reference
Execution endpoints, replay API, and internal service usage.
Execution API
Flows are exposed via Hono routes in flow.handler.ts.
Execute Flow
POST /api/v1/flows/:id/executeRequest:
{
"event": {
"userId": "user_123",
"action": "signup",
"recordId": "contact_456"
},
"idempotencyKey": "unique-request-id"
}Response:
{
"executionId": "run_abc",
"status": "COMPLETED",
"outputs": {
"result": "..."
},
"duration": 1250
}Get Execution Status
GET /api/v1/executions/:executionIdList Executions
GET /api/v1/flows/:flowId/executionsReplay API
Restart a previous execution from the beginning:
POST /api/v1/executions/:executionId/replayUses the exact same version and initial event data.
Node Debug API
Get detailed node-level information:
GET /api/v1/executions/:executionId/nodes/:nodeIdResponse includes:
- Input variables
- Output results
- Error messages (if failed)
- Execution timestamps
Internal Service Usage
For backend services, use the Effect-TS service directly instead of HTTP:
import { FlowExecutionEngine } from "./flow-execution.engine";
const program = Effect.flatMap(
FlowExecutionEngine,
engine => engine.execute({
flowId: "flow_123",
event: { userId: "user_456" },
})
);
const result = await Effect.runPromise(
program.pipe(Effect.provide(FlowExecutionEngineLive))
);Execute with Context
const result = await Effect.runPromise(
FlowExecutionEngine.execute({
flowId: "flow_123",
event: {
recordId: "contact_789",
action: "created"
},
context: {
orgId: "org_abc",
userId: "user_123",
},
}).pipe(Effect.provide(FlowExecutionEngineLive))
);Error Responses
| Code | Description |
|---|---|
| 404 | Flow not found |
| 409 | Idempotency key conflict |
| 422 | Flow not active |
| 429 | Rate limit exceeded |
| 500 | Engine error |