minimusdocs
Help center

Servers

List servers

GET/instances/servers/

read Read: looks, changes nothing. Scopes

Every server, a page at a time: the panel's own and each streaming server, with its addresses, limits, health and update state. Panel operators only.

Query parameters

  • pageinteger

    A page number within the paginated result set.

  • page_sizeinteger

    Number of results to return per page.

Response

200 OK

  • countintegerrequired

    How many there are in all, on every page.

  • nextstring (uri)can be null

    The next page, or null on the last one.

  • previousstring (uri)can be null

    The page before, or null on the first one.

  • resultsobject[]required
    • idstring (uuid)requiredread-only
    • instance_idstringrequiredread-only

      Stable identifier used in routing hashes. Must not change between restarts.

    • namestringrequired
    • kindstringrequiredread-only

      panel for the panel's own server (made by the install), streaming for every streaming server.

      • panel - Panel
      • streaming - Streaming node
    • domainstringrequired

      The server's public address (a host name). The install sets it on streaming servers.

    • address_rulestring

      Which of the streaming addresses each new viewer is sent to.

      • turns - Take turns
      • least_busy - Least busy
      • same_viewer - Same address per viewer
      • random - At random
    • caddy_managedboolean

      Whether the panel keeps the server's web address set up by itself.

    • internal_urlstring (uri)requiredread-only

      Where the panel reaches the server. Empty for the panel itself.

    • public_urlstring (uri)requiredread-only

      Client-facing URL used in stream redirects. Empty for the panel row.

    • ipstringrequiredread-onlycan be null

      The server's own public IP address.

    • stream_portinteger

      The port viewers reach the streams on. Setting it asks the server to move there.

    • desired_stream_portintegerrequiredread-onlycan be null

      A port change the server has not made yet. Empty when none is under way.

    • stream_port_errorstringrequiredread-onlycan be null
    • capabilitiesanyrequiredread-only

      e.g. ["x264", "nvenc", "vaapi"]

    • max_streamsinteger

      Hard ceiling. Rejected by FILL/LEAST_LOADED when reached.

    • weightinteger

      Higher = more streams routed here under HASH mode.

    • network_capacity_mbpsintegercan be null

      The bandwidth this server's port can push, in megabits per second — for example 10000 for a 10 Gbps port. Leave empty to use the speed its network card reports.

    • is_enabledboolean

      Operator switch. Set False to drain a server.

    • is_healthybooleanrequiredread-only
    • serves_streamsboolean

      Whether streams are sent to this server. Streaming servers are, once added, until you take one out; the panel's own server only after it is set to stream.

    • serves_vodboolean

      Whether this node may hold movie files and serve them. Every streaming node does by default — it is set when a node registers or the panel is promoted. Placement still only sends a file where it fits (vod_has_room: the quota, or the free space the node reports), so a node with no room is skipped rather than filled. Turn it off to keep movies off a node entirely.

    • vod_max_bytesinteger

      Ceiling on what movies may occupy here. 0 means 'use the disk's real free space instead'. Set this when VOD shares a filesystem with anything else you care about — a full disk stops live streams on this node too, not just movies.

    • archive_max_bytesinteger

      The most catch-up recordings may use here. Over it, the oldest recordings go first. 0 = no limit beyond the disk, which always keeps a share free for movies.

    • last_seenstring (date-time)requiredread-onlycan be null
    • ping_msintegerrequiredread-onlycan be null

      How stale this node's last heartbeat is, in ms.

      Same number the analytics action returns, carried on the list row so a client rendering a table of nodes needs no per-row follow-up request. Derived here rather than in the browser because it is a difference against our clock: computed client-side, a viewer whose machine is a minute off would see every node reported as stale.

      Not a round-trip measurement — a real one would need an echo we don't run. Costs one subtraction per row, no extra query.

    • current_streamsintegerrequiredread-only
    • health_dataanyrequiredread-only

      Latest cpu_pct, ram_pct, current_streams, and (on VOD nodes) vod_used_bytes / vod_free_bytes / vod_total_bytes. Metrics live here rather than in columns so a node can report something new without a migration.

    • versionstringrequiredread-only

      The release this server runs. The panel's row is the panel's release, a node on the same server included: it is updated with the panel.

    • update_stateobjectrequiredread-only

      Whether this server can be updated from the panel, and how its last update went.

    • token_prefixstringrequiredread-only
    • created_atstring (date-time)requiredread-only
    • updated_atstring (date-time)requiredread-only

Errors

  • 401 No credential, or one that is wrong, expired or revoked.
  • 403 The account, or the key's or app's scopes, may not do this.
  • 429 Slow down: wait the seconds in the Retry-After header, then try again.

What each error means