### Automated GPU/CPU Setup Script

Source: https://docs.vexa.ai/deployment

Use this script for a fresh cloud VM setup. It automates the installation of Docker and Vexa. Specify --gpu or --cpu based on your host.

```bash
git clone https://github.com/Vexa-ai/vexa.git && cd vexa
sudo ./deploy/scripts/fresh_setup.sh --gpu    # or --cpu for CPU-only hosts
cp deploy/env-example .env
# Edit .env
make all
```

--------------------------------

### Local Development Setup for Vexa Dashboard

Source: https://docs.vexa.ai/ui-dashboard

Follow these steps to set up the Vexa Dashboard for local development. This involves cloning the repository, installing dependencies, configuring environment variables, and starting the development server.

```bash
git clone https://github.com/Vexa-ai/vexa.git
cd vexa/services/dashboard
npm install
cp .env.example .env.local
# edit .env.local: VEXA_API_URL + VEXA_ADMIN_API_KEY
npm run dev
```

--------------------------------

### Complete Workflow Example via curl

Source: https://docs.vexa.ai/self-hosted-management

A comprehensive example demonstrating the creation of a user, generation of an API token, and testing user API access using curl. It utilizes jq for parsing JSON responses.

```bash
# Step 1: Create user
USER_RESPONSE=$(curl -s -X POST http://localhost:8056/admin/users \
  -H "Content-Type: application/json" \
  -H "X-Admin-API-Key: token" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "max_concurrent_bots": 2
  }')

USER_ID=$(echo $USER_RESPONSE | jq -r '.id')
echo "Created user with ID: $USER_ID"

# Step 2: Generate API token
TOKEN_RESPONSE=$(curl -s -X POST http://localhost:8056/admin/users/${USER_ID}/tokens \
  -H "X-Admin-API-Key: token")

API_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.token')
echo "Generated token: $API_TOKEN"

# Step 3: Test user API access
curl -X GET "http://localhost:8056/meetings" \
  -H "X-API-Key: $API_TOKEN"
```

--------------------------------

### Install Vexa Python Client

Source: https://docs.vexa.ai/self-hosted-management

Install the Vexa Python client library using pip. This is required for using the Python examples.

```bash
pip install vexa-client
```

--------------------------------

### Install NVIDIA Container Toolkit for GPU Deployment

Source: https://docs.vexa.ai/deployment

Installs the NVIDIA Container Toolkit necessary for GPU acceleration. Ensure `nvidia-smi` works before proceeding.

```bash
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
```

```bash
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
```

```bash
sudo apt update && sudo apt install -y nvidia-container-toolkit
```

```bash
sudo nvidia-ctk runtime configure --runtime=docker
```

```bash
sudo systemctl restart docker
```

--------------------------------

### Kubernetes Helm Install and Upgrade

Source: https://docs.vexa.ai/scaling

Use these commands to install or upgrade Vexa using Helm charts. Ensure you have a `your-values.yaml` file configured for your deployment.

```bash
helm install vexa deploy/helm/charts/vexa \
  -f your-values.yaml \
  --namespace vexa --create-namespace
```

```bash
helm upgrade vexa deploy/helm/charts/vexa \
  -f your-values.yaml \
  --namespace vexa
```

--------------------------------

### Install Docker Engine and Compose Plugin (Ubuntu/Debian)

Source: https://docs.vexa.ai/deployment

Installs Docker Engine and the Compose V2 plugin on Ubuntu/Debian systems. This is a prerequisite for running Docker Compose.

```bash
# Prerequisites
sudo apt update && sudo apt install -y \
  python3 python3-pip python-is-python3 python3-venv \
  make git curl jq ca-certificates gnupg

# Docker Engine + Compose v2
sudo apt remove -y docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc || true
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update && sudo apt install -y \
  docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
```

--------------------------------

### Environment Variables Setup

Source: https://docs.vexa.ai/websocket

Sets up essential environment variables for the application, including API base URL, WebSocket URL, and API key.

```bash
export API_BASE="http://localhost:8056"
export WS_URL="ws://localhost:8056/ws"
export API_KEY="your_api_key_here"
```

--------------------------------

### Example Scoped Tokens

Source: https://docs.vexa.ai/token-scoping

Illustrates the format of scoped tokens for different access levels.

```text
vxa_bot_VDXyV683YBvsCRrlUtnWWKLC0qTtGNaxGgVS8F5s — bot scope
```

```text
vxa_tx_eFgh1234abcd5678... — transcription scope
```

```text
vxa_browser_xyz789... — browser scope
```

--------------------------------

### Complete Workflow Example via Python

Source: https://docs.vexa.ai/self-hosted-management

Demonstrates the full user and token management workflow using the Vexa Python client. It includes creating a user, generating a token, and then using a new client instance with the API key to access user-specific endpoints.

