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.
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...
}
{
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDU0MDgyMDAsImlzcyI6IkFQSWFiY2RlZiIsImp0aSI6ImFkaG9jXzEyMyIsIm5hbWUiOiJUZXN0IFVzZXIiLCJyb29tIjoiYWRob2MtYWJjMTIzIiwic3ViIjoiYWRob2NfMTIzIiwidmlkZW8iOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJyb29tIjoiam9pbiJ9fQ.signature",
"wsUrl": "wss://upliftai-livekit-url...",
"roomName": "adhoc-abc123-1705406400"
}
API Reference (Beta)
Create Adhoc Session
Create a temporary session with custom configuration
POST
/
v1
/
realtime-assistants
/
adhoc
/
createSession
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.
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...
}
{
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDU0MDgyMDAsImlzcyI6IkFQSWFiY2RlZiIsImp0aSI6ImFkaG9jXzEyMyIsIm5hbWUiOiJUZXN0IFVzZXIiLCJyb29tIjoiYWRob2MtYWJjMTIzIiwic3ViIjoiYWRob2NfMTIzIiwidmlkZW8iOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJyb29tIjoiam9pbiJ9fQ.signature",
"wsUrl": "wss://upliftai-livekit-url...",
"roomName": "adhoc-abc123-1705406400"
}
Beta Feature: This endpoint is currently in beta. Features and specifications may change.
Adhoc sessions allow you to create temporary assistants with custom configurations without persisting them. Perfect for testing and dynamic use cases.
string
required
Display name for the user participant
string
Optional custom room name. If not provided, a unique room name will be generated
object
required
Complete assistant configuration for this session
Show See configuration options
Show See configuration options
Configuration structure is the same as in Create Assistant.
You must provide a complete configuration for the adhoc session.
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.
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...
}
{
"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.
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.
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
};
Related Endpoints
- Create Session - For persisted assistants
- Create Public Session - For public access
- Create Assistant - To persist configurations
⌘I
