Build an agent

Create a draft agent

POST /api/v1/agents always creates a draft. Send a title and a questions array. The response contains the id.

curl -X POST https://api.formbharo.artpark.ai/api/v1/agents \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Clinic intake",
    "questions": [
      {
        "question": "What is your full name?",
        "response_type": "string"
      },
      {
        "question": "What is your date of birth?",
        "response_type": "date"
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.formbharo.artpark.ai/api/v1/agents",
    headers={"Authorization": "Bearer <api-key>"},
    json={
        "title": "Clinic intake",
        "questions": [
            {
                "question": "What is your full name?",
                "response_type": "string",
            },
            {
                "question": "What is your date of birth?",
                "response_type": "date",
            },
        ],
    },
)

agent_id = response.json()["id"]

Map each field to a question type

response_type sets how the spoken answer is parsed and stored.

`response_type`	What it stores	Extra options
`string`	Free-text answer
`number`	Numeric value	`number_format: "integer"` or `"decimal"`
`date`	Date, stored as `DD-MM-YYYY`
`boolean`	Yes/no answer	`boolean_labels` to customize the spoken options
`single-select`	One choice from a list	`options[]`, required
`multi-select`	One or more choices from a list	`options[]`, required

options is an array of strings. The agent reads the list aloud and maps the answer to the closest option.Omit number_format to accept both integers and decimals.Add an optional name to a question to give it a stable snake_case key. Branch conditions reference questions by name.

Add scripts

Set scripts on the agent body.

Field	When the agent says it
`scripts.intro`	At the start of the call, before the first question
`scripts.outro`	After all required questions are answered
`scripts.outro_incomplete`	When the call ends before all questions are answered

outro_incomplete requires outro.

{
  "scripts": {
    "intro": "Hi, I'm calling on behalf of City Clinic to complete your intake form. This will only take a couple of minutes.",
    "outro": "That's everything I need. Thank you for your time, we'll see you at your appointment.",
    "outro_incomplete": "It looks like we ran out of time. Our team will follow up to collect the remaining details."
  }
}

Add conditional branches

Add an entry to the top-level branches array with a unique id and a condition.
Set branch_id on every question in that branch. Those questions are asked only when the condition is true.

A condition supports these fields:

Field	Type	Meaning
`field`	string	The `name` of the question whose answer is evaluated
`equals`	boolean	Matches the answer to a `boolean` question
`present`	boolean	`true` asks the branch when the question was answered, `false` asks it when the question was skipped

Set exactly one of equals or present.

{
  "branches": [
    {
      "id": "has_insurance",
      "condition": {
        "field": "insurance_status",
        "equals": true
      }
    }
  ],
  "questions": [
    {
      "name": "insurance_status",
      "question": "Do you have health insurance?",
      "response_type": "boolean"
    },
    {
      "question": "Who is your insurance provider?",
      "response_type": "string",
      "branch_id": "has_insurance"
    },
    {
      "question": "What is your policy number?",
      "response_type": "string",
      "branch_id": "has_insurance"
    }
  ]
}

{
  "branches": [
    {
      "id": "has_referral",
      "condition": {
        "field": "referral_source",
        "present": true
      }
    }
  ],
  "questions": [
    {
      "name": "referral_source",
      "question": "Were you referred by someone?",
      "response_type": "string"
    },
    {
      "question": "What is the name of the person who referred you?",
      "response_type": "string",
      "branch_id": "has_referral"
    }
  ]
}

Configure screening

end_call_values is an array of strings set on a question. When the answer to that question matches one of the values, the agent ends the call and marks the conversation screened_out. Screened-out calls count as successes, not failures, and appear separately in analytics.

{
  "question": "Are you interested in scheduling an appointment?",
  "response_type": "boolean",
  "end_call_values": ["no"]
}

Publish

PUT /api/v1/agents/{agent_id} always publishes. Send the complete agent body, not just the changed fields.

curl -X PUT https://api.formbharo.artpark.ai/api/v1/agents/AGENT_ID \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Clinic intake",
    "questions": [ ... ],
    "scripts": { ... },
    "branches": [ ... ]
  }'

import requests

agent_body = {
    "title": "Clinic intake",
    "questions": [...],
    "scripts": {...},
    "branches": [...],
}

response = requests.put(
    f"https://api.formbharo.artpark.ai/api/v1/agents/{agent_id}",
    headers={"Authorization": "Bearer <api-key>"},
    json=agent_body,
)

if response.status_code == 400:
    print("Validation failed:", response.json()["validation_issues"])
else:
    print("Published:", response.json())

On validation failure the API returns 400 with a validation_issues array. Fix every issue before retrying. Partial saves are not supported.

See Agent config schema for every field.

Get Started

Guides

Reference