Create Adhoc Session - Uplift AI API Docs

Example Request

JavaScript

React Example with Dynamic Config

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"
        }
      }
    }
  }'

// 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.\n                        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();

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

Response

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

Use Cases

Adhoc sessions are perfect for:

• A/B Testing — Test different configurations without creating multiple assistants
• Personalization — Create custom experiences based on user preferences
• Multi-language Support — Dynamic language selection per session
• Role-based Assistants — Different behaviors for different user types
• Temporary Demos — One-off demonstrations with specific settings
• Development — Quick testing of configurations before persisting

Benefits

• No need to create and manage multiple assistant configurations
• Instant configuration changes without database updates
• Perfect for dynamic, context-aware assistants
• Reduced storage overhead for temporary configurations

Limitations

Adhoc sessions are temporary and their configurations are not persisted. Each session requires the full configuration to be provided.

• Configuration must be complete (no partial configs)
• No configuration history or versioning
• Cannot be referenced by ID for future sessions
• May have different rate limits than persisted assistants

Configuration Examples

Customer Support with Dynamic Language

const config = {
  agent: {
    instructions: `You are a multilingual support agent.\n                  Respond in ${userLanguage}.`,
    tools: supportTools
  },
  stt: {
    default: {
      provider: 'deepgram',
      model: 'nova-3',
      language: userLanguage
    }
  },
  tts: {
    default: {
      provider: 'upliftai',
      voiceId: voiceForLanguage(userLanguage),
      outputFormat: 'MP3_22050_32'
    }
  },
  llm: {
    default: {
      provider: 'groq',
      model: 'llama-3.3-70b-versatile'
    }
  }
};

Educational Assistant with Grade Level

const config = {
  agent: {
    instructions: `You are a ${gradeLevel} teacher.\n                  Adapt your language and explanations to ${gradeLevel} students.`,
    initialGreeting: true,
    greetingInstructions: `Hello! I'm here to help you with your ${subject} homework.`
  },
  // ... rest of config
};