Uplift AI

https://docs.upliftai.org
Admin
Uplift AI provides voice synthesis and speech-to-text APIs and SDKs to build voice-enabled...
Tokens:53,684
Snippets:396
Trust Score:6.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone the Demo Repository

Source: https://docs.upliftai.org/tutorials/livekit-voice-agent

Download the project files from GitHub to get started.

```bash
git clone https://github.com/uplift-initiative/livekit-demo
cd livekit-demo
```

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

### Initialize React Project and Install Dependencies

Source: https://docs.upliftai.org/assistants/tutorial

Commands to scaffold a new React application and install the required UpliftAI and LiveKit SDKs.

```bash
# Create a new React app
npx create-react-app voice-assistant-demo
cd voice-assistant-demo

# Install UpliftAI SDK and dependencies
npm install @upliftai/assistants-react @livekit/components-react livekit-client
```

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

### Start Development Server

Source: https://docs.upliftai.org/assistants/tutorial

Command to launch the local development environment.

```bash
npm start
```

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

### Install Uplift AI SDK

Source: https://docs.upliftai.org/sdk/nodejs/overview

Install the package via npm to begin using the SDK.

```bash
npm install @upliftai/sdk-js
```

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

### List Realtime Assistants Request

Source: https://docs.upliftai.org/assistants/api-reference/list-assistants

Use these examples to perform a GET request to retrieve the list of assistants. Ensure the Authorization header is set with a valid API key.

```bash
curl -X GET https://api.upliftai.org/v1/realtime-assistants \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript
const response = await fetch('https://api.upliftai.org/v1/realtime-assistants', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  }
});

const assistants = await response.json();
```

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

### Install Project Dependencies

Source: https://docs.upliftai.org/tutorials/livekit-voice-agent

Install all required Python packages for the LiveKit voice agent.

```bash
pip install "livekit-agents==1.5.1" "livekit-plugins-openai==1.5.1" "livekit-plugins-turn-detector==1.5.1" "livekit-plugins-upliftai==1.5.1" "livekit-plugins-silero==1.5.1" "python-socketio[asyncio]>=5.11.0" "aiohttp>=3.9.0" "python-dotenv>=1.0.0" "loguru>=0.7.0" "openai>=1.84.0"
```

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

### Create Public Session Request Examples

Source: https://docs.upliftai.org/assistants/api-reference/create-public-session

Examples showing how to initiate a public session using cURL, standard JavaScript fetch, and a React component.

```bash
curl -X POST https://api.upliftai.org/v1/realtime-assistants/550e8400-e29b-41d4-a716-446655440000/createPublicSession \
  -H "Content-Type: application/json" \
  -d '{
    "participantName": "Guest User"
  }'
```

```javascript
// Can be called directly from frontend for public assistants
const assistantId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.upliftai.org/v1/realtime-assistants/${assistantId}/createPublicSession`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      participantName: 'Guest User',
    })
  }
);

if (!response.ok) {
  if (response.status === 403) {
    throw new Error('This assistant is not public');
  }
  if (response.status === 404) {
    throw new Error('Assistant not found');
  }
  throw new Error('Failed to create session');
}

const sessionData = await response.json();
```

```jsx
import { useState } from 'react';
import { UpliftAIRoom } from '@upliftai/assistants-react';

function PublicAssistantDemo() {
  const [sessionData, setSessionData] = useState(null);
  const [loading, setLoading] = useState(false);
  
  const connectToAssistant = async () => {
    setLoading(true);
    try {
      const response = await fetch(
        'https://api.upliftai.org/v1/realtime-assistants/YOUR_PUBLIC_ASSISTANT_ID/createPublicSession',
        {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            participantName: 'Demo User'
          })
        }
      );
      
      const data = await response.json();
      setSessionData(data);
    } catch (error) {
      console.error('Failed to connect:', error);
    } finally {
      setLoading(false);
    }
  };
  
  if (!sessionData) {
    return (
      <button onClick={connectToAssistant} disabled={loading}>
        {loading ? 'Connecting...' : 'Connect to Assistant'}
      </button>
    );
  }
  
  return (
    <UpliftAIRoom
      token={sessionData.token}
      serverUrl={sessionData.wsUrl}
      connect={true}
      audio={true}
    >
      <YourAssistantUI />
    </UpliftAIRoom>
  );
}
```

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

### Create Session Request

Source: https://docs.upliftai.org/assistants/api-reference/create-session

Examples of how to initiate a session creation request from a backend environment.

```bash
curl -X POST https://api.upliftai.org/v1/realtime-assistants/550e8400-e29b-41d4-a716-446655440000/createSession \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participantName": "John Doe"
  }'