```python
from vexa_client import VexaClient

# Step 1: Create user
admin_client = VexaClient(base_url="http://localhost:8056", admin_key="token")

user = admin_client.create_user(
    email="newuser@example.com",
    name="New User",
    max_concurrent_bots=2
)
print(f"✓ Created user: {user['email']}")

# Step 2: Generate token
token_info = admin_client.create_token(user_id=user['id'])
api_token = token_info['token']
print(f"✓ Generated token: {api_token}")

# Step 3: Test user access
user_client = VexaClient(base_url="http://localhost:8056", api_key=api_token)
meetings = user_client.get_meetings()
print(f"✓ User API access working!")
```

--------------------------------

### Set up Local PostgreSQL Database

Source: https://docs.vexa.ai/vexa-lite-deployment

Create a Docker network and run a PostgreSQL container for Vexa Lite. This setup is for local development and requires Vexa Lite to be connected to the same network with the correct database host.

```bash
docker network create vexa-network

docker run -d \
  --name vexa-postgres \
  --network vexa-network \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=vexa \
  -p 5432:5432 \
  postgres:latest
```

--------------------------------

### Clone Vexa Repository and Build

Source: https://docs.vexa.ai/deployment

Clones the Vexa repository, copies the environment example, and builds the project. Ensure you are in the cloned directory for subsequent commands.

```bash
git clone https://github.com/Vexa-ai/vexa.git && cd vexa
```

```bash
cp deploy/env-example .env
```

```bash
make all
```

--------------------------------

### Clone Vexa and Set Up Environment Variables

Source: https://docs.vexa.ai/deployment

Clone the Vexa repository and copy the environment example file. You must edit the .env file to set your transcription service URL and token before building.

```bash
git clone https://github.com/Vexa-ai/vexa.git && cd vexa
cp deploy/env-example .env
# Edit .env — set TRANSCRIPTION_SERVICE_URL and TRANSCRIPTION_SERVICE_TOKEN
make all
```

--------------------------------

### Example Usage: Real-time Transcription Script

Source: https://docs.vexa.ai/websocket

Demonstrates how to run the real-time transcription script with basic and debug mode options. Requires setting environment variables beforehand.

```bash
# Basic usage
python testing/ws_realtime_transcription.py \
  --api-base http://localhost:8056 \
  --ws-url ws://localhost:8056/ws \
  --api-key $API_KEY \
  --platform google_meet \
  --native-id abc-defg-hij

# Debug mode (show raw frames)
python testing/ws_realtime_transcription.py \
  --api-base http://localhost:8056 \
  --ws-url ws://localhost:8056/ws \
  --api-key $API_KEY \
  --platform google_meet \
  --native-id abc-defg-hij \
  --raw
```

--------------------------------

### Example Log File Line

Source: https://docs.vexa.ai/websocket

Illustrates the format of a log file entry when the WebSocket messages are being recorded, useful for debugging message flow.

```log
2025-10-04T14:50:35.101823 - {"type": "transcript.mutable", "meeting": {"platform": "google_meet", "native_id": "tys-tztv-nrj"}, "payload": {"segments": [...]}, "ts": "2025-10-04T11:50:35.100142+00:00"}
```

--------------------------------

### Starting a Bot

Source: https://docs.vexa.ai/websocket

Initiates a transcription bot for a meeting. Requires the meeting bot to be running and active.

```APIDOC
## POST /bots

### Description
Starts a transcription bot for a meeting.

### Method
POST

### Endpoint
/bots

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.

#### Request Body
- **platform** (string) - Required - The platform of the meeting (e.g., `google_meet`, `teams`).
- **native_meeting_id** (string) - Required - The unique identifier for the meeting on its native platform.
- **passcode** (string) - Optional - The passcode for the meeting, required for platforms like Microsoft Teams.

### Request Example
```json
{
  "platform": "google_meet",
  "native_meeting_id": "your-meeting-id"
}
```

```json
{
  "platform": "teams",
  "native_meeting_id": "1234567890123",
  "passcode": "YOUR_PASSCODE"
}
```
```

--------------------------------

### GET /recording-config

Source: https://docs.vexa.ai/api/settings

Retrieves the current default recording configuration for the user.

```APIDOC
## GET /recording-config

### Description
Get your default recording configuration.

### Method
GET

### Endpoint
/recording-config

### Response
#### Success Response (200)
- **enabled** (bool) - Indicates if recording is enabled.
- **capture_modes** (string[]) - List of capture modes.

#### Response Example
{
  "enabled": true,
  "capture_modes": ["audio"]
}
```

--------------------------------

### Bot Creation Response (201)

Source: https://docs.vexa.ai/api/bots

Example of a successful bot creation response, including meeting details and status.

```json
{
  "id": 219,
  "user_id": 4,
  "platform": "google_meet",
  "native_meeting_id": "abc-defg-hij",
  "constructed_meeting_url": "https://meet.google.com/abc-defg-hij",
  "status": "requested",
  "bot_container_id": "d21c5b0c5275...c9fe9333",
  "start_time": null,
  "end_time": null,
  "data": {},
  "created_at": "2026-02-16T17:42:33.524137",
  "updated_at": "2026-02-16T17:42:33.535113"
}
```

--------------------------------

### Get Recording Configuration

