Skip to main content
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"
        }
      }
    }
  }'

{
  "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.
​
participantName
string
required
Display name for the user participant
​
roomName
string
Optional custom room name. If not provided, a unique room name will be generated
​
config
object
required
Complete assistant configuration for this 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"
        }
      }
    }
  }'

{
  "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
};