HTTP API

The API reference pages list every endpoint, parameter and status code. They are generated from openapi.yaml. This page covers behavior that the reference does not show well. Every /v1 endpoint requires Authorization: Bearer <token> when server.auth.tokens is set. /health needs no token.

Run a flow

curl -s localhost:8080/v1/flows/triage/run \
  -H "authorization: Bearer $MILFORD_TOKEN" \
  -d '{"input": {"text": "My invoice is wrong"}}'

The response is 200 with the run result, even when a node failed. Check ok.

{
  "ok": true,
  "runId": "5c1f...",
  "nodes": { "team": { "status": "done", "ms": 212.4, "result": { "success": true, "output": "billing", "data": { "choice": "billing", "confidence": 0.93 } } } },
  "output": { "success": true, "output": "Route to billing." }
}

nodes is the trace: status (done, error or skipped), timing and result for each node, including decision probabilities.

Idempotency

Send an Idempotency-Key header to make retries safe. A retry with the same key and input returns the first successful result with Idempotent-Replayed: true and does not run the flow again. See enterprise integration for the limits.

Server-sent events

Send Accept: text/event-stream to receive events as they happen. Each event name matches its type: node:start, node:done, node:error, node:skipped, provider:call. The last event is result, which holds the run result. If the server is busy, the stream ends with a result event that carries an error, because the HTTP status is already sent. Closing the connection cancels the run.

curl -N localhost:8080/v1/flows/triage/run \
  -H "authorization: Bearer $MILFORD_TOKEN" -H "accept: text/event-stream" \
  -d '{"input": {"text": "My invoice is wrong"}}'

Get started

Concepts

Building blocks

Guides

Reference

API reference

Run a flow

Idempotency

Server-sent events

​Run a flow

​Idempotency

​Server-sent events

Run a flow

Idempotency

Server-sent events