Source: https://docs.vexa.ai/vexa-mcp

Retrieves the user's default recording settings.

```APIDOC
## GET /recording-config

### Description
Get the user's default recording settings.

### Method
GET

### Endpoint
/recording-config
```

--------------------------------

### Get Recording Configuration

Source: https://docs.vexa.ai/api/settings

Retrieve the current default recording settings for the user. This configuration applies to all new bots unless overridden.

```bash
curl -H "X-API-Key: $API_KEY" \
  "$API_BASE/recording-config"
```

--------------------------------

### Compare Environment Variables

Source: https://docs.vexa.ai/changelog

Use the diff command to compare your current .env file with the example provided in the deploy directory. This helps identify new or changed environment variables required for the new version.

```bash
diff .env deploy/env-example
```

--------------------------------

### macOS CPU-only Deployment Setup

Source: https://docs.vexa.ai/deployment

Sets up Vexa for macOS using CPU only. Requires Docker Desktop. Remember to edit the `.env` file to set `TRANSCRIPTION_SERVICE_URL`.

```bash
git clone https://github.com/Vexa-ai/vexa.git && cd vexa
```

```bash
cp deploy/env-example .env
```

```bash
# Edit .env — set TRANSCRIPTION_SERVICE_URL
```

```bash
make all
```

--------------------------------

### Make a User API Request with API Key

Source: https://docs.vexa.ai/authentication

Use the `X-API-Key` header for all user-facing API requests. Get your API key from vexa.ai/account.

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.cloud.vexa.ai/bots"
```

--------------------------------

### Paginate List Endpoints

Source: https://docs.vexa.ai/user_api_guide

Use 'limit' and 'offset' query parameters to control the number of items returned and the starting point for lists. Adjust 'limit' for desired page size and 'offset' to skip items.

```bash
GET /recordings?limit=50&offset=0
```

```bash
GET /meetings?limit=100&offset=0
```

--------------------------------

### Start Screen Share

Source: https://docs.vexa.ai/api/interactive-bots

Initiates a screen share within a meeting, allowing you to display images, web pages, videos, or custom HTML content to participants.

```APIDOC
## POST /bots/{platform}/{native_meeting_id}/screen

### Description
Show content via screen share. Content is rendered on an Xvfb display (1920x1080), then the bot starts presenting.

### Method
POST

### Endpoint
`/bots/{platform}/{native_meeting_id}/screen`

### Parameters
#### Path Parameters
- **platform** (string) - Required - The platform of the meeting (e.g., google_meet).
- **native_meeting_id** (string) - Required - The unique identifier for the meeting on the specified platform.

#### Request Body
- **type** (string) - Required - Content type: `image`, `url`, `video`, or `html`.
- **url** (string) - Required for `image`, `url`, `video` - The URL of the content to share.
- **html** (string) - Required for `html` - Raw HTML content to render.
- **start_share** (bool) - Optional - Defaults to `true`. Auto-starts screen sharing if not already active.

### Request Example
```json
{
  "type": "image",
  "url": "https://example.com/quarterly-chart.png"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the command was sent.
- **meeting_id** (integer) - Internal Vexa meeting ID.

#### Response Example
```json
{
  "message": "Screen content command sent",
  "meeting_id": 220
}
```

#### Validation Error (400)
- **detail** (string) - Error message indicating validation failure (e.g., invalid type).

#### Response Example
```json
{
  "detail": "type must be one of: image, video, url, html"
}
```
```

--------------------------------

### Running Bots Status Response (200)

Source: https://docs.vexa.ai/api/bots

Example response detailing the status of running bots, including container information and meeting IDs.

```json
{
  "running_bots": [
    {
      "container_id": "d21c5b0c5275...c9fe9333",
      "container_name": "vexa-bot-219-fd0a58fb",
      "platform": "google_meet",
      "native_meeting_id": "abc-defg-hij",
      "status": "Up 4 seconds",
      "normalized_status": "Up",
      "created_at": "2026-02-16T17:42:33+00:00",
      "labels": {
        "vexa.user_id": "4"
      },
      "meeting_id_from_name": "219"
    }
  ]
}
```

--------------------------------

### List All Users via curl

Source: https://docs.vexa.ai/self-hosted-management

Retrieve a list of all users with optional pagination parameters (skip and limit) by sending a GET request to the /admin/users endpoint. The X-Admin-API-Key header must be included.

```bash
curl -X GET "http://localhost:8056/admin/users?skip=0&limit=100" \
  -H "X-Admin-API-Key: token"
```

--------------------------------

### Set up PostgreSQL for Vexa Lite

Source: https://docs.vexa.ai/deployment

Creates a Docker network and runs a PostgreSQL container for Vexa Lite. Ensure you replace `your_password` with a strong password.

```bash
docker network create vexa-network
```

```bash
docker run -d \
  --name vexa-postgres \
  --network vexa-network \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=vexa \
  -p 5432:5432 \
  postgres:latest
```

--------------------------------

### Get User by Email via curl

Source: https://docs.vexa.ai/self-hosted-management

