> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sayna.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# LiveKit room details
> Returns detailed information about a specific LiveKit room including
all current participants. Access is authorized via `metadata.auth_id` check.
# Arguments
* `state` - Shared application state containing LiveKit configuration
* `auth` - Authentication context from middleware
* `room_name` - Name of the room to retrieve (from path parameter)
# Returns
* `Response` - JSON response with room details or error status
# Authorization
- When `auth.id` is present: Requires `room.metadata.auth_id == auth.id`
- When `auth.id` is absent: Access is allowed (backward-compatible mode)
# Errors
* 404 Not Found - Room not found or access denied (masked as not found)
* 500 Internal Server Error - LiveKit service not configured or API call failed
Returns detailed information about a specific LiveKit room including all current participants. Access is authorized via `metadata.auth_id` check.
## Authorization
| Mode | Behavior |
| ---------------------------------- | --------------------------------------------- |
| Authenticated (`auth.id` present) | Requires `room.metadata.auth_id == auth.id`. |
| Unauthenticated (`auth.id` absent) | Access is allowed (backward-compatible mode). |
Room names are used exactly as provided. No prefixing or modification is applied.
## Response
Returns room details including:
* `sid` - Unique session ID (generated by LiveKit)
* `name` - The room name
* `num_participants` - Current participant count
* `max_participants` - Maximum allowed (0 = no limit)
* `creation_time` - Unix timestamp
* `metadata` - Room metadata (treat as opaque JSON)
* `active_recording` - Whether recording is active
* `participants` - List of participants with identities, metadata, and state
## Error responses
| Status | Condition |
| --------------------------- | ------------------------------------------------------ |
| `404 Not Found` | Room not found or access denied (masked for security). |
| `500 Internal Server Error` | LiveKit not configured or API call failed. |
## OpenAPI
````yaml GET /livekit/rooms/{room_name}
openapi: 3.1.0
info:
title: Sayna API
description: >-
Real-time voice processing server with Speech-to-Text (STT) and
Text-to-Speech (TTS) services
contact:
name: Sayna
url: https://api.sayna.ai
license:
name: Apache-2.0
identifier: Apache-2.0
version: 0.1.0
servers:
- url: https://api.sayna.ai
description: Production API
- url: http://localhost:3001
description: Local development
security: []
tags:
- name: health
description: Health check endpoints
- name: voices
description: TTS voice management
- name: tts
description: Text-to-speech synthesis
- name: livekit
description: LiveKit room and token management
- name: recordings
description: Recording download operations
- name: sip
description: SIP webhook configuration management
- name: websocket
description: WebSocket API for real-time communication
paths:
/livekit/rooms/{room_name}:
get:
tags:
- livekit
summary: Handler for GET /livekit/rooms/{room_name} endpoint
description: >-
Returns detailed information about a specific LiveKit room including
all current participants. Access is authorized via `metadata.auth_id`
check.
# Arguments
* `state` - Shared application state containing LiveKit configuration
* `auth` - Authentication context from middleware
* `room_name` - Name of the room to retrieve (from path parameter)
# Returns
* `Response` - JSON response with room details or error status
# Authorization
- When `auth.id` is present: Requires `room.metadata.auth_id == auth.id`
- When `auth.id` is absent: Access is allowed (backward-compatible mode)
# Errors
* 404 Not Found - Room not found or access denied (masked as not found)
* 500 Internal Server Error - LiveKit service not configured or API call
failed
operationId: get_room_details
parameters:
- name: room_name
in: path
description: Name of the room to retrieve
required: true
schema:
type: string
responses:
'200':
description: Room details retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RoomDetailsResponse'
'404':
description: Room not found or not accessible
'500':
description: LiveKit service not configured or failed to get room details
security:
- auth: []
components:
schemas:
RoomDetailsResponse:
type: object
description: |-
Detailed information about a LiveKit room including participants
# Example
```json
{
"sid": "RM_xyz789",
"name": "conversation-room-123",
"num_participants": 2,
"max_participants": 10,
"creation_time": 1703123456,
"metadata": "{\"auth_id\": \"tenant-123\"}",
"active_recording": false,
"participants": [...]
}
```
required:
- sid
- name
- num_participants
- max_participants
- creation_time
- metadata
- active_recording
- participants
properties:
active_recording:
type: boolean
description: Whether a recording is currently active
example: false
creation_time:
type: integer
format: int64
description: Room creation time (Unix timestamp in seconds)
example: 1703123456
max_participants:
type: integer
format: int32
description: Maximum allowed participants (0 = no limit)
example: 10
minimum: 0
metadata:
type: string
description: User-specified metadata for the room
example: ''
name:
type: string
description: The room name
example: conversation-room-123
num_participants:
type: integer
format: int32
description: Number of current participants in the room
example: 2
minimum: 0
participants:
type: array
items:
$ref: '#/components/schemas/ParticipantInfo'
description: List of participants currently in the room
sid:
type: string
description: Unique session ID for the room (generated by LiveKit)
example: RM_xyz789
ParticipantInfo:
type: object
description: |-
Detailed information about a participant in a LiveKit room
# Example
```json
{
"sid": "PA_abc123",
"identity": "user-alice-456",
"name": "Alice Smith",
"state": "ACTIVE",
"kind": "STANDARD",
"joined_at": 1703123456,
"metadata": "{\"role\": \"host\"}",
"attributes": {}
}
```
required:
- sid
- identity
- name
- state
- kind
- joined_at
- metadata
- attributes
- is_publisher
properties:
attributes:
type: object
description: User-specified attributes for the participant
additionalProperties:
type: string
propertyNames:
type: string
identity:
type: string
description: Unique identifier provided when connecting
example: user-alice-456
is_publisher:
type: boolean
description: Whether the participant is currently publishing audio/video
example: true
joined_at:
type: integer
format: int64
description: Timestamp when participant joined (Unix timestamp in seconds)
example: 1703123456
kind:
type: string
description: 'Participant kind: STANDARD, AGENT, SIP, EGRESS, or INGRESS'
example: STANDARD
metadata:
type: string
description: User-specified metadata for the participant
example:
role: host
name:
type: string
description: Display name of the participant
example: Alice Smith
sid:
type: string
description: Unique session ID for this participant (generated by LiveKit)
example: PA_abc123
state:
type: string
description: 'Participant state: JOINING, JOINED, ACTIVE, or DISCONNECTED'
example: ACTIVE
securitySchemes:
auth:
type: http
scheme: bearer
bearerFormat: Token
description: >-
Authentication token for protected endpoints. Can be provided as
`Authorization: Bearer ` or `?api_key=`. Required when
AUTH_REQUIRED is enabled.
````