Admin voice

A voice region is a named group of media machines, and a voice server is one machine registered inside it. Together they are the topology Voice places a session into when it joins a voice channel or a call.

No operation here addresses a live session, a participant, or a track. Get voice state counts reports occupancy, and List RTC regions is the caller-facing view of the same regions.

Changes apply to new placements

Every write publishes a change notification. Each API node reloads the voice configuration when it receives that notification, a short time after the write. Placements after that reload use the new configuration. No write moves or disconnects an existing session.

A failed response can follow a successful change

A 500 response can arrive after the configuration has changed. Read it back before retrying.

Media transport

LiveKit is the media transport. Each voice server record names one LiveKit deployment and the API key pair the instance authenticates to it with.

endpoint is that deployment’s signalling URL, a ws:// or wss:// address. Fluxer hands it to the placed session verbatim as the endpoint of Voice Server Update, and the client opens its media connection there. The API rewrites the same value to http:// or https:// for its own room service calls, and it keeps any path prefix.

api_key and api_secret mint the 600-second grant the placed session presents, as Voice describes. The grant admits the session to exactly one room and has the track sources the member’s permissions allow.

A room is one voice channel. A guild channel uses the room name guild_{guild_id}_channel_{channel_id} and a private call uses dm_channel_{channel_id}.

A participant is one voice connection, identified as user_{user_id}_{connection_id}. One account holding several connections in a channel is several participants. Going live publishes a screen share track from the participant that already exists, so a stream needs no second server, room, or grant.

Placement eligibility

The stored fields below decide whether a region or a server can be chosen for one placement. Fluxer evaluates them identically on both records, and it also skips a server whenever is_active is false. It resolves a region first, then a server inside it, so a caller admitted to a region whose servers all refuse it cannot use that region.

allowed_user_ids is evaluated first and on its own. A non-empty list admits only the accounts it names and refuses every other caller whatever the remaining fields say. An empty list gates nothing.

vip_only, required_guild_features, and allowed_guild_ids are guild gates. When none of the three is set, the record admits every caller that passed the user gate, including a private call, which has no guild. When any of the three is set, the record admits only a placement that has a guild. A call or a group direct message can then never use that region or server.

With a guild present, a guild named by allowed_guild_ids is admitted at once and the other gates are not checked. Otherwise vip_only requires the guild to hold the VIP_VOICE guild feature, and required_guild_features requires the guild to hold at least one of the features it names. A guild holding none of them is refused.

Admin voice region object

A region record has the identity a client sees, the coordinate placement measures distance from, and the eligibility fields described under placement eligibility. It has no capacity, no health, and no server count.

The operator supplies id on creation. Channels reference it through rtc_region, and Modify call region accepts it. To change an ID, create a new region and delete the old one.

Structure

Field	Type	Description
id	string	The ID of the region, chosen by the operator and never renamed (1-64 characters)
name	string	The name shown for the region in a client (1-100 characters)
emoji	string	The emoji the operator configured for the region (1-64 characters)
latitude	number	The latitude placement measures distance from, in decimal degrees
longitude	number	The longitude placement measures distance from, in decimal degrees
is_default1	boolean	Whether automatic placement falls back to this region
vip_only2	boolean	Whether the guild has to hold VIP_VOICE
required_guild_features2	array[string]	Guild features that admit a guild, any one of which is enough (max 100)
allowed_guild_ids23	array[snowflake]	The guilds admitted without checking the other guild gates (max 1000)
allowed_user_ids3	array[snowflake]	The accounts allowed to use the region at all (max 1000)
created_at	?ISO8601 timestamp	Time the region record was created, or null when the stored row has none
updated_at	?ISO8601 timestamp	Time the region record last changed, or null when the stored row has none
servers?4	array[Admin voice server object]	The servers registered in the region

¹ The flag is not exclusive, and setting it on a second region does not clear it on the first. Each API node then uses the first flagged region in the region list it loaded as the default. When no region is flagged, it uses the first region in that list

² Setting any of these three makes the region unusable for a private call

³ Duplicate entries collapse and the returned order is not the submitted order

⁴ Present only on List voice regions and Get voice region, and only when include_servers resolved to true. List voice regions sorts the array by server identifier, and Get voice region returns it in the order the store yields

Example

{
  "id": "europe-north",
  "name": "Northern Europe",
  "emoji": "🇸🇪",
  "latitude": 59.33,
  "longitude": 18.06,
  "is_default": true,
  "vip_only": false,
  "required_guild_features": [],
  "allowed_guild_ids": [],
  "allowed_user_ids": [],
  "created_at": "2026-02-11T08:14:00.000Z",
  "updated_at": "2026-08-02T17:45:31.000Z"
}