Retrieve user information by their email address using a GET request to the /admin/users/email/{email} endpoint. Requires the X-Admin-API-Key header.

```bash
curl -X GET "http://localhost:8056/admin/users/email/user@example.com" \
  -H "X-Admin-API-Key: token"
```

--------------------------------

### Get Chat Messages Response

Source: https://docs.vexa.ai/api/interactive-bots

To retrieve chat messages, a GET request is made to the chat endpoint. The API returns a 200 OK status with a JSON object containing an array of messages.

```json
{
  "messages": [...],
  "meeting_id": 220
}
```

--------------------------------

### Get User by ID via curl

Source: https://docs.vexa.ai/self-hosted-management

Fetch detailed user information, including API tokens, by their unique ID using a GET request to the /admin/users/{id} endpoint. The X-Admin-API-Key header is necessary.

```bash
curl -X GET "http://localhost:8056/admin/users/1" \
  -H "X-Admin-API-Key: token"
```

--------------------------------

### Run Vexa Lite with Local Database

Source: https://docs.vexa.ai/vexa-lite-deployment

Set up a local PostgreSQL database and then deploy Vexa Lite, connecting to the local database via a Docker network. The container automatically runs database migrations on startup.

```bash
# Create network
docker network create vexa-network

# Start PostgreSQL
docker run -d \
  --name vexa-postgres \
  --network vexa-network \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=vexa \
  -p 5432:5432 \
  postgres:latest

# Start Vexa Lite
docker run -d \
  --name vexa \
  --network vexa-network \
  -p 8056:8056 \
  -e DATABASE_URL="postgresql://postgres:your_password@vexa-postgres:5432/vexa" \
  -e ADMIN_API_TOKEN="your-secret-admin-token" \
  -e TRANSCRIPTION_SERVICE_URL="https://transcription.vexa.ai/v1/audio/transcriptions" \
  -e TRANSCRIPTION_SERVICE_TOKEN="your-transcription-api-key" \
  -e OPENAI_API_KEY="sk-your-openai-key" \
  vexaai/vexa-lite:latest
```

--------------------------------

### Get a specific recording

Source: https://docs.vexa.ai/user_api_guide

Retrieves details for a specific recording by its ID.

```APIDOC
## GET /recordings/{recording_id}

### Description
Retrieve details for a specific recording.

### Method
GET

### Endpoint
/recordings/{recording_id}

### Parameters
#### Path Parameters
- **recording_id** (string) - Required - The unique identifier for the recording.

### Response
#### Success Response (200)
- **recording_id** (string) - The unique identifier for the recording.
- **meeting_id** (string) - The identifier of the meeting associated with the recording.
- **start_time** (string) - The start time of the recording.
- **end_time** (string) - The end time of the recording.
- **media_files** (array) - Information about the media files associated with the recording.
```

--------------------------------

### Get Recording

Source: https://docs.vexa.ai/api/recordings

Retrieves a specific recording and its associated media files by its ID.

```APIDOC
## GET /recordings/{recording_id}

### Description
Get a recording and its `media_files`.

### Method
GET

### Endpoint
/recordings/{recording_id}

### Request Example
```bash
curl -H "X-API-Key: $API_KEY" \
  "$API_BASE/recordings/123456789"
```

### Response (200)
- **id** (integer) - The unique identifier for the recording.
- **meeting_id** (integer) - The ID of the meeting associated with the recording.
- **user_id** (integer) - The ID of the user who owns the recording.
- **session_uid** (string) - The unique identifier for the session.
- **source** (string) - The source of the recording (e.g., "bot").
- **status** (string) - The status of the recording (e.g., "completed").
- **error_message** (string) - An error message if the recording failed.
- **created_at** (string) - The timestamp when the recording was created.
- **completed_at** (string) - The timestamp when the recording was completed.
- **media_files** (array) - An array of media files associated with the recording.

### Response Example
```json
{
  "id": 906238426347,
  "meeting_id": 16,
  "user_id": 1,
  "session_uid": "d6e337d6-92cd-452f-b003-23c5498091ef",
  "source": "bot",
  "status": "completed",
  "error_message": null,
  "created_at": "2026-02-13T20:10:20Z",
  "completed_at": "2026-02-13T20:44:55Z",
  "media_files": [
    {
      "id": 906238426348,
      "type": "audio",
      "format": "wav",
      "storage_backend": "s3",
      "file_size_bytes": 1234567,
      "duration_seconds": 2079.2,
      "metadata": {
        "sample_rate": 16000
      },
      "created_at": "2026-02-13T20:44:55Z"
    }
  ]
}
```
```

--------------------------------

### Check Bot Status

Source: https://docs.vexa.ai/vexa-mcp

Retrieve the current status of all running bots. This is a simple GET request.

```json
GET /bot-status
```

--------------------------------

### Verify Vexa Services and API

Source: https://docs.vexa.ai/changelog

After rebuilding and restarting, use 'make ps' to check if all services are running. Then, use curl to test the API by accessing the documentation endpoint.

```bash
# Check services are running
make ps

# Quick API test
curl http://localhost:8056/docs
```

