> ## 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.

# Remove LiveKit participant

> Removes a participant from a LiveKit room, forcibly disconnecting them.
Access is authorized via `metadata.auth_id` check.

Note: This does not invalidate the participant's token. To prevent rejoining,
use short-lived tokens and avoid issuing new tokens to removed participants.

# Arguments
* `state` - Shared application state containing LiveKit configuration
* `auth` - Authentication context from middleware
* `request` - Request with room name and participant identity

# Returns
* `Response` - JSON response with removal status or error

# 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
* 400 Bad Request - Empty room name or participant identity
* 404 Not Found - Room/participant not found or access denied (masked)
* 500 Internal Server Error - LiveKit not configured or removal failed

# Flow
1. Validate request fields are not empty
2. Check room access via metadata.auth_id
3. Verify participant exists in the room
4. Remove the participant
5. Return success or appropriate error

Removes a participant from a LiveKit room, forcibly disconnecting them. 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). |

<Note>
  Room names are used exactly as provided. No prefixing or modification is applied.
</Note>

## Request

Requires `room_name` and `participant_identity` in the request body.

## Error responses

| Status                      | Condition                                                          |
| --------------------------- | ------------------------------------------------------------------ |
| `400 Bad Request`           | Empty room name or participant identity.                           |
| `404 Not Found`             | Room/participant not found or access denied (masked for security). |
| `500 Internal Server Error` | LiveKit not configured or removal failed.                          |

<Warning>
  This endpoint does not revoke the participant's token. To prevent rejoining, use short-lived tokens and avoid issuing new tokens to removed participants.
</Warning>


## OpenAPI

````yaml DELETE /livekit/participant
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/participant:
    delete:
      tags:
        - livekit
      summary: Handler for DELETE /livekit/participant endpoint
      description: >-
        Removes a participant from a LiveKit room, forcibly disconnecting them.

        Access is authorized via `metadata.auth_id` check.


        Note: This does not invalidate the participant's token. To prevent
        rejoining,

        use short-lived tokens and avoid issuing new tokens to removed
        participants.


        # Arguments

        * `state` - Shared application state containing LiveKit configuration

        * `auth` - Authentication context from middleware

        * `request` - Request with room name and participant identity


        # Returns

        * `Response` - JSON response with removal status or error


        # 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

        * 400 Bad Request - Empty room name or participant identity

        * 404 Not Found - Room/participant not found or access denied (masked)

        * 500 Internal Server Error - LiveKit not configured or removal failed


        # Flow

        1. Validate request fields are not empty

        2. Check room access via metadata.auth_id

        3. Verify participant exists in the room

        4. Remove the participant

        5. Return success or appropriate error
      operationId: remove_participant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveParticipantRequest'
        required: true
      responses:
        '200':
          description: Participant removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveParticipantResponse'
        '400':
          description: Invalid request (empty fields)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveParticipantErrorResponse'
        '404':
          description: Participant not found in room
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveParticipantErrorResponse'
        '500':
          description: LiveKit not configured or removal failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveParticipantErrorResponse'
      security:
        - auth: []
components:
  schemas:
    RemoveParticipantRequest:
      type: object
      description: |-
        Request body for removing a participant from a LiveKit room

        # Example
        ```json
        {
          "room_name": "conversation-room-123",
          "participant_identity": "user-alice-456"
        }
        ```
      required:
        - room_name
        - participant_identity
      properties:
        participant_identity:
          type: string
          description: The identity of the participant to remove
          example: user-alice-456
        room_name:
          type: string
          description: The LiveKit room name where the participant is connected
          example: conversation-room-123
    RemoveParticipantResponse:
      type: object
      description: |-
        Response for a successful participant removal

        # Example
        ```json
        {
          "status": "removed",
          "room_name": "conversation-room-123",
          "participant_identity": "user-alice-456"
        }
        ```
      required:
        - status
        - room_name
        - participant_identity
      properties:
        participant_identity:
          type: string
          description: The identity of the removed participant
          example: user-alice-456
        room_name:
          type: string
          description: The room name
          example: conversation-room-123
        status:
          type: string
          description: Status of the removal operation
          example: removed
    RemoveParticipantErrorResponse:
      type: object
      description: |-
        Error response for participant removal failures

        # Example
        ```json
        {
          "error": "Participant 'user-123' not found in room",
          "code": "PARTICIPANT_NOT_FOUND"
        }
        ```
      required:
        - error
        - code
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: PARTICIPANT_NOT_FOUND
        error:
          type: string
          description: Human-readable error message
          example: Participant not found in room
  securitySchemes:
    auth:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: >-
        Authentication token for protected endpoints. Can be provided as
        `Authorization: Bearer <token>` or `?api_key=<token>`. Required when
        AUTH_REQUIRED is enabled.

````