> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upliftai.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Adhoc Session

> Create a temporary session with custom configuration

<Note>
  **Beta Feature**: This endpoint is currently in beta. Features and specifications may change.
</Note>

<Info>
  Adhoc sessions allow you to create temporary assistants with custom configurations without persisting them. Perfect for testing and dynamic use cases.
</Info>

<ParamField body="participantName" type="string" required>
  Display name for the user participant
</ParamField>

<ParamField body="roomName" type="string">
  Optional custom room name. If not provided, a unique room name will be generated
</ParamField>

<ParamField body="config" type="object" required>
  Complete assistant configuration for this session

  <Expandable title="See configuration options">
    Configuration structure is the same as in [Create Assistant](/assistants/api-reference/create-assistant).
    You must provide a complete configuration for the adhoc session.
  </Expandable>
</ParamField>

<RequestExample>
  ```bash Example Request theme={null}
  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 JavaScript theme={null}
  // 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();
  ```

  ```jsx React Example with Dynamic Config theme={null}
  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...
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDU0MDgyMDAsImlzcyI6IkFQSWFiY2RlZiIsImp0aSI6ImFkaG9jXzEyMyIsIm5hbWUiOiJUZXN0IFVzZXIiLCJyb29tIjoiYWRob2MtYWJjMTIzIiwic3ViIjoiYWRob2NfMTIzIiwidmlkZW8iOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJyb29tIjoiam9pbiJ9fQ.signature",
    "wsUrl": "wss://upliftai-livekit-url...",
    "roomName": "adhoc-abc123-1705406400"
  }
  ```
</ResponseExample>

## 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

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

* 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

```javascript theme={null}
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

```javascript theme={null}
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](/assistants/api-reference/create-session) - For persisted assistants
* [Create Public Session](/assistants/api-reference/create-public-session) - For public access
* [Create Assistant](/assistants/api-reference/create-assistant) - To persist configurations