Admin voice server object

A server record names one LiveKit deployment, the API key pair the instance authenticates to it with, and its own set of eligibility fields. A server is available for placement only when its region also admits the placement.

The region_id and server_id pair addresses one server, and a server belongs to exactly one region. The same server identifier can exist in two regions. Moving a server between regions means deleting it and recreating it. Both identifiers are operator-chosen strings of 1 to 64 characters, and no operation renames either one.

A server can have its own coordinate. Placement then measures distance from that coordinate to pick the closest server for an automatically placed session. A server without one takes no part in distance comparison.

A server can also have a soft connection limit, described under soft connection limits.

Structure

Field	Type	Description
region_id	string	The ID of the region the server belongs to (1-64 characters)
server_id	string	The ID of the server, unique inside its region (1-64 characters)
endpoint1	string	The LiveKit signalling URL the client opens its media connection to
latitude2	?number	The latitude replacing this server’s region coordinate, in decimal degrees, or null when the region coordinate is used
longitude2	?number	The longitude replacing this server’s region coordinate, in decimal degrees, or null when the region coordinate is used
is_active3	boolean	Whether the server is in rotation for new placement
soft_connection_limit5	?integer	The count at which placement starts preferring another server, or null when the server has no limit (1-2147483647)
vip_only	boolean	Whether the guild has to hold VIP_VOICE
required_guild_features	array[string]	Guild features that admit a guild, any one of which is enough (max 100)
allowed_guild_ids4	array[snowflake]	The guilds admitted without checking the other guild gates (max 1000)
allowed_user_ids4	array[snowflake]	The accounts allowed to use the server at all (max 1000)
created_at	?ISO8601 timestamp	Time the server record was created, or null when the stored row has none
updated_at	?ISO8601 timestamp	Time the server record last changed, or null when the stored row has none

¹ An instance can configure an internal URL that the API uses for its own room service calls to one designated server. That URL changes neither the stored value nor the value the session receives

² The two coordinates are set and cleared together, and a server with only one of them cannot be stored

³ Fluxer skips an inactive server when it resolves a new placement. Fluxer can still mute, deafen, change the permissions of, or disconnect a participant already on it

⁴ Duplicate entries collapse and the returned order is not the submitted order

⁵ The limit is a preference, not a cap. It is described under soft connection limits

Server credentials are never returned

api_key and api_secret are stored on the record and accepted by the create and update bodies. No read returns them, so a lost secret has to be replaced with an update.

Example

{
  "region_id": "europe-north",
  "server_id": "europe-north-server-1",
  "endpoint": "wss://voice.example.com/livekit",
  "latitude": null,
  "longitude": null,
  "is_active": true,
  "soft_connection_limit": null,
  "vip_only": false,
  "required_guild_features": [],
  "allowed_guild_ids": [],
  "allowed_user_ids": [],
  "created_at": "2026-02-11T08:15:22.000Z",
  "updated_at": "2026-02-11T08:15:22.000Z"
}

Soft connection limits

soft_connection_limit is the connection count at which a server stops being a preferred placement target. It orders the candidates for one placement and never refuses one.

Placement splits the servers it may use into those below their limit and those at or above it. It picks from the first group, and it picks from the full set when the first group is empty. A server with a null limit is always in the first group, and so is a server whose current count is unknown. A session is therefore still placed on a server past its limit when no other server can take it.

The count is the number of voice connections the gateway holds for the server, the same figure Get voice state counts returns. Each API node reads it at most once every 15 seconds and places against the last reading, so a burst of placements can push a server past its limit before the next reading. A node that has no reading less than 60 seconds old places as though no server had a limit.

The count is keyed by server_id alone. Two servers registered in different regions under the same server_id share one count, and each is measured against its own limit.

The limit is read when a channel is first placed and the server is pinned for it, as Voice describes. Later placements into that channel inherit the pin and are not measured against the limit. Lowering or clearing a limit moves no live session.

List voice regions

GET/v1/admin/voice/regionsAudit reason

Returns every Admin voice region object in ascending display name order. Requires voice:region:list.

Query parameters

Field	Type	Description
include_servers?1	boolean	Whether each region has its servers, sorted by server identifier (default false)

¹ The value is read as a string and counts as true only for true, True, or 1, so any other value, including yes and TRUE, is false. Supplying the parameter twice makes it an array, which fails validation

