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

# Create Agent

> Create a new agent with the given title and questions.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/agents
openapi: 3.1.0
info:
  description: >
    Create and run form-filling voice agents, and read back the conversations
    they had.


    Send your API key on every request as `Authorization: Bearer fb_live_...`.

    A key belongs to one workspace and only reaches that workspace's agents.
    Create

    and revoke keys from Settings in the web app; keys cannot manage other keys.
  title: FormBharo API
  version: 1.0.0
servers:
  - description: Production
    url: https://form-fill-agent-backend.artpark.ai
security:
  - apiKey: []
paths:
  /api/v1/agents:
    post:
      tags:
        - Agents
      summary: Create Agent
      description: Create a new agent with the given title and questions.
      operationId: create_agent_api_v1_agents_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateAgentRequest:
      properties:
        agent_persona:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Persona
        agent_speaks_first:
          default: true
          title: Agent Speaks First
          type: boolean
        ai_instructions:
          default: ''
          title: Ai Instructions
          type: string
        ask_questions_one_by_one:
          default: true
          title: Ask Questions One By One
          type: boolean
        branches:
          items:
            $ref: '#/components/schemas/Branch'
          title: Branches
          type: array
        calibrate_base_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Calibrate Base Url
        calibrate_extract_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Calibrate Extract Agent Id
        calibrate_reply_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Calibrate Reply Agent Id
        description:
          default: ''
          title: Description
          type: string
        hearing_acknowledgement_mode:
          default: fixed
          enum:
            - fixed
            - llm
          title: Hearing Acknowledgement Mode
          type: string
        hearing_acknowledgement_phrases:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Hearing Acknowledgement Phrases
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
        mute_user_while_agent_speaking:
          default: false
          title: Mute User While Agent Speaking
          type: boolean
        questions:
          items:
            $ref: '#/components/schemas/Question'
          title: Questions
          type: array
        scripts:
          anyOf:
            - $ref: '#/components/schemas/ScriptsConfig'
            - type: 'null'
        send_hearing_acknowledgements:
          default: true
          title: Send Hearing Acknowledgements
          type: boolean
        title:
          title: Title
          type: string
        user_persona:
          anyOf:
            - type: string
            - type: 'null'
          title: User Persona
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
      required:
        - title
        - questions
      title: CreateAgentRequest
      type: object
    CreateAgentResponse:
      properties:
        id:
          title: Id
          type: string
        workspace_id:
          title: Workspace Id
          type: string
      required:
        - id
        - workspace_id
      title: CreateAgentResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    Branch:
      description: >-
        A conditional group ("box") of questions in the form builder.


        Questions reference a branch via ``Question.branch_id``. The branch's
        questions

        are only asked when ``condition`` evaluates true against the collected
        answers.
      properties:
        condition:
          $ref: '#/components/schemas/BranchCondition'
        id:
          title: Id
          type: string
      required:
        - id
        - condition
      title: Branch
      type: object
    Question:
      properties:
        advanced_instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Advanced Instructions
        boolean_labels:
          anyOf:
            - $ref: '#/components/schemas/BooleanLabels'
            - type: 'null'
        branch_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Branch Id
        end_call_values:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: End Call Values
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        number_format:
          anyOf:
            - enum:
                - integer
                - decimal
              type: string
            - type: 'null'
          title: Number Format
        options:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Options
        question:
          title: Question
          type: string
        required:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Required
        response_type:
          enum:
            - string
            - number
            - date
            - boolean
            - single-select
            - multi-select
          title: Response Type
          type: string
        retry_config:
          anyOf:
            - $ref: '#/components/schemas/RetryConfig'
            - type: 'null'
        script:
          anyOf:
            - type: string
            - type: 'null'
          title: Script
        skip_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Skip Message
        validation:
          anyOf:
            - $ref: '#/components/schemas/ValidationConfig'
            - type: 'null'
      required:
        - question
        - response_type
      title: Question
      type: object
    ScriptsConfig:
      properties:
        intro:
          anyOf:
            - type: string
            - type: 'null'
          title: Intro
        outro:
          anyOf:
            - type: string
            - type: 'null'
          title: Outro
        outro_incomplete:
          anyOf:
            - type: string
            - type: 'null'
          title: Outro Incomplete
      title: ScriptsConfig
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    BranchCondition:
      description: >-
        Condition that gates a branch.


        ``field`` is the ``name`` of the controlling question. Exactly one of
        ``equals``

        or ``present`` is set, selecting the condition mode:


        - Value-match mode (``equals``): boolean controllers only. The branch
        activates
          when the controller's boolean answer matches ``equals`` ("is True" / "is False").
        - Presence mode (``present``): any controller type
        (string/number/date/boolean/
          single-select/multi-select). The branch keys off whether the controller was
          answered vs skipped — ``present=True`` activates when the controller was
          answered (not present = skipped), ``present=False`` activates when it was
          skipped.
      properties:
        equals:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Equals
        field:
          title: Field
          type: string
        present:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Present
      required:
        - field
      title: BranchCondition
      type: object
    BooleanLabels:
      properties:
        'false':
          anyOf:
            - type: string
            - type: 'null'
          title: 'False'
        'true':
          anyOf:
            - type: string
            - type: 'null'
          title: 'True'
      title: BooleanLabels
      type: object
    RetryConfig:
      description: >-
        Per-question retry behaviour driven deterministically by the backend.


        - ``allow_retries``: when False, the question is never re-asked; the
        first failed
          attempt immediately exhausts retries.
        - ``until_answered``: when True, the question is re-asked indefinitely
        until a valid
          answer is captured (``max_retries`` is ignored).
        - ``max_retries``: number of re-asks allowed after the initial ask (e.g.
        2 = ask once,
          then two retries, then exhausted).
        - ``retry_messages``: exact text to speak on each retry.
        ``retry_messages[0]`` is the
          first retry, ``[1]`` the second, and so on. An empty/missing entry re-asks the
          question's Script verbatim.

        The action taken once retries are exhausted: required questions always
        end the call.

        Optional questions follow ``exhausted_action`` — ``"skip"`` (default)
        moves on to the

        next question (speaking ``skip_message``), ``"end_call"`` ends the call
        instead.
      properties:
        allow_retries:
          default: true
          title: Allow Retries
          type: boolean
        exhausted_action:
          default: skip
          enum:
            - skip
            - end_call
          title: Exhausted Action
          type: string
        max_retries:
          default: 2
          title: Max Retries
          type: integer
        retry_messages:
          items:
            type: string
          title: Retry Messages
          type: array
        until_answered:
          default: false
          title: Until Answered
          type: boolean
      title: RetryConfig
      type: object
    ValidationConfig:
      properties:
        rules:
          additionalProperties: true
          title: Rules
          type: object
        type:
          title: Type
          type: string
      required:
        - type
      title: ValidationConfig
      type: object
  securitySchemes:
    apiKey:
      bearerFormat: fb_live_...
      scheme: bearer
      type: http

````