--------------------------------

### Build Vexa Lite Image from Source

Source: https://docs.vexa.ai/vexa-lite-deployment

Clone the Vexa repository and build the Vexa Lite Docker image locally using make commands. This process generates a 'vexa-lite:dev' image.

```bash
git clone https://github.com/Vexa-ai/vexa.git
cd vexa/deploy/lite
make build
```

--------------------------------

### Get User by Email

Source: https://docs.vexa.ai/self-hosted-management

Retrieves user information by their email address. Requires an Admin API Key.

```APIDOC
## GET /admin/users/email/{EMAIL}

### Description
Retrieve a user's information using their email address.

### Method
GET

### Endpoint
`http://localhost:8056/admin/users/email/{EMAIL}`

### Parameters
#### Path Parameters
- **EMAIL** (string) - Required - The email address of the user to retrieve.

### Headers
- `X-Admin-API-Key`: (string) Your admin API token

### Response
#### Success Response (200 OK)
- **id** (integer) - Unique identifier for the user
- **email** (string) - User's email address
- **name** (string) - User's display name
- **max_concurrent_bots** (integer) - Maximum concurrent bots allowed
- **created_at** (string) - Timestamp of user creation (ISO 8601 format)

#### Response Example
```json
{
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "max_concurrent_bots": 2,
  "created_at": "2025-10-10T12:00:00Z"
}
```
```

--------------------------------

### Create a User via Admin API

Source: https://docs.vexa.ai/authentication

For self-hosted deployments, create users using the Admin API. Ensure the `$ADMIN_TOKEN` environment variable is set.

```bash
# Create a user
curl -X POST "http://localhost:8056/admin/users" \
  -H "Content-Type: application/json" \
  -H "X-Admin-API-Key: $ADMIN_TOKEN" \
  -d '{"email": "user@example.com", "name": "User", "max_concurrent_bots": 5}'
```

--------------------------------

### Sort Segments by Start Time

Source: https://docs.vexa.ai/websocket

Sorts the processed transcript segments in ascending order based on their 'absolute_start_time'.

```python
sorted_segments = sorted(
    transcript_by_abs_start.values(),
    key=lambda s: s['absolute_start_time']
)
```

--------------------------------

### Render Custom HTML via Screen Share

Source: https://docs.vexa.ai/api/interactive-bots

Initiate a screen share to render custom HTML content. Requires the platform and native meeting ID.

```bash
curl -X POST "$API_BASE/bots/google_meet/abc-defg-hij/screen" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"type": "html", "html": "<h1>Quarterly Report</h1>"}'
```

--------------------------------

### Get Single Recording

Source: https://docs.vexa.ai/vexa-mcp

Retrieve a single recording along with its associated media files. Requires the recording ID.

```json
GET /recordings/{id}
```

--------------------------------

### List Recordings - Bash

Source: https://docs.vexa.ai/api/recordings

Use this command to list recordings for the authenticated user. Supports pagination with `limit` and `offset` parameters.

```bash
curl -H "X-API-Key: $API_KEY" \
  "$API_BASE/recordings?limit=50&offset=0"
```

--------------------------------

### Get Bot Status

Source: https://docs.vexa.ai/api/bots

Lists all bots currently running under your API key, providing their status and meeting details.

```APIDOC
## GET /bots/status

### Description
List bots currently running under your API key. This endpoint provides a summary of active bots, including their container ID, platform, meeting ID, status, and creation time.

### Method
GET

### Endpoint
/bots/status

### Response
#### Success Response (200)
Returns a JSON object containing a list of running bots. Each bot object includes `container_id`, `container_name`, `platform`, `native_meeting_id`, `status`, `normalized_status`, `created_at`, `labels`, and `meeting_id_from_name`.

#### Response Example
```json
{
  "running_bots": [
    {
      "container_id": "d21c5b0c5275...c9fe9333",
      "container_name": "vexa-bot-219-fd0a58fb",
      "platform": "google_meet",
      "native_meeting_id": "abc-defg-hij",
      "status": "Up 4 seconds",
      "normalized_status": "Up",
      "created_at": "2026-02-16T17:42:33+00:00",
      "labels": {
        "vexa.user_id": "4"
      },
      "meeting_id_from_name": "219"
    }
  ]
}
```
```

--------------------------------

### Get Recording by ID - Bash

Source: https://docs.vexa.ai/api/recordings

Retrieve a specific recording and its associated media files using its unique ID.

```bash
curl -H "X-API-Key: $API_KEY" \
  "$API_BASE/recordings/123456789"
```

--------------------------------

### GET /public/transcripts/{share_id}.txt

Source: https://docs.vexa.ai/api/transcripts

Access a shared transcript using its public URL. No authentication is required for this endpoint.

```APIDOC
## GET /public/transcripts/{share_id}.txt

### Description
Access a shared transcript. No authentication required.

### Method
GET

### Endpoint
`/public/transcripts/{share_id}.txt`

### Parameters
#### Path Parameters
- **share_id** (string) - Required - The share identifier obtained from the POST `/share` endpoint.