```

```javascript
const assistantId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.upliftai.org/v1/realtime-assistants/${assistantId}/createSession`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      participantName: 'John Doe',
      // roomName: 'custom-room-123' // optional
    })
  }
);

const sessionData = await response.json();

// Send sessionData to your frontend application
```

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

### Create a Realtime Assistant

Source: https://docs.upliftai.org/assistants/api-reference/create-assistant

Use these examples to initialize a new assistant with specific voice, language, and model configurations.

```bash
curl -X POST https://api.upliftai.org/v1/realtime-assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Assistant",
    "description": "24/7 voice support for customers",
    "public": false,
    "config": {
      "session": {
        "ttl": 3600,
        "roomPrefix": "support"
      },
      "agent": {
        "instructions": "You are a helpful customer support agent. Be friendly and professional.",
        "initialGreeting": true,
        "greetingInstructions": "Greet the customer and ask how you can help them today.",
        "tools": []
      },
      "stt": {
        "default": {
          "provider": "groq",
          "model": "whisper-large-v3",
          "language": "en"
        }
      },
      "tts": {
        "default": {
          "provider": "upliftai",
          "voiceId": "v_meklc281",
          "outputFormat": "MP3_22050_32"
        }
      },
      "llm": {
        "default": {
          "provider": "groq",
          "model": "openai/gpt-oss-120b"
        }
      }
    }
  }'
```

```javascript
const response = await fetch('https://api.upliftai.org/v1/realtime-assistants', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Customer Support Assistant',
    description: '24/7 voice support for customers',
    public: false,
    config: {
      agent: {
        instructions: 'You are a helpful customer support agent.',
        initialGreeting: true,
      },
      stt: {
        default: {
          provider: 'groq',
          model: 'whisper-large-v3',
        }
      },
      tts: {
        default: {
          provider: 'upliftai',
          voiceId: 'v_meklc281',
          outputFormat: 'MP3_22050_32',
        }
      },
      llm: {
        default: {
          provider: 'groq',
          model: 'openai/gpt-oss-120b',
        }
      }
    }
  })
});

const assistant = await response.json();
```

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

### Install React SDK dependencies

Source: https://docs.upliftai.org/assistants/sdk/react

Install the required packages for the UpliftAI React SDK and LiveKit components.

```bash
npm install @upliftai/assistants-react @livekit/components-react livekit-client
```

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

### Deploy Bot with ngrok

Source: https://docs.upliftai.org/tutorials/whatsapp-bot

Install ngrok and expose the local server to the internet for webhook testing.

```bash
# Install ngrok
npm install -g ngrok

# Start your server
node server.js

# In another terminal, expose it
ngrok http 3000

# Use the HTTPS URL for WhatsApp webhook
```

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

### Run Agent in Web Interface Mode

Source: https://docs.upliftai.org/tutorials

Starts the agent with a web interface, requiring LiveKit credentials.

```bash
python agent.py dev
```

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

### Retrieve Realtime Assistant Configuration

Source: https://docs.upliftai.org/assistants/api-reference/get-assistant

Use these examples to fetch assistant details via cURL or the Fetch API. Ensure the Authorization header is set with a valid API key.

```bash
curl -X GET https://api.upliftai.org/v1/realtime-assistants/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript
const assistantId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api.upliftai.org/v1/realtime-assistants/${assistantId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  }
});

const assistant = await response.json();
```

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

### GET /v1/realtime-assistants/{realtimeAssistantId}

Source: https://docs.upliftai.org/assistants/api-reference/get-assistant

Retrieve the configuration details for a specific realtime assistant.

