Skip to main content
In FormBharo, an agent is a reusable form definition. It holds the questions the voice assistant will ask, the exact words to use at the start and end of a call, and settings like language and whether the agent speaks first. You create one agent and reuse it across as many conversations as you need — each conversation writes its answers back to the same agent definition.

​
What an agent contains

Every agent is made up of four parts:
  • Questions — the list of things the agent will ask, in order. Each question has a name (used as the key in the answer object), the exact wording the assistant speaks, and an answer type such as string, number, boolean, or single-select.
  • Scripts — the exact phrases the assistant uses to open and close the call. The intro script runs before the first question; the outro runs after the last answer is collected.
  • Settings — configuration that controls call behaviour: the language the agent speaks, whether the agent speaks first or waits for the caller to start, and what to do when a question receives no answer (skip it, retry, or end the call).
  • Branches — conditional follow-up question groups. When an answer matches a trigger value, the agent inserts an additional set of questions before continuing the main sequence.

​
Draft and published

Every agent starts as a draft:
  • POST /api/v1/agents creates a new agent in draft state.
  • PUT /api/v1/agents/{agent_id} replaces the agent’s definition and moves it to published state.
The status field in listing responses is either draft or published. Drafts are fully callable — conversations can run against them — but they are not considered stable. Treat drafts as works in progress and publish before sending an agent into production.
Publishing an agent by calling PUT /api/v1/agents/{agent_id} replaces the entire definition. Send the complete agent body each time, not just the fields you want to change.

​
Version history

Every time you publish a save, FormBharo records an immutable version snapshot. Version numbers start at 1 and increment with each subsequent publish. Drafts are never versioned — only successful publishes create a new version entry. Use versions to audit changes, roll back a bad update, or preview what a pending save will affect before you commit it.
1

List all versions of an agent

Returns a list of version summaries ordered newest first, including version number and publish timestamp.
2

Read a specific version

Returns the full agent definition exactly as it was when that version was published.
3

Compare two versions

Returns the diff between the specified version and the current published version. Use this to understand exactly what changed between any historical snapshot and today.
4

Preview what a save would change

Send a candidate agent body. FormBharo compares it against the current published version and returns a diff — no changes are saved.
5

Preview a config-only change

Like diff-preview but scoped to agent configuration fields only. Use this when you want to preview changes to settings without touching the question list.
6

Restore an older version

Promotes an old version to become the current published definition and increments the version counter. The restored content becomes the new latest version.

​
Workspaces

Every agent belongs to exactly one workspace. By default, new agents are placed in your personal workspace. To place an agent in a shared workspace at creation time, include workspace_id in the request body of POST /api/v1/agents. To move an existing agent to a different workspace, call:
with the target workspace_id in the request body. Moving an agent does not affect its conversations or version history.
Use workspaces to organise agents by team, client, or product line. Members of a workspace can view and edit all agents in it, so place agents accordingly before sharing access.

​
Deleting an agent

This performs a soft delete. The agent stops appearing in list responses and can no longer accept new calls. All existing call records and their collected answers are fully preserved. If you need to recover a soft-deleted agent, contact support.
Deleting an agent is not reversible through the API. Make sure you no longer need to run new conversations against it before you delete it.