Using the API Server

Kerf includes a FastAPI server for running workflows over HTTP.

Start the server

kerf serve

Custom host and port:

kerf serve --host 127.0.0.1 --port 3000

Execute a workflow

curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_name": "summarize",
    "input_data": "Your text here...",
    "fallback_enabled": true
  }'

Response:

{
  "summary": "..."
}

Request format

Field	Type	Required	Description
workflow_name	string	yes	Name of the workflow (matches workflows/<name>.json)
input_data	string	yes	Input text to process
fallback_enabled	boolean	no	Enable fallback policies (default: true)

Error handling

If the workflow doesn't exist, you get a 404:

{
  "detail": "Workflow 'nonexistent' not found at workflows/nonexistent.json"
}

When to use the server vs CLI

Use kerf serve when you want to call workflows from other services, integrate with existing APIs, or run workflows from non-Python code. Use kerf run for scripting, testing, and one-off executions.

Both call the same engine. Results are identical.