```APIDOC
## GET /v1/realtime-assistants/{realtimeAssistantId}

### Description
Retrieve a specific realtime assistant configuration.

### Method
GET

### Endpoint
https://api.upliftai.org/v1/realtime-assistants/{realtimeAssistantId}

### Parameters
#### Path Parameters
- **realtimeAssistantId** (string) - Required - The unique identifier of the assistant

### Response
#### Success Response (200)
- **realtimeAssistantId** (string) - The unique identifier of the assistant
- **organizationId** (string) - The ID of the organization
- **projectId** (string) - The ID of the project
- **name** (string) - The name of the assistant
- **description** (string) - A description of the assistant
- **config** (object) - The configuration object containing session, agent, stt, tts, and llm settings
- **public** (boolean) - Whether the assistant is public
- **createdAt** (string) - Timestamp of creation
- **updatedAt** (string) - Timestamp of last update
- **createdBy** (string) - ID of the user who created the assistant
- **updatedBy** (string) - ID of the user who last updated the assistant

#### Response Example
{
  "realtimeAssistantId": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "org_123",
  "projectId": "proj_456",
  "name": "Customer Support Assistant",
  "description": "24/7 voice support for customers",
  "config": {
    "session": {
      "ttl": 3600,
      "roomPrefix": "support"
    },
    "agent": {
      "instructions": "You are a helpful customer support agent. Be friendly and professional.",
      "initialGreeting": true,
      "greetingInstructions": "Greet the customer and ask how you can help them today.",
      "tools": [
        {
          "name": "check_order_status",
          "description": "Check the status of a customer order",
          "parameters": {
            "type": "object",
            "properties": {
              "orderId": {
                "type": "string",
                "description": "The order ID to check"
              }
            },
            "required": ["orderId"]
          },
          "timeout": 10
        }
      ]
    },
    "stt": {
      "default": {
        "provider": "groq",
        "model": "whisper-large-v3",
        "language": "en"
      }
    },
    "tts": {
      "default": {
        "provider": "upliftai",
        "voiceId": "v_meklc281",
        "outputFormat": "MP3_22050_32"
      }
    },
    "llm": {
      "default": {
        "provider": "groq",
        "model": "openai/gpt-oss-120b"
      }
    }
  },
  "public": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:20:00Z",
  "createdBy": "user_789",
  "updatedBy": "user_789"
}
```

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

### Retrieve Audio via cURL and HTML

Source: https://docs.upliftai.org/api-reference/endpoint/stream-audio

Examples for fetching audio files directly via command line or embedding them into web applications.

```cURL
curl -X GET "https://api.upliftai.org/v1/synthesis/stream-audio/media_abc123xyz?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -o output.mp3
```

```HTML
<!-- Direct embedding in HTML -->
<audio controls>
  <source src="https://api.upliftai.org/v1/synthesis/stream-audio/media_abc123xyz?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." type="audio/mp3">
</audio>
```

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

### Create Adhoc Session Request

Source: https://docs.upliftai.org/assistants/api-reference/create-adhoc-session

Examples of how to initiate an adhoc session using cURL and JavaScript.

```bash
curl -X POST https://api.upliftai.org/v1/realtime-assistants/adhoc/createSession \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participantName": "Test User",
    "config": {
      "session": {
        "ttl": 1800
      },
      "agent": {
        "instructions": "You are a specialized assistant for this specific session.",
        "initialGreeting": true,
        "greetingInstructions": "Welcome! This is a custom session.",
        "tools": []
      },
      "stt": {
        "default": {
          "provider": "groq",
          "model": "whisper-large-v3",
          "language": "en"
        }
      },
      "tts": {
        "default": {
          "provider": "upliftai",
          "voiceId": "john",
          "outputFormat": "MP3_22050_32"
        }
      },
      "llm": {
        "default": {
          "provider": "groq",
          "model": "openai/gpt-oss-120b"
        }
      }
    }
  }'
```

```javascript
// Create an adhoc session with custom configuration
const response = await fetch(
  'https://api.upliftai.org/v1/realtime-assistants/adhoc/createSession',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      participantName: 'Test User',
      config: {
        session: {
          ttl: 1800 // 30 minutes
        },
        agent: {
          instructions: `You are a specialized math tutor. 
                        Help students solve math problems step by step.`,
          initialGreeting: true,
          greetingInstructions: 'Hello! I\'m your math tutor. What would you like to work on today?',
          tools: [
            {
              name: 'solve_equation',
              description: 'Solve mathematical equations',
              parameters: {
                type: 'object',
                properties: {
                  equation: {
                    type: 'string',
                    description: 'The equation to solve'
                  }
                },
                required: ['equation']
              },
              timeout: 5
            }
          ]
        },
        stt: {
          default: {
            provider: 'groq',
            model: 'whisper-large-v3',
            language: 'en'
          }
        },
        tts: {
          default: {
            provider: 'upliftai',
            voiceId: 'v_meklc281',
            outputFormat: 'MP3_22050_32'
          }
        },
        llm: {
          default: {
            provider: 'groq',
            model: 'openai/gpt-oss-120b',
            apiKey: 'YOUR_OPENAI_KEY' // Optional if using your own key
          }
        }
      }
    })
  }
);

const sessionData = await response.json();
```

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

