Skip to main content
Change what your agent says with two Brilo API calls: write the change as a draft, then publish it. Callers hear the new version from their next call. Two more calls find the agent a phone number and buy it, and a last one rings your own phone so you can hear it. Each step works over REST or as a tool on the Brilo MCP server. Skip steps 3 and 4 if the agent already has a number.

​
Before you start

  • A Brilo API key for the workspace, from Settings, then Developer. See Authentication.
  • The id of the agent to change. GET /v1/agents or the list_agents tool lists them.
  • The Agents API turned on for your workspace. While it is off, these routes answer 404.

​
Steps

1

Write the change as a draft

Send only the fields you want to change. Everything else on the agent, including actions and knowledge bases set in the dashboard, stays as it is.
Over MCP, call update_agent with {"agent_id": "AGENT_ID", "config": {"greeting": "..."}}. The response lists changed_fields, says draft_pending: true, and its next_action points at publish. An agent that had no versions gets them now, with the warning versioning_enabled.
2

Publish the draft

Over MCP, call publish_agent with {"agent_id": "AGENT_ID"}. Callers hear the change from their next call. Publishing again with no draft changes nothing and returns the warning nothing_to_publish, so a retry is safe.
3

Find a phone number

Over MCP, call search_available_phone_numbers with {"area_code": "512"}. Each number shows its monthly_price, which is 0 when your plan covers it. Show the owner the price before buying.
4

Buy it for this agent

Over MCP, call buy_phone_number with the same fields; it waits for the number to be ready. accept_monthly_price must be the price the owner saw, and the Idempotency-Key makes a retry safe. The number answers for the agent once status is active. Limits, refunds and releasing are on Buy and release phone numbers.
5

Hear it

The publish response carries try_it when the agent can be reached: its phone numbers, a demo link if the agent has one, and ring_me, a ready made Create Call request. Fill in your own number as to and send it:
An AI agent should ask the person before placing this call.

​
You will know it worked when

  • GET /v1/agents/AGENT_ID shows the new greeting in config and draft_pending: false.
  • The call to your phone opens with the new greeting.

​
What else you can do here

​
If it did not work

The routes answer 404. The Agents API is not on for this workspace yet, or the agent id belongs to another workspace. Check the id with GET /v1/agents. The response is 409 stale_revision. Someone changed the agent after you read it. Apply your change to details.current and send it again with its revision as If-Match. The response is 400 voice_not_available. That voice is not offered to your workspace or plan. Pick one from details.available_voices, or leave voice out. There is no try_it in the response. The agent has no phone number and no demo link, so there is nothing to call yet. Do steps 3 and 4 first. The purchase returns 409 price_not_accepted. The price changed since you searched. Show the owner details.monthly_price and send the purchase again with it.

​
FAQ

No. An update writes a draft, and callers keep hearing the published version until you call publish. That lets you change several fields, check the draft with GET, and make it live in one step. Publishing takes effect from the next call, with no restart.
No. An update changes only the fields you send. Actions, knowledge bases, workflows and every setting the API does not show are copied into the draft unchanged and published with it, so work done in the dashboard is never lost.
The agent had no versions, so the Brilo API turned them on with your first change. Its current settings became the live version “main”, and your change is a draft on it. Callers hear nothing new until you publish. The dashboard now shows versions for that agent.
Yes. POST /v1/agents with a name and an optional config creates an agent that is live straight away, with plan defaults for anything you leave out. A plan with no room for another agent returns 403 agent_limit_reached with a link to upgrade.
Use whichever your tool speaks. Every Agents API route has an MCP tool with the same name pattern and the same rules, because both call the same code. MCP suits AI tools such as Claude or Cursor; REST suits scripts and servers.
Send the revision from your last read as the If-Match header, or if_revision over MCP. If the agent changed since, the Brilo API refuses with 409 stale_revision and returns the current agent, so nothing is overwritten by accident.