Response body

Field	Type	Description
regions	array[Admin voice region object]	Every configured region

Response

Status	Body	Condition
200	response body	The regions were returned

Side effects

The operation records one Admin audit entry with action list_voice_regions, target type voice_region, target ID 0, and metadata keys include_servers and result_count.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Get voice region

GET/v1/admin/voice/regions/{region_id}Audit reason

Returns one Admin voice region object. Requires voice:region:list.

Path parameters

Field	Type	Description
region_id	string	The ID of the region (1-64 characters)

Query parameters

Field	Type	Description
include_servers?12	boolean	Whether the region has its servers (default true)

¹ The default is true here and false on List voice regions

² The value is read as a string and counts as true only for true, True, or 1, so any other value suppresses the servers

Response body

Field	Type	Description
region1	?Admin voice region object	The region, or null when no region has the identifier

¹ An unknown region answers 200 with a null region, so region existence is read from the body

Response

Status	Body	Condition
200	response body	A lookup was done, whether or not it resolved

Side effects

The operation records one Admin audit entry with action get_voice_region, target type voice_region, target ID 0, and metadata keys region_id, include_servers, and found. An unknown region records found as false.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Create voice region

POST/v1/admin/voice/regionsAudit reason

Stores a region and returns it. Requires voice:region:create.

JSON body

Field	Type	Description
id1	string	The ID to store the region under (1-64 characters)
name	string	The name shown for the region in a client (1-100 characters)
emoji	string	The emoji the operator configured for the region (1-64 characters)
latitude	number	The latitude placement measures distance from, in decimal degrees
longitude	number	The longitude placement measures distance from, in decimal degrees
is_default?	boolean	Whether automatic placement falls back to this region (default false)
vip_only?	boolean	Whether the guild has to hold VIP_VOICE (default false)
required_guild_features?2	array[string]	Guild features that admit a guild (max 100 items, default empty)
allowed_guild_ids?	array[snowflake]	The guilds admitted without checking the other guild gates (max 1000, default empty)
allowed_user_ids?	array[snowflake]	The accounts allowed to use the region at all (max 1000, default empty)

¹ The identifier is not checked for collision. Reusing the identifier of an existing region overwrites that record in full, resets its creation time to now, and replaces its required_guild_features, allowed_guild_ids, and allowed_user_ids arrays

² Each item is 1 to 64 characters. A value that is not a real guild feature is stored as supplied and then matches no guild

Response body

Field	Type	Description
region1	Admin voice region object	The stored region

¹ The object has no servers member

Response

Status	Body	Condition
200	response body	The region was stored

Side effects

Each node reloads its topology after the write. One Admin audit entry with the action create_voice_region and the target type voice_region records the region identifier and its name in metadata.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

Update voice region

PATCH/v1/admin/voice/regions/{region_id}Audit reason

Applies a partial update to a region and returns the updated record. Requires voice:region:update.

Path parameters

Field	Type	Description
region_id	string	The ID of the region (1-64 characters)

JSON body

Every field is optional and an omitted field is left unchanged. An absent, empty, or whitespace-only body is read as an empty object, which validates and updates nothing but updated_at. A body that does not parse as JSON returns 400 INVALID_FORM_BODY with one element at path body and code INVALID_FORMAT, as Errors describes.

Field	Type	Description
name?	string	The name shown for the region in a client (1-100 characters)
emoji?	string	The emoji the operator configured for the region (1-64 characters)
latitude?	number	The latitude placement measures distance from, in decimal degrees
longitude?	number	The longitude placement measures distance from, in decimal degrees
is_default?	boolean	Whether automatic placement falls back to this region
vip_only?	boolean	Whether the guild has to hold VIP_VOICE
required_guild_features?1	array[string]	Guild features that admit a guild (max 100 items of 1-64 characters each)
allowed_guild_ids?1	array[snowflake]	The guilds admitted without checking the other guild gates (max 1000)
allowed_user_ids?1	array[snowflake]	The accounts allowed to use the region at all (max 1000)

¹ A supplied collection replaces the stored collection outright, so removing one entry means sending the complete remaining set and clearing a collection means sending an empty array

An id member in the body is overwritten from the path and never renames the region.

Response body

Field	Type	Description
region1	Admin voice region object	The updated region

¹ The object has no servers member. Read the servers with List voice servers or Get voice region

Response

Status	Body	Condition
200	response body	The region was updated
404	error response	No region has the identifier, returned as UNKNOWN_VOICE_REGION

Side effects

