> ## Documentation Index > Fetch the complete documentation index at: https://docs.brilo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Change an agent through the API > Change an agent greeting with the Brilo Agents API or MCP tools, publish it, give it a phone number and hear it yourself, in four calls. 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](https://docs.brilo.ai/api-reference/introduction.md#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. ```bash theme={null} curl -X PATCH https://api.brilo.ai/v1/agents/AGENT_ID \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"config": {"greeting": "Thanks for calling Lakeside Dental. We are open until 6pm today."}}' ``` 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** ```bash theme={null} curl -X POST https://api.brilo.ai/v1/agents/AGENT_ID/publish \ -H "Authorization: Bearer YOUR_API_KEY" ``` 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** ```bash theme={null} curl "https://api.brilo.ai/v1/phone_numbers/available?country=US&area_code=512&limit=5" \ -H "Authorization: Bearer YOUR_API_KEY" ``` 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** ```bash theme={null} curl -X POST "https://api.brilo.ai/v1/phone_numbers?wait=20" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Idempotency-Key: 6f1c2b7e-buy-512-555-0142" \ -H "Content-Type: application/json" \ -d '{"phone_number": "+15125550142", "accept_monthly_price": 20, "agent_id": "AGENT_ID"}' ``` 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](https://docs.brilo.ai/api-reference/agents/phone-numbers.md). **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](https://docs.brilo.ai/api-reference/endpoint/call.md) request. Fill in your own number as `to` and send it: ```bash theme={null} curl -X POST https://api.brilo.ai/v1/call \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"agent_id": "AGENT_ID", "to": "+15125550142"}' ``` 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 * [Try a change on a separate version](https://docs.brilo.ai/api-reference/agents/versions.md) before it reaches callers. * [Bring back an earlier greeting](https://docs.brilo.ai/api-reference/agents/versions.md#bring-back-an-earlier-commit) from history. * [Release a number or move it to another agent](https://docs.brilo.ai/api-reference/agents/phone-numbers.md). * [Do the same from Claude or Cursor](https://docs.brilo.ai/api-reference/mcp/connect.md) with the Brilo MCP server. ## 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 > **Do callers hear my change as soon as I update the agent?** > > 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. > **Will updating the greeting remove my agent's actions?** > > 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. > **Why did my update return a versioning\_enabled warning?** > > 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. > **Can I create a new agent through the API?** > > 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. > **Should I use REST or the MCP tools?** > > 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. > **How do I avoid overwriting someone else's change?** > > 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. ## Related * [Versions are branches](https://docs.brilo.ai/api-reference/agents/versions.md), how drafts, publishing and going live fit together * [Buy and release phone numbers](https://docs.brilo.ai/api-reference/agents/phone-numbers.md), price consent, limits and refunds * [API introduction](https://docs.brilo.ai/api-reference/introduction.md), for errors, retries and rate limits * [MCP tools](https://docs.brilo.ai/api-reference/mcp/tools.md), every agent tool and its parameters This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.