Quickstart: Your First FormBharo API Call in Minutes

This guide walks you through the two most fundamental FormBharo API calls: listing existing agents and creating a new one. You need an API key (see API Keys). Both steps work in curl and Python — pick whichever you prefer.

Set your API key

Store your API key as an environment variable so you don’t hard-code it into every command.

export FORMBHARO_KEY="fb_live_0123456789ab_REPLACE_THIS_WITH_YOUR_KEY"

List your agents

Fetch all agents visible to your account. A successful response confirms your key is correct.

curl "{FORMBHARO_URL}/api/v1/agents" \
  -H "Authorization: Bearer $FORMBHARO_KEY"

import os
import requests

response = requests.get(
    "{FORMBHARO_URL}/api/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['FORMBHARO_KEY']}"},
)
response.raise_for_status()
print(response.json())

The API returns an array of agent objects. For example:

[
  {
    "id": "a87c1556-79fa-4492-add9-a704c13466a3",
    "title": "Clinic intake",
    "question_count": 6,
    "updated_at": 1787626873.7724512,
    "conversation_count": 3,
    "status": "published",
    "workspace_id": "personal-b3c9fe587b86d5a1",
    "workspace_role": "admin"
  }
]

Create an agent

Send a POST request with a title and at least one question. This creates a draft agent you can refine before publishing.

curl -X POST "{FORMBHARO_URL}/api/v1/agents" \
  -H "Authorization: Bearer $FORMBHARO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My first agent",
    "questions": [
      {
        "text": "What is your full name?",
        "response_type": "string"
      }
    ]
  }'

import os
import requests

payload = {
    "title": "My first agent",
    "questions": [
        {
            "text": "What is your full name?",
            "response_type": "string",
        }
    ],
}

response = requests.post(
    "{FORMBHARO_URL}/api/v1/agents",
    headers={
        "Authorization": f"Bearer {os.environ['FORMBHARO_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
)
response.raise_for_status()
print(response.json())

On success the API returns the new agent’s ID and workspace:

{
  "id": "f3a92c11-08bd-4e7a-b541-dc3301a4ef88",
  "workspace_id": "personal-b3c9fe587b86d5a1"
}

Save the id — you will need it in the next step.

Publish your agent

A newly created agent starts as a draft and cannot accept calls until it is published. To publish it, send a PUT request to /api/v1/agents/{agent_id} with the complete agent body and "status": "published".

curl

curl -X PUT "{FORMBHARO_URL}/api/v1/agents/f3a92c11-08bd-4e7a-b541-dc3301a4ef88" \
  -H "Authorization: Bearer $FORMBHARO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My first agent",
    "status": "published",
    "questions": [
      {
        "text": "What is your full name?",
        "response_type": "string"
      }
    ]
  }'

The PUT endpoint replaces the entire agent definition, so always send the full body — not just the fields you want to change. See Agent Configuration for every available field.

Next, read Build an Agent for a complete walkthrough including question types, scripts, branching, and validation.

Get Started

Core Concepts

Guides

Reference

Quickstart: Your First FormBharo API Call in Minutes