### Test WebSocket TTS with wscat

Source: https://docs.upliftai.org/websocket-tts

Use this command to install the wscat utility, establish a connection to the TTS endpoint, and send a synthesis request.

```bash
# Install wscat
npm install -g wscat

# Connect
wscat -c wss://api.upliftai.org/text-to-speech/multi-stream \
  -H "Authorization: Bearer sk_api_your_key"

# Send synthesize message
{"type":"synthesize","requestId":"test-1","text":"Hello world","voiceId":"v_meklc281"}
```

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

### Update Realtime Assistant Request

Source: https://docs.upliftai.org/assistants/api-reference/update-assistant

Examples of how to send a POST request to update an assistant's configuration using cURL or JavaScript.

```bash
curl -X POST https://api.upliftai.org/v1/realtime-assistants/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enhanced Support Assistant",
    "config": {
      "agent": {
        "instructions": "You are an expert customer support agent. Provide detailed and helpful responses.",
        "tools": [
          {
            "name": "check_order_status",
            "description": "Check the status of a customer order",
            "parameters": {
              "type": "object",
              "properties": {
                "orderId": {
                  "type": "string",
                  "description": "The order ID"
                }
              },
              "required": ["orderId"]
            },
            "timeout": 10
          }
        ]
      }
    }
  }'
```

```javascript
const assistantId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api.upliftai.org/v1/realtime-assistants/${assistantId}`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Enhanced Support Assistant',
    config: {
      agent: {
        instructions: 'You are an expert customer support agent. Provide detailed and helpful responses.',
        tools: [
          {
            name: 'check_order_status',
            description: 'Check the status of a customer order',
            parameters: {
              type: 'object',
              properties: {
                orderId: {
                  type: 'string',
                  description: 'The order ID'
                }
              },
              required: ['orderId']
            },
            timeout: 10
          }
        ]
      }
    }
  })
});

