HTTP API

All error responses use { "error": { "code": string, "message": string, "requestId": string, "details"?: unknown } } unless a separately deployed service documents otherwise. The same correlation ID is returned in x-request-id. Production omits private diagnostic causes; non-production may include the cause under details.

Server health and runs

Method	Path	Result
GET	/health	{ "status": "ok" }
GET	/ready	{ "status": "ready" }, or HTTP 503 with degraded workspace issues
POST	/api/runs	Execute { flowPath, input?, authorizationToken?, sessionId? } synchronously
POST	/api/runs/async	Add debug?, callbackUrl?, and interactionRequest?; returns 202 and location
GET	/api/runs/:id	Public durable run; 202 while active, 200 terminal, 404 missing
POST	/api/runs/:id/continue	Advance a paused debug run
POST	/api/runs/:id/cancel	Cancel queued, active, paused, or suspended work

flowPath is relative to WORKSPACE_ROOT/workflows; traversal outside it returns a stable boundary error. A public run includes timestamps, result/error, continuation, callback delivery state, node states, and status URL.

Async debug runs move in paused/running transitions and only advance after POST /api/runs/:id/continue.

Webhooks

Method	Path	Result
GET	/api/webhooks	Manifest-derived webhook descriptors
GET	/api/webhooks/:id/workflow	Return the workflow graph
GET	/api/webhooks/:id/runs	Active runs for that workflow
POST	/api/webhooks/:id	Manifest-selected sync or async execution
POST	/api/webhooks/:id/async	Optional additional async endpoint

Request shape is manifest-specific JSON or multipart form data. Async acceptance returns { runId, status, statusUrl } with 202 and Location.

Example multipart request:

POST /api/webhooks/book-document HTTP/1.1
Authorization: Bearer <application-api-key>
Content-Type: multipart/form-data; boundary=----faimulus

------faimulus
Content-Disposition: form-data; name="prompt"

Summarize the attached files.
------faimulus
Content-Disposition: form-data; name="attachments"; filename="report.pdf"
Content-Type: application/pdf

<binary bytes>
------faimulus--

Async webhook interactions default to public and non-broadcasted. Poll statusUrl; a suspended run includes interactionRequest with its request ID, questions, private, broadcasted, and creation time. Set X-Faimulus-Interaction-Private or X-Faimulus-Interaction-Broadcasted to the literal true or false to override those defaults.

Webhook execution calls require Authorization: Bearer <api-key>. The server reads APPLICATION_API_KEY at startup. The corresponding application principal has access to every declared workflow capability.

Manual workflow authorization

Method	Path	Result
GET	/api/workflows/:id/authorization/preview	Trusted proxy principal and capabilities entitled for the workflow
POST	/api/workflows/:id/authorization	Exchange { capabilityIds } for a five-minute, single-use launch token

The authorization exchange requires a principal from TRUSTED_IDENTITY_HEADER and rejects capability IDs outside that principal's grants. Pass the returned token as authorizationToken to POST /api/runs or POST /api/runs/async; it is bound to the workflow and principal.

Authorization registry

Method	Path	Result
GET	/api/authorization/principals	Principal IDs and their configured grants
PUT	/api/authorization/principals/:id/grants	Replace a principal's grants with { grants }
GET	/api/authorization/api-keys	Fixed API-key metadata including principal ID and env var name

Schedules and interaction requests

Method	Path	Result
GET	/api/scheduled-workflows	Scheduling-eligible descriptors
GET	/api/schedules	All schedules
GET	/api/schedules/:id	One schedule
POST	/api/schedules	Create a one-time or interval schedule; 201
PATCH	/api/schedules/:id	Update enabled state, input, or cadence fields accepted by the route
DELETE	/api/schedules/:id	Delete; 204
GET	/api/interaction-requests?status=pending	Pending non-private requests
GET	/api/interaction-requests/:id	One pending request
POST	/api/interaction-requests/:id/resolve	Resolve with { response } and continue the run

POST /api/runs/async, schedule creation, and schedule updates accept interactionRequest: { private, broadcasted }. Direct runs default both fields to false; schedules default to { private: false, broadcasted: true }. Add withPrivate=true to the pending-list query to include private requests. Add broadcasted=true to return only broadcasted requests; both filters can be combined.

MCP toolset registry

Method	Path	Result
GET	/api/toolsets	Configured HTTP MCP records loaded from config/toolsets.yaml
GET	/api/toolsets/:name/tools	Discover remote tools for one configured toolset with host policy

Records identify a streamable HTTP endpoint and optional authorization-token environment variable. Toolsets are loaded once at startup from workspace config. Secrets are resolved only while constructing an execution catalog or performing read-only tool discovery.

Authenticated channel integration

These server routes require Authorization: Bearer <integration secret> for the :channelId registry entry.

Method	Path	Result
GET	/api/channel-integrations/:channelId/workflows	Available workflow descriptors
POST	/api/channel-integrations/:channelId/runs	Enqueue a channel-correlated run; 202
POST	/api/channel-integrations/:channelId/interaction-requests/:requestId/resolve	Resolve a request scoped to an instance

Run submissions contain workflowId, channelInstanceId, messageId, input, and optional interactionRequest. Channel interactions always return to their originating channel and default to { private: true, broadcasted: false }. The server fixes the callback URL from its registry and derives idempotency from instance/message identity.

Channel management API

These routes are served by the Faimulus server and require an admin session when admin authentication is configured.

Method	Path	Result
GET	/api/channels/host/drivers	Driver schemas and actions
GET / POST	/api/channels/host/instances	List or create instances
GET / PUT / DELETE	/api/channels/host/instances/:id	Read, replace configuration, or remove
POST	/api/channels/host/instances/:id/actions/:action	Execute a driver action with optional input
GET	/api/channels/host/workflows	Workflow descriptors available to channel instances
POST	/api/channels/host/instances/:id/messages	Send { requestId, target, message }; returns 202
POST	/api/channels/host/callbacks	Signed completion/interaction-request callback; returns 204

Channel workflow completions are normally delivered in-process. The callback endpoint requires X-Faimulus-Signature: sha256=<hex> over the exact JSON body.

Memories

Method	Path	Result
GET	/api/memory/drivers	Registered memory driver descriptors and JSON schemas
GET	/api/memories	Immutable startup memory definitions from config/memories.yaml
GET	/api/memories/:name/content	Driver-backed named memory content for supported memory definitions

There are no memory mutation endpoints.

Workflow calls through POST /api/runs and POST /api/runs/async accept an optional sessionId. Webhook endpoints accept the same value in x-session-id.