> ## Documentation Index
> Fetch the complete documentation index at: https://milford.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> How runs, events and retries behave over HTTP.

The API reference pages list every endpoint, parameter and status code. They are generated from [`openapi.yaml`](/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

```bash theme={null}
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`.

```json theme={null}
{
  "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](/guides/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.

```bash theme={null}
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"}}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.