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

# Update an assistant

> This replaces rather than merges, so read the assistant, change what you need, and send the whole object back. Leaving out `description` or `public` clears them — `public` resets to false — while `name` and `config` keep their stored values. Only populated parts of `config` are validated, so a config missing `agent.instructions` saves fine and leaves the assistant unable to take calls.

Until the assistant's first publish, a save goes live at once. After that, an update changes the draft only. Calls and share links keep running the published version, and the `public` check reads it too, until you [publish](/api-reference/assistants/publish-an-assistant-version) again.

`noiseCancellation` and `backgroundNoise` are checked on every save that sends `config`. An assistant stored with a bad value before these checks gets a 400 on that save until you fix it. A save without `config` still goes through.



## OpenAPI

````yaml /voice-agents/api-reference/openapi.yaml post /realtime-assistants/{realtimeAssistantId}
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/{realtimeAssistantId}:
    post:
      tags:
        - Assistants
      summary: Update an assistant
      description: >-
        This replaces rather than merges, so read the assistant, change what you
        need, and send the whole object back. Leaving out `description` or
        `public` clears them — `public` resets to false — while `name` and
        `config` keep their stored values. Only populated parts of `config` are
        validated, so a config missing `agent.instructions` saves fine and
        leaves the assistant unable to take calls.


        Until the assistant's first publish, a save goes live at once. After
        that, an update changes the draft only. Calls and share links keep
        running the published version, and the `public` check reads it too,
        until you
        [publish](/api-reference/assistants/publish-an-assistant-version) again.


        `noiseCancellation` and `backgroundNoise` are checked on every save that
        sends `config`. An assistant stored with a bad value before these checks
        gets a 400 on that save until you fix it. A save without `config` still
        goes through.
      operationId: updateRealtimeAssistant
      parameters:
        - name: realtimeAssistantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 80b00435-4f7d-4555-b7c2-778229512f0b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAssistantRequest'
            example:
              name: Al-Falah credit card payment reminder
              description: >-
                Reminds cardholders of the due date and offers to log a payment
                promise
              public: false
              config:
                agent:
                  instructions: >-
                    آپ الفلاح بینک کی جانب سے کال کر رہے ہیں۔ کارڈ ہولڈر کو
                    ادائیگی کی آخری تاریخ یاد دلائیں، واجب الادا رقم بتائیں، اور
                    اگر وہ ادائیگی کا وعدہ کریں تو تاریخ نوٹ کریں۔ صرف نستعلیق
                    اردو میں جواب دیں۔
                  initialGreeting: true
                  greetingInstructions: >-
                    السلام علیکم کہیں، بینک کا تعارف کروائیں، پھر پوچھیں کہ کیا
                    وہ ابھی بات کر سکتے ہیں۔
                session:
                  ttl: 1800
                  roomPrefix: al-falah
                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: The assistant as stored after the update.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
              example:
                realtimeAssistantId: 80b00435-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                organizationId: a12b7e74-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                projectId: c782a4ec-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                name: Al-Falah credit card payment reminder
                description: >-
                  Reminds cardholders of the due date and offers to log a
                  payment promise
                config:
                  agent:
                    instructions: >-
                      آپ الفلاح بینک کی جانب سے کال کر رہے ہیں۔ کارڈ ہولڈر کو
                      ادائیگی کی آخری تاریخ یاد دلائیں، واجب الادا رقم بتائیں،
                      اور اگر وہ ادائیگی کا وعدہ کریں تو تاریخ نوٹ کریں۔ صرف
                      نستعلیق اردو میں جواب دیں۔
                    initialGreeting: true
                    greetingInstructions: >-
                      السلام علیکم کہیں، بینک کا تعارف کروائیں، پھر پوچھیں کہ
                      کیا وہ ابھی بات کر سکتے ہیں۔
                  session:
                    ttl: 1800
                    roomPrefix: al-falah
                  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
                public: false
                createdAt: '2026-08-18T04:37:53.727Z'
                updatedAt: '2026-08-18T04:39:28.828Z'
                createdBy: ef80cc74-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                updatedBy: ef80cc74-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                version: 6
        '400':
          $ref: '#/components/responses/ConfigBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    UpdateAssistantRequest:
      type: object
      properties:
        name:
          type: string
          description: An empty string is accepted.
        description:
          type: string
        config:
          $ref: '#/components/schemas/AssistantConfig'
        public:
          type: boolean
          description: >-
            Allows anyone to open a browser session against this assistant
            without an API key. On a published assistant, the change takes
            effect at the next publish.
    Assistant:
      type: object
      properties:
        realtimeAssistantId:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        projectId:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        config:
          $ref: '#/components/schemas/AssistantConfig'
        public:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        createdBy:
          type: string
          description: Who created the assistant — an API key or a portal user.
        updatedBy:
          type: string
        version:
          type: integer
          minimum: 1
          description: >-
            The version this response shows. Every save bumps it, so published
            numbers skip the saves in between.
    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
    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
    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:
    ConfigBadRequest:
      description: Validation failed. Nothing was saved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingInstructions:
              summary: The agent has no instructions
              value:
                message:
                  - config.agent.instructions should not be empty
                  - config.agent.instructions must be a string
                error: Bad Request
                statusCode: 400
            unknownNoiseModel:
              summary: A noise cancellation model we don't run
              value:
                message:
                  - >-
                    config.noiseCancellation.model must be one of the following
                    values: quail_vf_s, quail_vf_l, quail_l
                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
    NotFound:
      description: No such resource in the API key's project.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: 'Realtime assistant not found: 00000000-0000-4000-8000-000000000000'
            error: Not Found
            statusCode: 404
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Project API key (`sk_api_…`).

````