const updatedAssistant = await response.json();
```

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

### JavaScript Text to Speech Streaming

Source: https://docs.upliftai.org/api-reference/endpoint/text-to-speech-stream

Example implementation using the Fetch API to stream audio synthesis from the UpliftAI endpoint.

```javascript
async function streamTextToSpeech() {
  try {
    const response = await fetch('https://api.upliftai.org/v1/synthesis/text-to-speech/stream', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({
        voiceId: "v_8eelc901",
        text: "سلام، آپ اِس وقت اوریٹر کی آواز سن رہے ہیں۔",
        outputFormat: "MP3_22050_128"
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
```

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

### DisplayAudio Component Usage

Source: https://docs.upliftai.org/orator

Examples of implementing the DisplayAudio component with specific audio source URLs for different voice profiles.

```jsx
<DisplayAudio audio_url="https://d3bh4trxpt2avf.cloudfront.net/voice_15_line_intercept_example.mp3" />
```

```jsx
<DisplayAudio audio_url="https://d3bh4trxpt2avf.cloudfront.net/voa_f17.mp3" />
```

```jsx
<DisplayAudio audio_url="https://d3bh4trxpt2avf.cloudfront.net/daastan_surah.mp3" />
```

```jsx
<DisplayAudio audio_url="https://d3bh4trxpt2avf.cloudfront.net/coral_sugar.mp3" />
```

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

### Synthesize Text-to-Speech via REST API

Source: https://docs.upliftai.org/

Examples for generating audio from text using cURL, JavaScript, and Python. Requires a valid API key for authorization.

```bash
curl -X POST https://api.upliftai.org/v1/synthesis/text-to-speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceId": "v_8eelc901",
    "text": "Hello, this is a test",
    "outputFormat": "MP3_22050_128"
  }' \
  --output test.mp3
```

```javascript
const response = await fetch('https://api.upliftai.org/v1/synthesis/text-to-speech', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    voiceId: 'v_8eelc901',
    text: 'Hello, this is a test',
    outputFormat: 'MP3_22050_128'
  })
});

const audioBlob = await response.blob();
// Play or save the audio
```

```python
import requests

response = requests.post(
  'https://api.upliftai.org/v1/synthesis/text-to-speech',
  headers={
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  json={
    'voiceId': 'v_8eelc901',
    'text': 'Hello, this is a test',
    'outputFormat': 'MP3_22050_128'
  }
)

with open('output.mp3', 'wb') as f:
  f.write(response.content)
```

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

### Speech to Text API Response Example

Source: https://docs.upliftai.org/api-reference/endpoint/speech-to-text

Example JSON response returned by the speech-to-text transcription endpoint.

```json
{
  "text": "آج کا موسم کیسا ہے؟ میں نے سنا ہے کہ بارش ہونے والی ہے۔"
}
```

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

### Initiate Async TTS with Python

Source: https://docs.upliftai.org/api-reference/endpoint/text-to-speech-async

Demonstrates how to trigger the asynchronous synthesis process and capture the resulting media credentials.

```python
import requests
import json

# Step 1: Initiate async TTS
url = "https://api.upliftai.org/v1/synthesis/text-to-speech-async"

payload = json.dumps({
  "voiceId": "v_meklc281",
  "text": "سلام، یہ پاکستان کی تاریخ کے بارے میں ہے۔",
  "outputFormat": "MP3_22050_128"
})

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(url, headers=headers, data=payload)
result = response.json()

# Step 2: Retrieve audio when ready
media_id = result['mediaId']
token = result['token']
```

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

### Get Phrase Replacement Config OpenAPI Definition

Source: https://docs.upliftai.org/api-reference/endpoint/get-phrase-replacement-config

The OpenAPI specification for the GET request to retrieve a phrase replacement configuration.

```yaml
openapi: 3.1.0
info:
  title: UpliftAI API
  version: 1.0.0
  description: >
    API for UpliftAI messaging, media handling, and text-to-speech capabilities.
    This API enables real-time communication

    with AI assistants, supporting various content types including text, images,

    audio,

    and documents. It provides both synchronous and asynchronous messaging

    capabilities

    with webhook support for real-time updates. The API also supports

    text-to-speech synthesis

    and phrase replacement configuration.
servers:
  - url: https://api.upliftai.org/v1
    description: Version 1 API
security: []
paths:
  /synthesis/phrase-replacement-config/{configId}:
    get:
      summary: Get Phrase Replacement Config
      description: |
        <b>Get a specific phrase replacement configuration</b>

        Retrieves a specific phrase replacement configuration by its ID.
      parameters:
        - in: path
          name: configId
          required: true
          schema:
            type: string
          description: ID of the configuration to retrieve
      responses:
        '200':
          description: Successful retrieval of configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhraseReplacementConfigResponse'
        '404':
          description: Configuration not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Rate limit exceeded, please try again later
      security:
        - apiKeyAuth: []
components:
  schemas:
    PhraseReplacementConfigResponse:
      type: object
      required:
        - configId
        - phraseReplacements
      description: Response containing phrase replacement configuration
      properties:
        configId:
          type: string
          description: Unique identifier for the configuration
        phraseReplacements:
          type: array
          description: Array of phrase replacement rules
          items:
            $ref: '#/components/schemas/PhraseReplacement'
    PhraseReplacement:
      type: object
      required:
        - phrase
        - replacement
      description: Configuration for how to replace specific phrases
      properties:
        phrase:
          type: string
          maxLength: 50
          description: Original phrase to be replaced
        replacement:
          type: string
          maxLength: 50
          description: Text to use as replacement
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key with format "Bearer sk_api_..."
```

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

### Create an Assistant via API

Source: https://docs.upliftai.org/assistants/introduction

Configures a new assistant with specific instructions, STT, TTS, and LLM provider settings.

```bash
curl -X POST https://api.upliftai.org/v1/realtime-assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dream Psychologist",
    "description": "Understands the mysterious world of your dreams",
    "config": {
      "agent": {
        "instructions": "You are a dream interpreter who helps people understand their dreams.",
        "initialGreeting": true,
        "greetingInstructions": "Salam! How may I assist you today?"
      },
      "stt": {
        "default": {
          "provider": "groq",
          "model": "whisper-large-v3",
          "language": "en"
        }
      },
      "tts": {
        "default": {
          "provider": "upliftai",
          "voiceId": "v_meklc281",
          "outputFormat": "MP3_22050_32"
        }
      },
      "llm": {
        "default": {
          "provider": "groq",
          "model": "openai/gpt-oss-120b"
        }
      },
      "session": {
        "ttl": 1800
      }
    }
  }'
```

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

### GET /v1/realtime-assistants

Source: https://docs.upliftai.org/assistants/api-reference/list-assistants

Retrieves a list of all realtime assistants associated with the authenticated organization.

```APIDOC
## GET /v1/realtime-assistants

### Description
List all realtime assistants in your organization.

### Method
GET

### Endpoint
https://api.upliftai.org/v1/realtime-assistants

### Response
#### Success Response (200)
- **realtimeAssistantId** (string) - Unique identifier for the assistant
- **organizationId** (string) - ID of the organization
- **projectId** (string) - ID of the project
- **name** (string) - Name of the assistant
- **description** (string) - Description of the assistant
- **config** (object) - Configuration object for session, agent, stt, tts, and llm settings
- **public** (boolean) - Whether the assistant is public
- **createdAt** (string) - ISO timestamp of creation
- **updatedAt** (string) - ISO timestamp of last update
- **createdBy** (string) - User ID who created the assistant
- **updatedBy** (string) - User ID who last updated the assistant

#### Response Example
[
  {
    "realtimeAssistantId": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org_123",
    "projectId": "proj_456",
    "name": "Customer Support Assistant",
    "description": "24/7 voice support for customers",
    "config": {
      "session": {
        "ttl": 3600,
        "roomPrefix": "support"
      },
      "agent": {
        "instructions": "You are a helpful customer support agent.",
        "initialGreeting": true,
        "tools": []
      },
      "stt": {
        "default": {
          "provider": "groq",
          "model": "whisper-large-v3",
          "language": "en"
        }
      },
      "tts": {
        "default": {
          "provider": "upliftai",
          "voiceId": "v_meklc281",
          "outputFormat": "MP3_22050_32"
        }
      },
      "llm": {
        "default": {
          "provider": "groq",
          "model": "openai/gpt-oss-120b"
        }
      }
    },
    "public": false,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "createdBy": "user_789",
    "updatedBy": "user_789"
  }
]
```

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

### GET /synthesis/phrase-replacement-config/{configId}

Source: https://docs.upliftai.org/api-reference/endpoint/get-phrase-replacement-config

Retrieves a specific phrase replacement configuration by its ID.

```APIDOC
## GET /synthesis/phrase-replacement-config/{configId}

### Description
Retrieves a specific phrase replacement configuration by its ID.

### Method
GET

### Endpoint
/synthesis/phrase-replacement-config/{configId}

### Parameters
#### Path Parameters
- **configId** (string) - Required - ID of the configuration to retrieve

### Response
#### Success Response (200)
- **configId** (string) - Unique identifier for the configuration
- **phraseReplacements** (array) - Array of phrase replacement rules

#### Error Responses
- **404** - Configuration not found
- **429** - Rate limit exceeded
```

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

### Run Agent in Console Mode

Source: https://docs.upliftai.org/tutorials

Starts the agent in terminal-based interactive mode.

```bash
python agent.py console
```

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

### Configure Environment Variables

Source: https://docs.upliftai.org/tutorials/whatsapp-bot

Define necessary API keys and server settings in a .env file.

```bash
# WhatsApp Configuration
WHATSAPP_ACCESS_TOKEN=your_whatsapp_token
PHONE_NUMBER_ID=your_phone_number_id
WEBHOOK_VERIFY_TOKEN=your_custom_verify_token

# Uplift AI Configuration
UPLIFT_API_KEY=sk_api_your_uplift_key

# Server Configuration
PORT=3000
```

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

### Get a specific configuration

Source: https://docs.upliftai.org/sdk/nodejs/phrase-replacements

Fetches details for a specific configuration using its unique ID.

```typescript
const config = await client.tts.phraseReplacements.get('config_abc123');
```

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

### Initiate TTS and Retrieve Audio via JavaScript

Source: https://docs.upliftai.org/api-reference/endpoint/text-to-speech-async

Demonstrates the asynchronous request flow and the construction of the audio stream URL.

```javascript
// Server-side: Initiate TTS
            async function initiateTTS() {
              const response = await fetch('https://api.upliftai.org/v1/synthesis/text-to-speech-async', {
                method: 'POST',
                headers: {
                  'Content-Type': 'application/json',
                  'Authorization': 'Bearer YOUR_API_KEY'
                },
                body: JSON.stringify({
                  voiceId: "v_meklc281",
                  text: "سلام، یہ پاکستان کی تاریخ کے بارے میں ہے۔",
                  outputFormat: "MP3_22050_128"
                })
              });
              
              const { mediaId, token } = await response.json();
              
              // Send URL to client or webhook
              const audioUrl = `https://api.upliftai.org/v1/synthesis/stream-audio/${mediaId}?token=${token}`;
              
              // Client can now fetch audio directly
              return audioUrl;
            }
```

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

### Initiate Async Streaming TTS in Python

Source: https://docs.upliftai.org/api-reference/endpoint/text-to-speech-stream-async

Demonstrates how to request streaming synthesis and construct the audio stream URL using the returned mediaId and token.

```python
import requests
import json

# Step 1: Initiate streaming async TTS
url = "https://api.upliftai.org/v1/synthesis/text-to-speech/stream-async"

payload = json.dumps({
  "voiceId": "v_meklc281",
  "text": "سلام، یہ پاکستان کی تاریخ کے بارے میں ہے۔",
  "outputFormat": "MP3_22050_128"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(url, headers=headers, data=payload)
result = response.json()

# Step 2: Stream audio with ~300ms first chunk
media_id = result['mediaId']
token = result['token']

audio_url = f"https://api.upliftai.org/v1/synthesis/stream-audio/{media_id}?token={token}"
```

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

### GET /synthesis/phrase-replacement-config

Source: https://docs.upliftai.org/api-reference/endpoint/list-phrase-replacement-configs

Retrieves a list of all phrase replacement configurations for the current organization and project.

```APIDOC
## GET /synthesis/phrase-replacement-config

### Description
Returns a list of all phrase replacement configurations for the current organization and project.

### Method
GET

### Endpoint
/synthesis/phrase-replacement-config

### Response
#### Success Response (200)
- **configId** (string) - Unique identifier for the configuration
- **phraseReplacements** (array) - Array of phrase replacement rules

#### Response Example
[
  {
    "configId": "config_123",
    "phraseReplacements": [
      {
        "phrase": "old_phrase",
        "replacement": "new_phrase"
      }
    ]
  }
]
```

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

### Get voice assistant state

Source: https://docs.upliftai.org/assistants/sdk/react

Retrieves the current state and participant information for the voice assistant.

```javascript
const { state, participant } = useVoiceAssistant();

// state: 'listening' | 'thinking' | 'speaking'
```

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

### Download Required Model Files

Source: https://docs.upliftai.org/tutorials/livekit-voice-agent

Execute this command to fetch the necessary model dependencies for the voice agent.

```bash
python agent.py download-files
```

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

### Adhoc Session API Response

Source: https://docs.upliftai.org/assistants/api-reference/create-adhoc-session

Example of the JSON response returned after successfully creating an adhoc session.

```json
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDU0MDgyMDAsImlzcyI6IkFQSWFiY2RlZiIsImp0aSI6ImFkaG9jXzEyMyIsIm5hbWUiOiJUZXN0IFVzZXIiLCJyb29tIjoiYWRob2MtYWJjMTIzIiwic3ViIjoiYWRob2NfMTIzIiwidmlkZW8iOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJyb29tIjoiam9pbiJ9fQ.signature",
  "wsUrl": "wss://upliftai-livekit-url...",
  "roomName": "adhoc-abc123-1705406400"
}
```

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

### Verify Project Directory Structure

Source: https://docs.upliftai.org/tutorials/livekit-voice-agent

Ensure the project directory contains the .env file and agent.py script in the same location.

```text
your-project-folder/
├── .env                 # Your API keys
└── agent.py             # The voice agent code
```

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

### Create Adhoc Session with Dynamic Configuration

Source: https://docs.upliftai.org/assistants/api-reference/create-adhoc-session

Demonstrates building a dynamic configuration object based on user context and sending it to the UpliftAI API endpoint.

```jsx
import { useState } from 'react';
import { UpliftAIRoom } from '@upliftai/assistants-react';

function DynamicAssistant({ userRole, language }) {
  const [sessionData, setSessionData] = useState(null);
  
  const createCustomSession = async () => {
    // Build dynamic configuration based on user context
    const config = {
      agent: {
        instructions: userRole === 'student' 
          ? 'You are a patient tutor. Explain concepts simply.'
          : 'You are a professional consultant. Provide expert advice.',
        initialGreeting: true
      },
      stt: {
        default: {
          provider: 'groq',
          model: 'whisper-large-v3',
          language: language // Dynamic language selection
        }
      },
      tts: {
        default: {
          provider: 'upliftai',
          voiceId: language === 'es' ? 'maria' : 'john',
          outputFormat: 'MP3_22050_32'
        }
      },
      llm: {
        default: {
          provider: 'groq',
          model: 'openai/gpt-oss-120b'
        }
      }
    };
    
    const response = await fetch(
      'https://api.upliftai.org/v1/realtime-assistants/adhoc/createSession',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          participantName: 'User',
          config
        })
      }
    );
    
    const data = await response.json();
    setSessionData(data);
  };
  
  // Rest of component...
}
```

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

### Delete Realtime Assistant Request

Source: https://docs.upliftai.org/assistants/api-reference/delete-assistant

Examples for deleting an assistant using cURL and the JavaScript Fetch API.

```bash
curl -X DELETE https://api.upliftai.org/v1/realtime-assistants/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript
const assistantId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api.upliftai.org/v1/realtime-assistants/${assistantId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  }
});

