> ## 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. # Refine a built assistant's prompt > A finished refine regenerates the assistant's `name` and its whole `config` from the brief, overwriting any edits you made by hand — only the prompt carries forward. It reruns the same rehearse-and-grade rounds as a build, so it takes minutes: [poll the build status](/api-reference/authoring-an-assistant/poll-a-builds-progress). Starting one while another build is in flight still returns 200, then surfaces as `failed` in that poll. ## OpenAPI ````yaml /voice-agents/api-reference/openapi.yaml post /realtime-assistants/builds/{assistantId}/refine 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/builds/{assistantId}/refine: post: tags: - Authoring an assistant summary: Refine a built assistant's prompt description: >- A finished refine regenerates the assistant's `name` and its whole `config` from the brief, overwriting any edits you made by hand — only the prompt carries forward. It reruns the same rehearse-and-grade rounds as a build, so it takes minutes: [poll the build status](/api-reference/authoring-an-assistant/poll-a-builds-progress). Starting one while another build is in flight still returns 200, then surfaces as `failed` in that poll. operationId: refineAssistantBuild parameters: - name: assistantId in: path required: true description: The `assistantId` the original build returned. schema: type: string format: uuid example: befbca99-xxxx-xxxx-xxxx-xxxxxxxxxxxx requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefineAssistantRequest' example: ownerFeedback: >- اپائنٹمنٹ کا وقت اور ڈاکٹر کا نام دو بار دہرائیں۔ اگر مریض کہے کہ وہ ابھی مصروف ہیں تو بحث نہ کریں، معذرت کر کے کال ختم کر دیں۔ responses: '200': description: >- The refine started; nothing here reflects its outcome. A run that cannot start — because a build is already in flight for this assistant — still returns 200, and surfaces as `failed` in the status poll. content: application/json: schema: $ref: '#/components/schemas/StartBuildResponse' example: buildId: e2f42d2b-xxxx-xxxx-xxxx-xxxxxxxxxxxx assistantId: befbca99-xxxx-xxxx-xxxx-xxxxxxxxxxxx status: started '400': description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: - >- ownerFeedback must be shorter than or equal to 2000 characters - ownerFeedback must be a string error: Bad Request statusCode: 400 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- No such assistant, or it was never built and so has no prompt to refine. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Assistant has no build artifacts to refine error: Not Found statusCode: 404 components: schemas: RefineAssistantRequest: type: object properties: ownerFeedback: type: string maxLength: 2000 description: >- What to change, in plain language. Carried into every grading round, so a later automated fix cannot quietly undo it. brief: allOf: - $ref: '#/components/schemas/BuildBrief' description: >- Replaces the brief the original build stored, for this run and every one after — send the whole brief, not just the fields you are changing. Omit to keep the stored brief. required: - ownerFeedback StartBuildResponse: type: object properties: buildId: type: string format: uuid description: Identifies this build run, for the status poll. assistantId: type: string format: uuid description: The assistant being built. status: type: string enum: - started 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 BuildBrief: type: object properties: goal: type: string description: >- What the call is for. Also picks the tool the assistant gets for recording the outcome. enum: - appointment - event - lead - order_confirmation - payment_reminder - outreach - reservation_confirmation voiceId: type: string description: >- Voice for the built assistant's `tts.default` — ids are in the voices gallery. gender: type: string enum: - male - female description: >- The agent's own gender. Urdu verb forms are gendered, so the prompt is written and graded against it — match it to `voiceId`. context: type: string maxLength: 8000 description: >- The brief in your own words: the business, what the call must achieve, the key message, who is being called. Passed to the authoring model verbatim, so its detail sets the prompt's quality. sampleRows: type: array maxItems: 20 description: >- Real contact rows, using the column names your campaign will send. Each test persona is grounded in one row, injected the way a live call receives a contact — no call is placed, the rehearsals are text-only. items: type: object additionalProperties: type: string required: - goal - voiceId - gender - context responses: 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_…`). ````