HTTP API
The relay serves the API when api.enable is true, at http://127.0.0.1:4480/api/v1 unless api.bind says otherwise. Its settings are the api keys of the configuration file. Builds without the observability Cargo feature have no API.
Every path starts with /api/v1. Responses are JSON unless an endpoint says otherwise.
Features
Each endpoint belongs to a feature, and api.features lists the features that run.
| Feature | On by default | Serves |
|---|---|---|
health | yes | The endpoint index, liveness, readiness and meta |
state | yes | Snapshots of the relay: configuration, connections, tracks, namespaces |
metrics | yes | Prometheus metrics |
latency | yes | Object processing time and the slowlog |
qlog | yes | The qlog trace files, when qlog_folder is set |
events | no | A live stream of qlog events |
actions | no | Endpoints that change the running relay. Needs write_token. |
mcp | no | The MCP server for AI agents. Needs mcp_token_hash. |
An endpoint whose feature is off answers 404 with the error feature_off.
Endpoints
Paths are relative to /api/v1. {conn_id} and {track_id} are the numeric ids the list endpoints return. The connection and track lists are at most one second old.
health
| Method | Path | Returns |
|---|---|---|
| GET | / | The relay's version, the features that run, and every endpoint with its method, path, feature and whether it is enabled |
| GET | /health | {"status": "ok"} while the process answers, also while it drains |
| GET | /ready | {"ready": true}, or 503 with "reason": "starting" before the QUIC listeners accept and "draining" while it drains |
| GET | /meta | api.meta as written |
state
| Method | Path | Returns |
|---|---|---|
| GET | /config | The settings the relay runs on, without the tokens |
| GET | /overview | Version, process id, start time, connections by state, track, subscription and cached group counts, request results, and traffic totals when metrics is on |
| GET | /connections | A page of open connections, or of closed ones with closed=true |
| GET | /connections/{conn_id} | One open or recently closed connection: SETUP options, namespaces, tracks, subscriptions, QUIC statistics, close reason |
| GET | /tracks | A page of tracks with their publishers, subscriber count, cached groups and processing time |
| GET | /tracks/{track_id} | One track with every subscription to it and the groups in its cache |
| GET | /namespaces | Each announced namespace with the connections announcing it, and the namespace subscriptions the relay holds |
| GET | /upstreams | The open publishers and cluster peers the relay can request from, with round-trip time and request results |
| GET | /zones | Traffic and request results per api.accounting_zones prefix, then unzoned. Empty without zones. |
| GET | /cluster | The relay's mesh identity, its links to peers, and what it advertises to each |
metrics
| Method | Path | Returns |
|---|---|---|
| GET | /metrics | Every counter in the Prometheus text format, text/plain; version=0.0.4. filter keeps the metrics whose name contains it. |
Per-connection and per-track numbers are not metrics. They are in /connections and /tracks.
latency
| Method | Path | Returns |
|---|---|---|
| GET | /latency | Percentiles in milliseconds of each processing stage (ingest, queue, write, total) and of time to first object, with the slowest tracks and subscriptions. window is 10s, 60s (default), 5m or start. |
| GET | /latency/slow | The slowlog, newest first, with its two thresholds |
qlog
| Method | Path | Returns |
|---|---|---|
| GET | /qlog | The trace files in qlog_folder, newest first, with their connection, kind, size and whether they still grow |
| GET | /qlog/{conn_id} | The connection's MoQT trace |
| GET | /qlog/{conn_id}/quic | The connection's QUIC packet trace. Only debug builds of the relay write one. |
A trace comes as JSON-SEQ, application/qlog+json-seq. A request whose Accept names application/json or application/qlog+json gets one JSON document instead. On /qlog/{conn_id}, since keeps the events at or after a time in milliseconds since the Unix epoch, and follow=true keeps the response open and sends each new event until the connection closes. follow only streams JSON-SEQ.
Without qlog_folder, these endpoints answer 409 qlog_off.
events
| Method | Path | Returns |
|---|---|---|
| GET | /events | Every connection's qlog events as they happen, as Server-Sent Events |
| Event | Data |
|---|---|
qlog | The qlog event, with conn_id added as its first field |
closed | {"conn_id": …} when a connection closes |
lagged | {"missed": …}, the events a listener that fell behind lost |
conn keeps one connection's events, and name the events whose name starts with it, such as moqt:control_message. Without qlog_folder, the relay builds events only while someone listens.
actions
Every endpoint here needs the write token, and the relay logs each change with the address that asked for it.
| Method | Path | Body | Does |
|---|---|---|---|
| DELETE | /connections/{conn_id} | Closes the connection at once. 204. | |
| POST | /connections/{conn_id}/goaway | Sends the client GOAWAY, and closes the connection if it is still open after timeout_ms. 202. | |
| POST | /drain | Refuses new requests and sends every client GOAWAY, closing those still open after timeout_ms. Answers {"told": …, "timeout_ms": …}. Lasts until the relay restarts. | |
| GET | /config/redirect_uri | {"uri": …}, the URI GOAWAY sends clients to | |
| PUT | /config/redirect_uri | {"uri": "moqt://…"} | Replaces it. null or "" sends none. At most 8192 bytes. |
| GET | /logging | {"filter": …}, the current log filter | |
| PUT | /logging | {"filter": "info,relay=debug"} | Replaces the log filter, written as for RUST_LOG |
timeout_ms is a query parameter: 10000 when left out, at most 600000.
mcp
| Method | Path | Serves |
|---|---|---|
| POST | /mcp | The MCP server, over the Streamable HTTP transport. See MCP tools. |
List parameters
/connections and /tracks return one page:
{ "total": 42, "offset": 0, "limit": 100, "items": [] }| Parameter | Description |
|---|---|
sort | A sort key. A leading - sorts in descending order: sort=-bytes_out. |
limit | Items per page. 100 when left out, at most 1000. |
offset | Items to skip. 0 when left out. |
prefix | Only entries in a namespace that starts with this text. Namespaces are written with their fields joined by -, such as moqtail-ch07. A connection matches when it announces, publishes or subscribes to something there. |
closed | /connections only. true lists the recently closed connections, up to api.closed_connection_history. |
| Endpoint | Sort keys |
|---|---|
/connections | conn_id, connected_at, rtt, bytes_out, bytes_in, lost_packets, subscriptions |
/tracks | track_id, subscribers, publishers, cached_groups |
Authorization
Every request passes two checks before it reaches an endpoint: the client's address, then its token.
Address
On a loopback api.bind, every client is allowed. On a network address, the client's IP has to be in api.allow, or the request gets 403 address_not_allowed. api.metrics_bind is checked against the same list. An IPv4 client on an IPv6 socket is matched as IPv4.
Tokens
A token goes in the Authorization header: Authorization: Bearer <token>. A token set to "" counts as unset.
| Request | Accepted tokens |
|---|---|
GET /health, /ready, /meta | None needed, ever |
Other GET and HEAD | Open without read_token. With it, read_token or write_token. |
GET /metrics | As other reads, and also metrics_token. With metrics_token set and no read_token, the metrics need a token while other reads stay open. |
POST, PUT, DELETE | write_token |
/mcp | Only the MCP token, the one mcp_token_hash was made from. No other token works there, and it works nowhere else. |
A request without a needed token gets 401 token_required, and one with a wrong token 403 token_rejected. The tokens apply on the metrics listener too.
Browsers
A request whose Origin is in api.cors_origins gets CORS headers, and its preflight OPTIONS gets 204. A preflight from any other origin gets 403.
/mcp refuses any request that has an Origin not in api.cors_origins, with 403 origin_not_allowed. On a loopback api.bind, it also needs a Host of localhost, 127.0.0.1 or ::1. Both guard against DNS rebinding.
Errors
An error answers with a status and a JSON body: a stable error code, and often a detail sentence that says what to change.
{ "error": "feature_off", "detail": "add `actions` to api.features to turn this endpoint on" }| Status | error |
|---|---|
| 400 | bad_query, unknown_sort_key, unknown_window, bad_body, bad_filter |
| 401 | token_required |
| 403 | address_not_allowed, origin_not_allowed, token_rejected |
| 404 | not_found, feature_off, unknown_connection, unknown_track, no_trace |
| 406 | follow_needs_json_seq: follow asked for with Accept: application/json |
| 409 | qlog_off, events_off |
| 500 | qlog_unreadable |
Startup refusals
With api.enable set, the relay refuses to start, and exits with code 1 and the reason, when:
| Setting | Refused when |
|---|---|
features | It names a feature that does not exist |
features | It has actions and write_token is not set |
features | It has mcp and mcp_token_hash is not set |
mcp_token_hash | It is not a sha256d$<salt>$<digest> line as relay api-token prints it |
allow | An entry is neither an IP address nor a range, such as 10.0.0.0/8, with a prefix length its family allows |
allow | It is empty, and bind or metrics_bind is a network address |
allow | An entry with prefix length 0, such as 0.0.0.0/0 or ::/0, opens a network bind with no read_token, or a network metrics_bind with neither read_token nor metrics_token |
latency_detail | It is not relay, track or subscription |
metrics_resource_id | metrics_track_enable is on and the id is not 16 lowercase hexadecimal characters |
bind, metrics_bind | The address cannot be bound, for example because the port is in use |
The relay starts, with a warning in its log, when:
allowlists other ranges than loopback, butbindis a loopback address, whereallowis ignored.bindis a network address andallowis left at loopback only, so remote clients get 403.bindis a network address with noread_token, so the ranges inallowread without a token.mcp_writeis on without theactionsfeature, where it has no effect.
MCP tools
The MCP server offers a tool only when its feature is on. The write tools also need api.mcp_write. A tool with a limit returns 50 items when it is left out.
| Tool | Feature | Arguments | Returns |
|---|---|---|---|
relay_overview | state | What /overview returns | |
list_connections | state | closed, sort, limit (max 100), offset, prefix | A page of connections, as /connections |
get_connection | state | conn_id | One connection in full |
connection_timeline | qlog, with qlog_folder set | conn_id, limit (max 200) | The control messages a connection exchanged, each request with its responses, stream resets, parse errors and the close |
list_tracks | state | sort, limit (max 100), offset, prefix | A page of tracks, as /tracks |
get_track | state | track_id | One track with its subscriptions and cache |
namespaces | state | What /namespaces returns | |
upstreams | state | What /upstreams returns | |
zones | state | What /zones returns | |
cluster | state | What /cluster returns | |
latency_report | latency | window | What /latency returns |
slowlog | latency | limit (max 100) | The newest slowlog entries |
send_goaway | actions, write | conn_id, timeout_ms | Sends one client GOAWAY, as POST /connections/{conn_id}/goaway |
close_connection | actions, write | conn_id | Closes one connection at once |
drain_relay | actions, write | timeout_ms | Drains the relay, as POST /drain |
set_log_filter | actions, write | filter | Replaces the log filter |
set_redirect_uri | actions, write | uri | Replaces the GOAWAY redirect URI |
A failed call returns a tool error with the reason, which the agent can read and act on.