### Response
#### Success Response (200)
Returns plain text (`Content-Type: text/plain`) with the formatted transcript including platform, meeting ID, timestamps, and speaker-attributed segments.

#### Error Response (404)
Returned if the share link has expired or does not exist.
```

--------------------------------

### Get Meeting Telematics

Source: https://docs.vexa.ai/self-hosted-management

Fetch detailed telemetry for a specific meeting, including sessions, transcription stats, and performance metrics.

```bash
curl "http://localhost:8056/admin/analytics/meetings/218/telematics" \
  -H "X-Admin-API-Key: token"
```

--------------------------------

### Create Bot for Google Meet

Source: https://docs.vexa.ai/api/bots

Use this to create a bot for a Google Meet. Ensure transcription and recording are enabled as needed.

```bash
curl -X POST "$API_BASE/bots" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "platform": "google_meet",
    "native_meeting_id": "abc-defg-hij",
    "language": "en",
    "recording_enabled": true,
    "transcribe_enabled": true,
    "transcription_tier": "realtime"
  }'
```

--------------------------------

### Get Chat Messages

Source: https://docs.vexa.ai/api/interactive-bots

Retrieves all captured chat messages from a specific meeting. This endpoint is useful for auditing or analyzing conversation history.

```APIDOC
## GET /bots/{platform}/{native_meeting_id}/chat

### Description
Read all captured chat messages from the meeting.

### Method
GET

### Endpoint
`/bots/{platform}/{native_meeting_id}/chat`

### Parameters
#### Path Parameters
- **platform** (string) - Required - The platform of the meeting (e.g., google_meet).
- **native_meeting_id** (string) - Required - The unique identifier for the meeting on the specified platform.

### Response
#### Success Response (200)
- **messages** (array) - An array of chat message objects.
  - **sender** (string) - Participant name or bot name.
  - **text** (string) - The content of the message.
  - **timestamp** (number) - Unix timestamp of when the message was sent (in milliseconds).
  - **is_from_bot** (bool) - Indicates if the message was sent by a bot.
- **meeting_id** (integer) - Internal Vexa meeting ID.

### Response Example
```json
{
  "messages": [
    {
      "sender": "John Smith",
      "text": "Can you share the action items?",
      "timestamp": 1771268061761,
      "is_from_bot": false
    },
    {
      "sender": "AI Assistant",
      "text": "Here are the action items...",
      "timestamp": 1771268061885,
      "is_from_bot": true
    }
  ],
  "meeting_id": 220
}
```
```

--------------------------------

### Share Video via Screen Share

Source: https://docs.vexa.ai/api/interactive-bots

Initiate a screen share to play a video. The video plays fullscreen with autoplay. Requires the platform and native meeting ID.

```bash
curl -X POST "$API_BASE/bots/google_meet/abc-defg-hij/screen" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"type": "video", "url": "https://example.com/demo.mp4"}'
```

--------------------------------

### Get Paginated Meeting and User Stats

Source: https://docs.vexa.ai/self-hosted-management

Retrieve a paginated list of all meetings with embedded user details. Useful for overview dashboards.

```bash
curl "http://localhost:8056/admin/stats/meetings-users?skip=0&limit=100" \
  -H "X-Admin-API-Key: token"
```

--------------------------------

### Mount Local Volume for Recordings

Source: https://docs.vexa.ai/vexa-lite-deployment

Configure Vexa Lite to use a local Docker volume for storing recordings, suitable for local development environments.

```bash
docker run -d \
  -v vexa-recordings:/var/lib/vexa/recordings \
  ...
```

--------------------------------

### Set Environment Variables for API Access

Source: https://docs.vexa.ai/user_api_guide

Configure your shell environment with the API base URL and your API key. Use the provided localhost URL for local development or the cloud URL for production.

```bash
export API_BASE="http://localhost:8056"   # or https://api.cloud.vexa.ai
export API_KEY="YOUR_API_KEY_HERE"
```

--------------------------------

### Get recording media file

Source: https://docs.vexa.ai/user_api_guide

Streams a specific media file from a recording. Supports range requests for efficient playback and seeking.

```APIDOC
## GET /recordings/{recording_id}/media/{media_file_id}/raw

### Description
Stream a raw media file from a recording. Supports `Range` header for seeking.

### Method
GET

### Endpoint
/recordings/{recording_id}/media/{media_file_id}/raw

### Parameters
#### Path Parameters
- **recording_id** (string) - Required - The unique identifier for the recording.
- **media_file_id** (string) - Required - The unique identifier for the media file within the recording.

### Response
#### Success Response (206) Partial Content
- Returns the raw media file content. The `Content-Range` header indicates the portion of the file returned.
```

--------------------------------

### Get Bot Status

Source: https://docs.vexa.ai/api/bots

Retrieve the status of all bots currently running under your API key. This helps monitor active bot sessions.

```bash
curl -H "X-API-Key: $API_KEY" \
  "$API_BASE/bots/status"
