> ## 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. # Start a session from inline config > Identical to [Create a web session token](/api-reference/starting-a-conversation/create-a-web-session-token) — you get a LiveKit `wsUrl` and token, and everything on that page applies. The difference: the assistant is created on the fly from the `config` you send, instead of using a stored id. It stays hidden from the stored-assistant routes and **is gone five hours later**. The inline `config` follows the same rules as [Create an assistant](/api-reference/assistants/create-an-assistant): provider and model strings resolve when the client connects, so an unsupported value kills that conversation rather than failing this request. For Urdu, tell the model to reply in Nastaliq script, not Roman Urdu. ## OpenAPI ````yaml /voice-agents/api-reference/openapi.yaml post /realtime-assistants/adhoc/session openapi: 3.1.0 info: title: UpliftAI Voice Agents API version: '1.0' description: >- Build voice assistants, start conversations on the web or the phone, run calling campaigns, and receive outcomes by webhook. All endpoints take a bearer API key unless noted otherwise. servers: - url: https://api.upliftai.org/v1 security: - apiKey: [] tags: - name: Assistants - name: Authoring an assistant - name: Starting a conversation - name: Sessions & call records - name: Campaigns - name: Campaign outcomes - name: Contacts - name: Google Sheet sources - name: Integrations & delivery health paths: /realtime-assistants/adhoc/session: post: tags: - Starting a conversation summary: Start a session from inline config description: >- Identical to [Create a web session token](/api-reference/starting-a-conversation/create-a-web-session-token) — you get a LiveKit `wsUrl` and token, and everything on that page applies. The difference: the assistant is created on the fly from the `config` you send, instead of using a stored id. It stays hidden from the stored-assistant routes and **is gone five hours later**. The inline `config` follows the same rules as [Create an assistant](/api-reference/assistants/create-an-assistant): provider and model strings resolve when the client connects, so an unsupported value kills that conversation rather than failing this request. For Urdu, tell the model to reply in Nastaliq script, not Roman Urdu. operationId: createAdhocSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAdhocSessionRequest' example: participantName: ayesha-web roomName: shifa-clinic config: agent: instructions: >- آپ شفا کلینک کی ہیلپ ڈیسک ایجنٹ ہیں۔ ویب وزیٹر کے سوالات کا جواب دیں: اوقاتِ کار، ڈاکٹروں کی دستیابی، اور اپائنٹمنٹ بکنگ۔ صرف نستعلیق اردو میں جواب دیں۔ initialGreeting: true greetingInstructions: >- السلام علیکم کہیں، شفا کلینک کا تعارف کروائیں، پھر پوچھیں کہ کس طرح مدد کر سکتے ہیں۔ session: ttl: 900 stt: default: provider: soniox model: stt-rt-preview language: ur tts: default: provider: upliftai voiceId: v_meklc281 outputFormat: MP3_22050_32 llm: default: provider: google model: gemini-2.5-flash responses: '200': description: Credentials for the browser client to join with. content: application/json: schema: $ref: '#/components/schemas/SessionToken' example: token: >- eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9pbiI6dHJ1ZSwicm9vbSI6… wsUrl: wss://upliftai-prod-yd34to8b.livekit.cloud roomName: shifa-clinic-835050e4-xxxx-xxxx-xxxx-xxxxxxxxxxxx '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': description: The organization is out of credits. No session is created. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Insufficient credits to start a realtime session error: Payment Required statusCode: 402 '403': $ref: '#/components/responses/Forbidden' components: schemas: CreateAdhocSessionRequest: type: object properties: participantName: type: string minLength: 1 description: Identity your client joins the room under. roomName: type: string description: >- Cosmetic room prefix, truncated to its first 15 characters. Overrides `config.session.roomPrefix`; without either, the prefix is `adhoc`. config: $ref: '#/components/schemas/AssistantConfig' required: - participantName - config SessionToken: type: object properties: token: type: string description: >- LiveKit access token. Hand it to a LiveKit client SDK along with `wsUrl`. wsUrl: type: string format: uri description: LiveKit WebSocket URL the client connects to. roomName: type: string description: The room this token opens. Server-generated — treat it as opaque. Error: type: object properties: message: description: >- One message per failed field for validation errors, a single string otherwise. oneOf: - type: string - type: array items: type: string error: type: string statusCode: type: integer AssistantConfig: type: object additionalProperties: true description: Keys beyond those listed are stored and returned unchanged. properties: agent: $ref: '#/components/schemas/AgentConfig' grading: type: object description: >- Assistant-level scorecard. Every non-campaign call of this assistant — web, inbound, raw API dial — is graded against it; campaign calls use the campaign's own scorecard instead. See [Scorecards](/voice-agents/assistants/scorecards). A `scorecard` that is not an object, or whose points don't total 100, is a 400. properties: scorecard: $ref: '#/components/schemas/Scorecard' noiseCancellation: type: object description: >- Cleans the caller's audio before speech-to-text. `enabled` is required, and an unknown `model` is a 400. properties: enabled: type: boolean model: type: string enum: - quail_vf_s - quail_vf_l - quail_l default: quail_vf_s level: type: number default: 0.1 description: >- Suppression strength. Stronger settings clipped short Urdu backchannels, which is why the default is low. required: - enabled backgroundNoise: type: object description: Plays ambient room sound under the call. `enabled` is required. properties: enabled: type: boolean required: - enabled session: $ref: '#/components/schemas/SessionConfig' stt: type: object description: '`default` is the only supported key today (same for `tts`/`llm`).' properties: default: $ref: '#/components/schemas/SttConfig' required: - default tts: type: object properties: default: $ref: '#/components/schemas/TtsConfig' required: - default llm: type: object properties: default: $ref: '#/components/schemas/LlmConfig' required: - default required: - agent AgentConfig: type: object properties: instructions: type: string minLength: 1 description: >- System prompt. For Urdu assistants, tell the model to reply in Nastaliq script — otherwise it tends to answer in Roman Urdu. initialGreeting: type: boolean default: false description: >- Whether the assistant speaks first instead of waiting for the caller. greetingInstructions: type: string description: >- Describe how the agent should greet — it uses the prompt to come up with the opening line, so you can say "Say salam and confirm you are talking to the right person." Ignored unless `initialGreeting` is true. tools: type: array description: >- Invocations are delivered to your browser client over the session, using the tool name as the RPC method. Tools whose `execution` points at a tool endpoint connection go there instead. items: $ref: '#/components/schemas/AssistantTool' required: - instructions Scorecard: type: object description: >- The rubric every call on this campaign is graded against. It freezes once any call has been graded, so revise it before launching. properties: rubricVersionId: type: string minLength: 1 rules: type: array minItems: 1 description: Rule ids must be unique and their `points` must total exactly 100. items: $ref: '#/components/schemas/ScorecardRule' required: - rubricVersionId - rules SessionConfig: type: object properties: ttl: type: integer minimum: 1 default: 600 description: >- Lifetime in seconds of each web session's join token. Caps how long a client has to connect, not how long a call may run. roomPrefix: type: string maxLength: 32 description: >- Cosmetic prefix on generated room names. The server appends the session id. SttConfig: description: Pick the shape matching your provider. oneOf: - title: Soniox type: object required: - provider additionalProperties: true properties: provider: type: string enum: - soniox model: type: string description: '`stt-rt-v4` (default) or `stt-rt-v5`.' example: stt-rt-v4 language: type: string description: >- Bias hint, not a hard filter — language identification stays on, so other languages in the audio are still recognized. Defaults to `ur`. example: ur context: type: string description: >- Free-text biasing — names, products, phrases the model should expect to hear. apiKey: type: string description: >- Your own Soniox key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. - title: Deepgram type: object required: - provider additionalProperties: true properties: provider: type: string enum: - deepgram model: type: string description: '`nova-3` (default) or `nova-2`.' example: nova-3 language: type: string description: Defaults to `multi` (multilingual). example: multi apiKey: type: string description: >- Your own Deepgram key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. - title: OpenAI type: object required: - provider additionalProperties: true properties: provider: type: string enum: - openai model: type: string description: Defaults to `whisper-1`. example: whisper-1 language: type: string description: ISO code. Defaults to `ur`. example: ur prompt: type: string description: >- Free-text biasing — names, products, phrases the model should expect to hear. useRealtime: type: boolean description: Use OpenAI's realtime transcription. Defaults to false. apiKey: type: string description: >- Your own OpenAI key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. - title: Groq type: object required: - provider additionalProperties: true properties: provider: type: string enum: - groq model: type: string description: >- `whisper-large-v3-turbo` (default), `whisper-large-v3`, or `distil-whisper-large-v3-en`. example: whisper-large-v3-turbo language: type: string description: ISO code. Defaults to `ur`. example: ur prompt: type: string description: >- Free-text biasing — names, products, phrases the model should expect to hear. apiKey: type: string description: >- Your own Groq key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. - title: Uplift AI type: object required: - provider additionalProperties: true properties: provider: type: string enum: - upliftai model: type: string description: '`large-v3`.' example: large-v3 language: type: string description: ISO code. Defaults to `ur`. example: ur TtsConfig: description: >- Pick the shape matching your provider. A TTS block without a usable `voiceId` stores fine and fails at connect time. oneOf: - title: Uplift AI type: object required: - provider - voiceId additionalProperties: true properties: provider: type: string enum: - upliftai voiceId: type: string description: >- Pick an id from the [voices gallery](/orator_voices) — 80+ voices tuned for Urdu and regional languages. example: helpdesk-agent outputFormat: type: string description: Defaults to `MP3_22050_32`. example: MP3_22050_32 - title: OpenAI type: object required: - provider additionalProperties: true properties: provider: type: string enum: - openai model: type: string description: Defaults to `gpt-4o-mini-tts`. example: gpt-4o-mini-tts voiceId: type: string description: An OpenAI voice name. Defaults to `alloy`. example: alloy apiKey: type: string description: >- Your own OpenAI key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. - title: Soniox type: object required: - provider - voiceId additionalProperties: true properties: provider: type: string enum: - soniox model: type: string description: Defaults to `tts-rt-v1`. example: tts-rt-v1 voiceId: type: string description: A Soniox voice name. example: Maya language: type: string description: ISO code. Defaults to `ur`. example: ur apiKey: type: string description: >- Your own Soniox key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. LlmConfig: description: >- Pick the shape matching your provider — each takes different knobs, and a knob sent to the wrong provider is silently ignored. oneOf: - title: Google Gemini type: object required: - provider - model additionalProperties: true properties: provider: type: string enum: - google model: type: string description: >- `gemini-3.5-flash`, `gemini-3.1-flash-lite`, or `gemini-2.5-flash`. example: gemini-2.5-flash thinkingLevel: type: string enum: - minimal - low - medium - high description: >- Gemini 3.x models only. Reasoning depth per response — each step up adds latency, so `high` is rarely right for live calls. Absent behaves as the voice-tuned `low`. thinkingBudget: type: integer minimum: -1 maximum: 24576 description: >- Gemini 2.5 models only (not `-lite`). Maximum thinking tokens per response: `0` turns thinking off, `-1` lets the model decide, `1`–`24576` sets an explicit cap. Absent uses a voice-tuned low cap (512). apiKey: type: string description: >- Your own Gemini key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. - title: OpenAI type: object required: - provider - model additionalProperties: true properties: provider: type: string enum: - openai model: type: string description: '`gpt-5.4-nano`, `gpt-5.4-mini`, or `gpt-4o-mini`.' example: gpt-5.4-nano reasoningEffort: type: string enum: - none - low - medium - high - xhigh description: >- gpt-5.x models. Each step up adds latency per reply. Unset runs the model without a reasoning phase (classic `temperature: 0`). verbosity: type: string enum: - low - medium - high description: Answer-length control, gpt-5.x models only. apiKey: type: string description: >- Your own OpenAI key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. - title: Cerebras type: object required: - provider - model additionalProperties: true properties: provider: type: string enum: - cerebras model: type: string description: '`gpt-oss-120b`.' example: gpt-oss-120b reasoningEffort: type: string enum: - low - medium - high description: >- Supported by the reasoning models (`gpt-oss-120b`). `none` is rejected by Cerebras; `verbosity` is not supported on any Cerebras model. apiKey: type: string description: >- Your own Cerebras key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. - title: Groq type: object required: - provider - model additionalProperties: true properties: provider: type: string enum: - groq model: type: string description: >- `openai/gpt-oss-120b` or `openai/gpt-oss-20b`. No reasoning or verbosity knobs on this provider. example: openai/gpt-oss-120b apiKey: type: string description: >- Your own Groq key; omit to bill through Uplift AI. Reads return it verbatim, so anyone who can read the assistant can see it. AssistantTool: type: object properties: name: type: string minLength: 1 description: type: string minLength: 1 description: What the tool does. The model picks the tool from this text. parameters: type: object description: JSON Schema for the tool's arguments. properties: type: type: string minLength: 1 properties: type: object required: type: array items: type: string required: - type - properties timeout: type: number minimum: 0 description: >- Seconds to wait for a client tool's handler before the assistant moves on. Default 10. Webhook tools always get 10 seconds. execution: type: object description: >- Where the tool runs. Omit it for a client tool, which your web page or mobile app executes over the session. Set `type: tool_endpoint` with the id of a tool endpoint you added on the [portal](https://upliftai.org/app/calling/webhooks) to have the platform POST the call to your server instead. See [Webhook tools](/voice-agents/tools/webhook-tools). properties: type: type: string enum: - client_rpc - tool_endpoint connectionId: type: string description: >- Required when `type` is `tool_endpoint`. The id of a tool endpoint in this project, from the [portal](https://upliftai.org/app/calling/webhooks). A webhook's id is rejected at call time. Not checked on create: a missing or wrong id surfaces as an error result on the call, not a 400. required: - type required: - name - description - parameters ScorecardRule: type: object properties: ruleId: type: string minLength: 1 title: type: string minLength: 1 instruction: type: string minLength: 1 description: What the grader looks for in the transcript to award this rule. scoringType: type: string enum: - binary description: Each rule is earned in full or not at all. points: type: integer minimum: 1 evidenceRequired: type: boolean description: >- When true, the grader must cite a transcript quote to award the rule. required: - ruleId - title - instruction - scoringType - points responses: BadRequest: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: - config.agent.instructions should not be empty - config.agent.instructions must be a string error: Bad Request statusCode: 400 Unauthorized: description: A bearer key was sent but is not recognized. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: invalid authorization error: Unauthorized statusCode: 401 Forbidden: description: No API key sent, or the key lacks permission for this resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Forbidden resource error: Forbidden statusCode: 403 securitySchemes: apiKey: type: http scheme: bearer description: Project API key (`sk_api_…`). ````