The write sets updated_at to the time it ran, and each node reloads its topology. One Admin audit entry with the action update_voice_region and the target type voice_region records the region identifier in metadata. The entry has no field diff.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

Delete voice region

DELETE/v1/admin/voice/regions/{region_id}Audit reason

Deletes a region and every server registered in it. Requires voice:region:delete.

Path parameters

Field	Type	Description
region_id	string	The ID of the region (1-64 characters)

Deleting a region deletes every server in it

There is no confirmation step or recovery operation. Save the server configuration and credentials separately before deleting a region if they will be needed again. Server reads do not return credentials.

Response body

Field	Type	Description
success1	boolean	Always true

¹ The value is fixed, so a client reads the status to learn whether the call succeeded

Response

Status	Body	Condition
200	response body	The region was deleted
404	error response	No region has the identifier, returned as UNKNOWN_VOICE_REGION

Side effects

After each API node reloads its topology, Fluxer can no longer mute, deafen, change the permissions of, or remove a participant on a deleted server. Existing sessions are not disconnected by the deletion itself.

One Admin audit entry with the action delete_voice_region and the target type voice_region records the region identifier and its name in metadata. No delete_voice_server entry is written for the servers deleted with the region.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

List voice servers

GET/v1/admin/voice/regions/{region_id}/serversAudit reason

Returns every Admin voice server object registered in one region. Requires voice:server:list.

Path parameters

Field	Type	Description
region_id	string	The ID of the region (1-64 characters)

Response body

Field	Type	Description
servers1	array[Admin voice server object]	The servers registered in the region

¹ A region with no server and an identifier naming no region both answer with an empty array

Response

Status	Body	Condition
200	response body	The servers were returned

Side effects

The operation records one Admin audit entry with action list_voice_servers, target type voice_server, target ID 0, and metadata keys region_id and result_count.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Get voice server

GET/v1/admin/voice/regions/{region_id}/servers/{server_id}Audit reason

Returns one Admin voice server object. Requires voice:server:list.

Path parameters

Field	Type	Description
region_id	string	The ID of the region the server belongs to (1-64 characters)
server_id	string	The ID of the server (1-64 characters)

Response body

Field	Type	Description
server1	?Admin voice server object	The server, or null when the pair resolves to nothing

¹ An unknown server answers 200 with a null server, and an unknown region is reported the same way

Response

Status	Body	Condition
200	response body	A lookup was done, whether or not it resolved

Side effects

The operation records one Admin audit entry with action get_voice_server, target type voice_server, target ID 0, and metadata keys region_id, server_id, and found. A pair that resolves to no server records found as false.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Create voice server

POST/v1/admin/voice/regions/{region_id}/serversAudit reason

Registers a voice server in a region and returns it. Requires voice:server:create.

Path parameters

Field	Type	Description
region_id	string	The ID of the region the server belongs to (1-64 characters)

JSON body

Field	Type	Description
server_id1	string	The ID to store the server under, unique inside the region (1-64 characters)
endpoint2	string	The LiveKit signalling URL the client opens its media connection to
api_key	string	The LiveKit API key the instance authenticates with (1-256 characters)
api_secret	string	The LiveKit API secret the instance authenticates with (1-256 characters)
latitude?3	?number	The latitude replacing this server’s region coordinate, in decimal degrees, or null to use the region coordinate
longitude?3	?number	The longitude replacing this server’s region coordinate, in decimal degrees, or null to use the region coordinate
is_active?	boolean	Whether the server is in rotation for new placement (default true)
soft_connection_limit?4	?integer	The count at which placement starts preferring another server, or null for no limit (1-2147483647, default null)
vip_only?	boolean	Whether the guild has to hold VIP_VOICE (default false)
required_guild_features?	array[string]	Guild features that admit a guild (max 100 items of 1-64 characters each, default empty)
allowed_guild_ids?	array[snowflake]	The guilds admitted without checking the other guild gates (max 1000, default empty)
allowed_user_ids?	array[snowflake]	The accounts allowed to use the server at all (max 1000, default empty)

¹ The pair of region and server identifier is not checked for collision. Reusing an existing pair overwrites that record in full, resets its creation time to now, and replaces both stored credentials

² The value has to parse as a URL. Validation does not limit the scheme, and the client receives the value unchanged

³ The two coordinates are supplied together and are either both null or both a number. A mismatched pair fails body validation on the latitude path

⁴ Zero and every negative value fail validation, so a server with no limit is registered by omitting the field or sending null. Soft connection limits describes what the value does