if (response.status === 204) {
  console.log('Assistant deleted successfully');
}
```

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

### POST /v1/realtime-assistants

Source: https://docs.upliftai.org/assistants/api-reference/create-assistant

Creates a new realtime assistant with the specified configuration.

```APIDOC
## POST /v1/realtime-assistants

### Description
Creates a new realtime assistant instance for your project.

### Method
POST

### Endpoint
https://api.upliftai.org/v1/realtime-assistants

### Request Body
- **name** (string) - Required - The name of the assistant.
- **description** (string) - Optional - A brief description of the assistant.
- **public** (boolean) - Optional - Whether the assistant is public.
- **config** (object) - Required - Configuration object containing session, agent, stt, tts, and llm settings.

### Request Example
{
  "name": "Customer Support Assistant",
  "description": "24/7 voice support for customers",
  "public": false,
  "config": {
    "session": {
      "ttl": 3600,
      "roomPrefix": "support"
    },
    "agent": {
      "instructions": "You are a helpful customer support agent.",
      "initialGreeting": true
    },
    "stt": {
      "default": {
        "provider": "groq",
        "model": "whisper-large-v3"
      }
    },
    "tts": {
      "default": {
        "provider": "upliftai",
        "voiceId": "v_meklc281",
        "outputFormat": "MP3_22050_32"
      }
    },
    "llm": {
      "default": {
        "provider": "groq",
        "model": "openai/gpt-oss-120b"
      }
    }
  }
}

