Control-plane HTTP API for runtime visibility and user/config management. Data-plane MTProto traffic is out of scope.

API runtime is configured in [server.api].

server.admin_api is accepted as an alias for backward compatibility.

Runtime validation for API config:

• server.api.listen must be a valid IP:PORT.
• server.api.request_body_limit_bytes must be > 0.
• server.api.minimal_runtime_cache_ttl_ms must be within [0, 60000].
• server.api.runtime_edge_cache_ttl_ms must be within [0, 60000].
• server.api.runtime_edge_top_n must be within [1, 1000].
• server.api.runtime_edge_events_capacity must be within [16, 4096].

{
  "ok": true,
  "data": {},
  "revision": "sha256-hex"
}

{
  "ok": false,
  "error": {
    "code": "machine_code",
    "message": "human-readable"
  },
  "request_id": 1
}

Requests are processed in this order:

1. api_enabled gate (503 api_disabled if disabled).
2. Source IP whitelist gate (403 forbidden).
3. Authorization header gate when configured (401 unauthorized).
4. Route and method matching (404 not_found or 405 method_not_allowed).
5. read_only gate for mutating routes (403 read_only).
6. Request body read/limit/JSON decode (413 payload_too_large, 400 bad_request).
7. Business validation and config write path.

Notes:

• Whitelist is evaluated against the direct TCP peer IP (SocketAddr::ip), without X-Forwarded-For support.
• Authorization check is exact string equality against configured auth_header.

• Request body is read only for mutating routes that define a body contract.
• Body size limit is enforced during streaming read (413 payload_too_large).
• Invalid transport body frame returns 400 bad_request (Invalid request body).
• Invalid JSON returns 400 bad_request (Invalid JSON body).
• Content-Type is not required for JSON parsing.
• Unknown JSON fields are ignored by deserialization.
• PATCH updates only provided fields and does not support explicit clearing of optional fields.
• If-Match supports both quoted and unquoted values; surrounding whitespace is trimmed.

Note: the request contract is defined, but the corresponding route currently returns 404 (see routing edge cases).

Link generation uses active config and enabled modes:

• Link port is general.links.public_port when configured; otherwise server.port.
• If general.links.public_host is non-empty, it is used as the single link host override.
• If public_host is not set, hosts are resolved from server.listeners in order: announce -> announce_ip -> listener bind ip.
• For wildcard listener IPs (0.0.0.0 / ::), startup-detected external IP of the same family is used when available.
• Listener-derived hosts are de-duplicated while preserving first-seen order.
• If multiple hosts are resolved, API returns links for all resolved hosts in every enabled mode.
• If no host can be resolved from listeners, fallback is startup-detected IPv4 -> IPv6.
• Final compatibility fallback uses listen_addr_ipv4/listen_addr_ipv6 when routable, otherwise "UNKNOWN".
• User rows are sorted by username in ascending lexical order.

All mutating endpoints:

• Respect read_only mode.
• Accept optional If-Match for optimistic concurrency.
• Return new revision after successful write.
• Use process-local mutation lock + atomic write (tmp + rename) for config persistence.

Delete path cleanup guarantees:

• Config cleanup removes only the requested username keys.
• Runtime unique-IP cleanup removes only this user's limiter and tracked IP state.

source_unavailable conditions:

• ME endpoints: ME pool is absent (for example direct-only mode or failed ME initialization).
• Upstreams endpoint: non-blocking upstream snapshot lock is unavailable at request time.

Additional runtime endpoint behavior:

When general.use_middle_proxy=true and general.me2dc_fallback=true:

• Startup does not block on full ME pool readiness; initialization can continue in background.
• Runtime initialization payload can expose ME stage background_init until pool becomes ready.
• Admission/routing decision uses two readiness grace windows for "ME not ready" periods: 80s before first-ever readiness is observed (startup grace), 6s after readiness has been observed at least once (runtime failover timeout).
• While in fallback window breach, new sessions are routed via Direct-DC; when ME becomes ready, routing returns to Middle mode for new sessions.

• Success responses always include revision.
• Error responses never include revision; they include request_id.
• Optional fields with skip_serializing_if are omitted when absent.
• Nullable payload fields may still be null where contract uses ? (for example UserInfo option fields).
• For /v1/stats/upstreams, authentication details of SOCKS upstreams are intentionally omitted.
• ip[] fields are serialized as JSON string arrays (for example "1.2.3.4", "2001:db8::1").

• POST /v1/users/{username}/rotate-secret is currently unreachable in route matcher and returns 404.
• API runtime controls under server.api are documented as restart-required; hot-reload behavior for these fields is not strictly uniform in all change combinations.