```

--------------------------------

### Fetch Transcripts via REST API

Source: https://docs.vexa.ai/

Retrieve full transcript results using the GET /transcripts/{platform}/{native_meeting_id} endpoint.

```bash
GET /transcripts/{platform}/{native_meeting_id}
```

--------------------------------

### Set API Key and Base URL

Source: https://docs.vexa.ai/quickstart

Export your API base URL and API key as environment variables. Replace 'YOUR_API_KEY_HERE' with your actual Vexa Cloud API key.

```bash
export API_BASE="https://api.cloud.vexa.ai"
export API_KEY="YOUR_API_KEY_HERE"
```

--------------------------------

### Create Users and API Tokens

Source: https://docs.vexa.ai/getting-started

Use the Admin API to create users and mint API tokens for your self-hosted Vexa instance.

```APIDOC
## Create User

### Description
Creates a new user for the Vexa instance.

### Method
POST

### Endpoint
/admin/users

### Parameters
#### Request Body
- **email** (string) - Required - The email address of the user.
- **name** (string) - Required - The name of the user.
- **max_concurrent_bots** (integer) - Optional - The maximum number of concurrent bots the user can run.

### Request Example
```json
{
  "email": "user@example.com",
  "name": "User",
  "max_concurrent_bots": 2
}
```

## Generate API Token for User

### Description
Generates an API token for a specified user. This token should be saved securely as it cannot be retrieved later.

### Method
POST

### Endpoint
/admin/users/{user_id}/tokens

### Parameters
#### Path Parameters
- **user_id** (integer) - Required - The ID of the user for whom to generate the token.

### Response Example
(The token itself is returned in the response body, not shown here for brevity)

```

--------------------------------

### Get User by ID

Source: https://docs.vexa.ai/self-hosted-management

Retrieves detailed user information, including API tokens, by their user ID. Requires an Admin API Key.

```APIDOC
## GET /admin/users/{USER_ID}

### Description
Retrieve detailed user information, including API tokens, by their user ID.

### Method
GET

### Endpoint
`http://localhost:8056/admin/users/{USER_ID}`

### Parameters
#### Path Parameters
- **USER_ID** (integer) - Required - The ID of the user to retrieve.

### Headers
- `X-Admin-API-Key`: (string) Your admin API token

### Response
#### Success Response (200 OK)
- **id** (integer) - Unique identifier for the user
- **email** (string) - User's email address
- **name** (string) - User's display name
- **max_concurrent_bots** (integer) - Maximum concurrent bots allowed
- **created_at** (string) - Timestamp of user creation (ISO 8601 format)
- **tokens** (array) - List of API tokens associated with the user (may be empty)
  - **id** (integer) - Token ID
  - **token** (string) - The API token (masked or full depending on implementation)
  - **created_at** (string) - Timestamp of token creation (ISO 8601 format)

#### Response Example
```json
{
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "max_concurrent_bots": 2,
  "created_at": "2025-10-10T12:00:00Z",
  "tokens": [
    {
      "id": 1,
      "token": "AbCdEf1234567890AbCdEf1234567890AbCdEf12",
      "created_at": "2025-10-10T12:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Backend/Bot Runtime Environment Variables

Source: https://docs.vexa.ai/zoom-app-setup

Configure these variables for your Zoom bot's backend runtime.

```bash
ZOOM_CLIENT_ID=your_zoom_client_id
ZOOM_CLIENT_SECRET=your_zoom_client_secret
```

--------------------------------

### Rebuild Vexa Images and Run Migrations

Source: https://docs.vexa.ai/changelog

Execute this make command to rebuild all Docker images according to the new architecture and automatically apply database migrations. This is a crucial step after updating the code and environment variables.

```bash
make all
```

--------------------------------

### Share Screen Content via API

Source: https://docs.vexa.ai/interactive-bots

Initiate screen sharing for images, URLs, or videos. Use the DELETE method to stop sharing.

```bash
# Share an image
curl -X POST "$API_BASE/bots/google_meet/abc-defg-hij/screen" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"type": "image", "url": "https://example.com/chart.png"}'

# Share a Google Slides presentation
curl -X POST "$API_BASE/bots/google_meet/abc-defg-hij/screen" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"type": "url", "url": "https://docs.google.com/presentation/d/..."}'

# Stop sharing
curl -X DELETE "$API_BASE/bots/google_meet/abc-defg-hij/screen" \
  -H "X-API-Key: $API_KEY"
```

--------------------------------

### Access Bot Endpoint with Bot Scope

Source: https://docs.vexa.ai/token-scoping

This cURL example shows how to use a bot-scoped token to successfully access a bot status endpoint.

```bash
# This works — bot scope can access bot endpoints
curl -H "X-API-Key: vxa_bot_VDXyV683Y..." \
  https://your-vexa-host/bots/status
```

--------------------------------

### Send a bot to a meeting (Bash)

Source: https://docs.vexa.ai/interactive-bots

Enable interactive bot capabilities by setting `voice_agent_enabled: true` and then send a regular bot to a meeting. Ensure you have the API base URL and your API key set as environment variables.

```bash
curl -X POST "$API_BASE/bots" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "platform": "google_meet",
    "native_meeting_id": "abc-defg-hij",
    "bot_name": "AI Assistant"
  }'
