> ## 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. # Build an assistant from a brief > The assistant exists the moment this returns, but a background pipeline writes and hardens its Urdu prompt over the next few minutes — until the status poll reads `done`, its entire prompt is the literal text `(building…)`, so don't put it on a call yet. [Poll the build status](/api-reference/authoring-an-assistant/poll-a-builds-progress) for the outcome. Every request builds a fresh assistant; to change one you already built, [refine it](/api-reference/authoring-an-assistant/refine-a-built-assistants-prompt) or [update its config directly](/api-reference/assistants/update-an-assistant). ## OpenAPI ````yaml /voice-agents/api-reference/openapi.yaml post /realtime-assistants/builds 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: post: tags: - Authoring an assistant summary: Build an assistant from a brief description: >- The assistant exists the moment this returns, but a background pipeline writes and hardens its Urdu prompt over the next few minutes — until the status poll reads `done`, its entire prompt is the literal text `(building…)`, so don't put it on a call yet. [Poll the build status](/api-reference/authoring-an-assistant/poll-a-builds-progress) for the outcome. Every request builds a fresh assistant; to change one you already built, [refine it](/api-reference/authoring-an-assistant/refine-a-built-assistants-prompt) or [update its config directly](/api-reference/assistants/update-an-assistant). operationId: startAssistantBuild requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartBuildRequest' example: brief: goal: appointment voiceId: v_meklc281 gender: female context: >- Shifa Clinic, Lahore. Call patients to confirm tomorrow's doctor appointment, remind them of the time, and offer to reschedule if they cannot come. sampleRows: - name: عائشہ صدیقی phone: '+923001234567' doctor: ڈاکٹر عمران شیخ appointmentTime: کل صبح 11 بجے responses: '200': description: The build is running; its outcome arrives through the status poll. content: application/json: schema: $ref: '#/components/schemas/StartBuildResponse' example: buildId: 01407eda-xxxx-xxxx-xxxx-xxxxxxxxxxxx assistantId: 9d1d042f-xxxx-xxxx-xxxx-xxxxxxxxxxxx status: started '400': description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: - >- brief.goal must be one of the following values: appointment, event, lead, order_confirmation, payment_reminder, outreach, reservation_confirmation - brief.voiceId must be a string error: Bad Request statusCode: 400 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: StartBuildRequest: type: object properties: brief: $ref: '#/components/schemas/BuildBrief' required: - brief 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_…`). ````