### Response
#### Success Response (200)
- **realtimeAssistantId** (string) - Unique identifier for the assistant.
- **organizationId** (string) - ID of the organization.
- **projectId** (string) - ID of the project.
- **name** (string) - Name of the assistant.
- **description** (string) - Description of the assistant.
- **config** (object) - The configuration object.
- **public** (boolean) - Public status.
- **createdAt** (string) - Creation timestamp.
- **updatedAt** (string) - Last update timestamp.
- **createdBy** (string) - User ID who created the assistant.
- **updatedBy** (string) - User ID who last updated the assistant.

#### Response Example
{
  "realtimeAssistantId": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "org_123",
  "projectId": "proj_456",
  "name": "Customer Support Assistant",
  "description": "24/7 voice support for customers",
  "config": {
    "session": {
      "ttl": 3600,
      "roomPrefix": "support"
    },
    "agent": {
      "instructions": "You are a helpful customer support agent. Be friendly and professional.",
      "initialGreeting": true,
      "greetingInstructions": "Greet the customer and ask how you can help them today.",
      "tools": []
    },
    "stt": {
      "default": {
        "provider": "groq",
        "model": "whisper-large-v3",
        "language": "en"
      }
    },
    "tts": {
      "default": {
        "provider": "upliftai",
        "voiceId": "v_meklc281",
        "outputFormat": "MP3_22050_32"
      }
    },
    "llm": {
      "default": {
        "provider": "groq",
        "model": "openai/gpt-oss-120b"
      }
    }
  },
  "public": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "createdBy": "user_789",
  "updatedBy": "user_789"
}
```
Tokens:
Raw