> ## 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.

# Quickstart: Your First FormBharo API Call in Minutes

> Set your API key and server URL, list your existing agents, and create your first voice agent in under five minutes using curl or Python.

export const FORMBHARO_URL = "https://api.formbharo.artpark.ai";

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](/getting-started/api-keys)). Both steps work in curl and Python — pick whichever you prefer.

<Steps>
  <Step title="Set your API key">
    Store your API key as an environment variable so you don't hard-code it into every command.

    ```bash theme={null}
    export FORMBHARO_KEY="fb_live_0123456789ab_REPLACE_THIS_WITH_YOUR_KEY"
    ```
  </Step>

  <Step title="List your agents">
    Fetch all agents visible to your account. A successful response confirms your key is correct.

    <CodeGroup>
      ```bash curl theme={null}
      curl "{FORMBHARO_URL}/api/v1/agents" \
        -H "Authorization: Bearer $FORMBHARO_KEY"
      ```

      ```python Python theme={null}
      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())
      ```
    </CodeGroup>

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

    ```json theme={null}
    [
      {
        "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"
      }
    ]
    ```
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash curl theme={null}
      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"
            }
          ]
        }'
      ```

      ```python Python theme={null}
      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())
      ```
    </CodeGroup>

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

    ```json theme={null}
    {
      "id": "f3a92c11-08bd-4e7a-b541-dc3301a4ef88",
      "workspace_id": "personal-b3c9fe587b86d5a1"
    }
    ```

    Save the `id` — you will need it in the next step.
  </Step>

  <Step title="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"`.

    ```bash curl theme={null}
    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"
          }
        ]
      }'
    ```

    <Note>
      The `PUT` endpoint replaces the entire agent definition, so always send the full body, not just the fields you want to change. See [Agent Config Schema](/reference/agent-config-schema) for every available field.
    </Note>
  </Step>
</Steps>

<Tip>
  Next, read [Build an Agent](/guides/build-an-agent) for a complete walkthrough including question types, scripts, branching, and validation.
</Tip>