Skip to content

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.

FeatureOn by defaultServes
healthyesThe endpoint index, liveness, readiness and meta
stateyesSnapshots of the relay: configuration, connections, tracks, namespaces
metricsyesPrometheus metrics
latencyyesObject processing time and the slowlog
qlogyesThe qlog trace files, when qlog_folder is set
eventsnoA live stream of qlog events
actionsnoEndpoints that change the running relay. Needs write_token.
mcpnoThe 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 ​

MethodPathReturns
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/metaapi.meta as written

state ​

MethodPathReturns
GET/configThe settings the relay runs on, without the tokens
GET/overviewVersion, process id, start time, connections by state, track, subscription and cached group counts, request results, and traffic totals when metrics is on
GET/connectionsA 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/tracksA 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/namespacesEach announced namespace with the connections announcing it, and the namespace subscriptions the relay holds
GET/upstreamsThe open publishers and cluster peers the relay can request from, with round-trip time and request results
GET/zonesTraffic and request results per api.accounting_zones prefix, then unzoned. Empty without zones.
GET/clusterThe relay's mesh identity, its links to peers, and what it advertises to each

metrics ​

MethodPathReturns
GET/metricsEvery 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 ​

MethodPathReturns
GET/latencyPercentiles 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/slowThe slowlog, newest first, with its two thresholds

qlog ​

MethodPathReturns
GET/qlogThe 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}/quicThe 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 ​

MethodPathReturns
GET/eventsEvery connection's qlog events as they happen, as Server-Sent Events
EventData
qlogThe 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.

MethodPathBodyDoes
DELETE/connections/{conn_id}Closes the connection at once. 204.
POST/connections/{conn_id}/goawaySends the client GOAWAY, and closes the connection if it is still open after timeout_ms. 202.
POST/drainRefuses 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 ​

MethodPathServes
POST/mcpThe MCP server, over the Streamable HTTP transport. See MCP tools.

List parameters ​

/connections and /tracks return one page:

json
{ "total": 42, "offset": 0, "limit": 100, "items": [] }
ParameterDescription
sortA sort key. A leading - sorts in descending order: sort=-bytes_out.
limitItems per page. 100 when left out, at most 1000.
offsetItems to skip. 0 when left out.
prefixOnly 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.
EndpointSort keys
/connectionsconn_id, connected_at, rtt, bytes_out, bytes_in, lost_packets, subscriptions
/trackstrack_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.

RequestAccepted tokens
GET /health, /ready, /metaNone needed, ever
Other GET and HEADOpen without read_token. With it, read_token or write_token.
GET /metricsAs 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, DELETEwrite_token
/mcpOnly 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.

json
{ "error": "feature_off", "detail": "add `actions` to api.features to turn this endpoint on" }
Statuserror
400bad_query, unknown_sort_key, unknown_window, bad_body, bad_filter
401token_required
403address_not_allowed, origin_not_allowed, token_rejected
404not_found, feature_off, unknown_connection, unknown_track, no_trace
406follow_needs_json_seq: follow asked for with Accept: application/json
409qlog_off, events_off
500qlog_unreadable

Startup refusals ​

With api.enable set, the relay refuses to start, and exits with code 1 and the reason, when:

SettingRefused when
featuresIt names a feature that does not exist
featuresIt has actions and write_token is not set
featuresIt has mcp and mcp_token_hash is not set
mcp_token_hashIt is not a sha256d$<salt>$<digest> line as relay api-token prints it
allowAn entry is neither an IP address nor a range, such as 10.0.0.0/8, with a prefix length its family allows
allowIt is empty, and bind or metrics_bind is a network address
allowAn 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_detailIt is not relay, track or subscription
metrics_resource_idmetrics_track_enable is on and the id is not 16 lowercase hexadecimal characters
bind, metrics_bindThe address cannot be bound, for example because the port is in use

The relay starts, with a warning in its log, when:

  • allow lists other ranges than loopback, but bind is a loopback address, where allow is ignored.
  • bind is a network address and allow is left at loopback only, so remote clients get 403.
  • bind is a network address with no read_token, so the ranges in allow read without a token.
  • mcp_write is on without the actions feature, 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.

ToolFeatureArgumentsReturns
relay_overviewstateWhat /overview returns
list_connectionsstateclosed, sort, limit (max 100), offset, prefixA page of connections, as /connections
get_connectionstateconn_idOne connection in full
connection_timelineqlog, with qlog_folder setconn_id, limit (max 200)The control messages a connection exchanged, each request with its responses, stream resets, parse errors and the close
list_tracksstatesort, limit (max 100), offset, prefixA page of tracks, as /tracks
get_trackstatetrack_idOne track with its subscriptions and cache
namespacesstateWhat /namespaces returns
upstreamsstateWhat /upstreams returns
zonesstateWhat /zones returns
clusterstateWhat /cluster returns
latency_reportlatencywindowWhat /latency returns
slowloglatencylimit (max 100)The newest slowlog entries
send_goawayactions, writeconn_id, timeout_msSends one client GOAWAY, as POST /connections/{conn_id}/goaway
close_connectionactions, writeconn_idCloses one connection at once
drain_relayactions, writetimeout_msDrains the relay, as POST /drain
set_log_filteractions, writefilterReplaces the log filter
set_redirect_uriactions, writeuriReplaces the GOAWAY redirect URI

A failed call returns a tool error with the reason, which the agent can read and act on.