```

--------------------------------

### Download Media File - Bash

Source: https://docs.vexa.ai/api/recordings

Obtain a presigned URL for downloading a media file from object storage. This URL is typically valid for a limited time.

```bash
curl -H "X-API-Key: $API_KEY" \
  "$API_BASE/recordings/123456789/media/987654321/download"
```

--------------------------------

### WebSocket Keepalive Ping Message

Source: https://docs.vexa.ai/websocket

Example of a JSON message sent by the client to keep the WebSocket connection alive. The server is expected to respond with 'pong'.

```json
{
  "action": "ping"
}
```

--------------------------------

### Create User via Python

Source: https://docs.vexa.ai/self-hosted-management

Use the VexaClient to create a user programmatically. Provide the base URL and admin key for authentication. The function returns a dictionary containing user details.

```python
from vexa_client import VexaClient

admin_client = VexaClient(
    base_url="http://localhost:8056",
    admin_key="token"
)

user = admin_client.create_user(
    email="user@example.com",
    name="John Doe",
    max_concurrent_bots=2
)

print(f"Created user: {user['email']} (ID: {user['id']})")
```

--------------------------------

### Typical Error Response

Source: https://docs.vexa.ai/errors-and-retries

Most validation and authentication errors return a JSON object with a human-readable 'detail' field. This example shows a common authentication error.

```json
{
  "detail": "Not authenticated"
}
```

--------------------------------

### Get Comprehensive User Details

Source: https://docs.vexa.ai/self-hosted-management

Retrieve detailed user analytics, including meeting stats and usage patterns. Can optionally include API token list.

```bash
curl "http://localhost:8056/admin/analytics/users/1/details?include_tokens=true" \
  -H "X-Admin-API-Key: token"
```

--------------------------------

### Configure Local Filesystem Storage

Source: https://docs.vexa.ai/recording-storage

Use this configuration for the local filesystem backend. Ensure LOCAL_STORAGE_DIR is set to the desired path within the container.

```env
STORAGE_BACKEND=local
LOCAL_STORAGE_DIR=/data/recordings
LOCAL_STORAGE_FSYNC=true
# Optional: bind host path instead of named volume
# LOCAL_STORAGE_VOLUME_SOURCE=./data/recordings
```

--------------------------------

### Get User by Email via Python

Source: https://docs.vexa.ai/self-hosted-management

Fetch a user's details using their email address with the VexaClient. The function returns a dictionary with user information.

```python
user = admin_client.get_user_by_email("user@example.com")
print(f"User ID: {user['id']}, Bots: {user['max_concurrent_bots']}")
```

--------------------------------

### Backup Vexa Database

Source: https://docs.vexa.ai/changelog

Use this command to create a compressed backup of your Vexa database before upgrading. Ensure 'your_vexa_db' is replaced with your actual database name.

```bash
pg_dump -Fc your_vexa_db > vexa-backup-pre-0.10.sql
```

--------------------------------

### Internal/Same-Account Zoom Bot Verification

Source: https://docs.vexa.ai/zoom-app-setup

Run this command to verify your Zoom bot setup for internal or same-account meetings. Ensure all required environment variables are set.

```bash
ZOOM_MEETING_URL="https://us05web.zoom.us/j/YOUR_MEETING_ID?pwd=YOUR_PASSWORD" \
ZOOM_CLIENT_ID="$ZOOM_CLIENT_ID" \
ZOOM_CLIENT_SECRET="$ZOOM_CLIENT_SECRET" \
./services/vexa-bot/run-zoom-bot.sh
```

--------------------------------

### Expose Local Server with ngrok

Source: https://docs.vexa.ai/local-webhook-development

Use ngrok to create a public HTTPS URL for your local development server running on port 3009.

```bash
ngrok http 3009
```

--------------------------------

### Attempt to Access Transcript Endpoint with Bot Scope

Source: https://docs.vexa.ai/token-scoping

This cURL example demonstrates that a bot-scoped token will fail with a 403 error when attempting to access a transcript endpoint.

```bash
# This fails with 403 — bot scope cannot access transcript endpoints
curl -H "X-API-Key: vxa_bot_VDXyV683Y..." \
  https://your-vexa-host/transcripts/google_meet/abc-defg-hij
```

--------------------------------

### Docker Compose Build Command

Source: https://docs.vexa.ai/scaling

Run this command in the Vexa directory to build all services for single-host development and testing using Docker Compose.

```bash
cd vexa
make all
```

--------------------------------

### Configure Vexa Lite for Local Testing (Local Filesystem)

Source: https://docs.vexa.ai/recording-storage

Configuration for Vexa Lite using the local filesystem backend, intended for testing only. Ensure LOCAL_STORAGE_DIR is set.

```env
STORAGE_BACKEND=local
LOCAL_STORAGE_DIR=/var/lib/vexa/recordings
LOCAL_STORAGE_FSYNC=true
```