The body has no region_id. A region_id member in the body is overwritten from the path and cannot register the server under a different region.

Response body

Field	Type	Description
server1	Admin voice server object	The stored server

¹ Neither api_key nor api_secret appears on the object

Response

Status	Body	Condition
200	response body	The server was stored
400	error response	A non-URL endpoint or an unpaired coordinate, returned as INVALID_FORM_BODY
404	error response	The identifier names no region, returned as UNKNOWN_VOICE_REGION

Side effects

Each node reloads its topology after the write. One Admin audit entry with the action create_voice_server and the target type voice_server records the region identifier, the server identifier, and the endpoint in metadata. Neither credential is recorded.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

Update voice server

PATCH/v1/admin/voice/regions/{region_id}/servers/{server_id}Audit reason

Applies a partial update to a voice server and returns the updated record. Requires voice:server:update.

Path parameters

Field	Type	Description
region_id	string	The ID of the region the server belongs to (1-64 characters)
server_id	string	The ID of the server (1-64 characters)

JSON body

Every field is optional and an omitted field is left unchanged. An absent, empty, or whitespace-only body is read as an empty object, which validates and updates nothing but updated_at. A body that does not parse as JSON returns 400 INVALID_FORM_BODY with one element at path body and code INVALID_FORMAT, as Errors describes.

Field	Type	Description
endpoint?	string	The LiveKit signalling URL the client opens its media connection to, which has to parse as a URL
api_key?1	string	The LiveKit API key the instance authenticates with (1-256 characters)
api_secret?1	string	The LiveKit API secret the instance authenticates with (1-256 characters)
latitude?2	?number	The latitude replacing this server’s region coordinate, in decimal degrees, or null to use the region coordinate
longitude?2	?number	The longitude replacing this server’s region coordinate, in decimal degrees, or null to use the region coordinate
is_active?	boolean	Whether the server is in rotation for new placement
soft_connection_limit?4	?integer	The count at which placement starts preferring another server, or null for no limit (1-2147483647)
vip_only?	boolean	Whether the guild has to hold VIP_VOICE
required_guild_features?3	array[string]	Guild features that admit a guild (max 100 items of 1-64 characters each)
allowed_guild_ids?3	array[snowflake]	The guilds admitted without checking the other guild gates (max 1000)
allowed_user_ids?3	array[snowflake]	The accounts allowed to use the server at all (max 1000)

¹ An omitted credential is left unchanged and a supplied one replaces it. An empty string fails the length bound, so a credential can be replaced but never cleared

² The two coordinates are supplied together and are either both null or both a number. Sending both as null clears the override and returns the server to its region coordinate

³ A supplied collection replaces the stored collection outright, so removing one entry means sending the complete remaining set and clearing a collection means sending an empty array

⁴ An omitted limit is left unchanged and null clears it. Zero and every negative value fail validation

A region_id or server_id member in the body is overwritten from the path and cannot move the server to another region.

Response body

Field	Type	Description
server	Admin voice server object	The updated server

Response

Status	Body	Condition
200	response body	The server was updated
404	error response	The pair resolves to no server, returned as UNKNOWN_VOICE_SERVER

Side effects

The write sets updated_at to the time it ran, and each node reloads its topology and uses the stored credentials for later calls to the server. Setting is_active to false stops new placement and does not move sessions already on the server.

One Admin audit entry with the action update_voice_server and the target type voice_server records the region identifier and the server identifier in metadata. The entry records neither credential and no field diff, so a credential rotation is indistinguishable in the audit log from any other update.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

Delete voice server

DELETE/v1/admin/voice/regions/{region_id}/servers/{server_id}Audit reason

Deletes a voice server. Requires voice:server:delete.

Path parameters

Field	Type	Description
region_id	string	The ID of the region the server belongs to (1-64 characters)
server_id	string	The ID of the server (1-64 characters)

Response body

Field	Type	Description
success1	boolean	Always true

¹ The value is fixed, so a client reads the status to learn whether the call succeeded

Response

Status	Body	Condition
200	response body	The server was deleted
404	error response	The pair resolves to no server, returned as UNKNOWN_VOICE_SERVER

Side effects

Each node reloads its topology after the removal, and Fluxer can then no longer mute, deafen, change the permissions of, or remove a participant still on that server. Sessions already placed on the server are not disconnected by the deletion itself. The stored credentials are removed with the record and are not recoverable.

One Admin audit entry with the action delete_voice_server and the target type voice_server records the region identifier, the server identifier, and the endpoint the server held in metadata.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.