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

# Share Links

> Make a link anyone can open to talk to your agent in their browser, then pause, replace or turn it off.

# Share Links

A share link lets anyone talk to your agent from their browser. Send it to a prospect, a
colleague or a client, they open it, press call, and speak with the agent. They do not need a
phone, an app or a Brilo account.

For example, a dental clinic owner who has set up a receptionist agent can send
`https://brilo.ai/talk#q3Vx9...` to their office manager and say "try booking a cleaning".
The office manager hears exactly what a caller would hear.

Each agent has one link at a time. You choose how long it works (a day, a week, a month or for
good), and you can pause it, replace it with a new one or turn it off whenever you like. Calls
made through the link use your workspace's minutes like any other call.

These endpoints do what the **Share** button on an agent does in the dashboard, so a script or an
AI assistant can make and manage links for you.

> [!NOTE]
>
> Share links are being rolled out workspace by workspace. Until they are turned on for your
> workspace, every endpoint on this page answers `403` with `share_links_not_enabled`.

All requests go to `https://api.brilo.ai/v1` with your API key, as described in the
[Introduction](https://docs.brilo.ai/api-reference/introduction.md). Errors share one shape,
`{ "status", "error_code", "message", "details" }`. Branch on `error_code`; the `message` says in
plain words what to change.

## The link object

Every endpoint that returns a link returns it in this shape.

```json theme={null}
{
  "id": "6d1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
  "agent_id": "0b6f3c1a-2d4e-4f5a-8b9c-1d2e3f4a5b6c",
  "url": "https://brilo.ai/talk#q3Vx9mT2bK7yR1nW8pZ4cL6hJ0dF5sA2gE9uY3iO7kM",
  "label": "Demo for Dr Rao's clinic",
  "enabled": true,
  "status": "active",
  "expires_at": "2026-10-26T10:00:00.000Z",
  "call_count": 0,
  "created_at": "2026-10-19T10:00:00.000Z"
}
```

| Field | What it means |
| - | - |
| `url` | The link to send. Treat it like a key: anyone who has it can talk to your agent. |
| `label` | Your own note, for example who the link is for. Visitors never see it. |
| `enabled` | `false` while the link is paused. |
| `status` | `active` (works now), `disabled` (paused), `expired` (past `expires_at`) or `revoked` (turned off for good). |
| `expires_at` | When the link stops working. `null` means it never does. |
| `call_count` | How many calls have started through the link. |

`url` is `null` only for a link made before a security update on our side. That link still works
for anyone who already has it, but it cannot be shown again. [Replace it](#replace-a-link) to get
a new one.

## How long a link works

Send `expires_in` with one of these values. Leave it out and the link works for 7 days.

| `expires_in` | The link works for |
| - | - |
| `1d` | One day |
| `7d` | Seven days (the default) |
| `30d` | Thirty days |
| `never` | Until you pause or turn it off |

The clock starts when you send the request. Sending a new `expires_in` later restarts it from
that moment, which is also how you bring an expired link back.

## Create a link

```http theme={null}
POST /agent/{agent_id}/share-link
```

| Body field | Required | What it does |
| - | - | - |
| `label` | No | A note for you, up to 120 characters. |
| `expires_in` | No | `1d`, `7d`, `30d` or `never`. Defaults to `7d`. |

```bash theme={null}
curl -X POST https://api.brilo.ai/v1/agent/0b6f3c1a-2d4e-4f5a-8b9c-1d2e3f4a5b6c/share-link \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Demo for Dr Rao'\''s clinic", "expires_in": "7d" }'
```

Returns `201` with the [link object](#the-link-object). Send its `url` to whoever should try the
agent.

If the agent already has a link that is not turned off, you get that link back instead of a
second one, so it is safe to retry.

## Get the current link

```http theme={null}
GET /agent/{agent_id}/share-link
```

```bash theme={null}
curl https://api.brilo.ai/v1/agent/0b6f3c1a-2d4e-4f5a-8b9c-1d2e3f4a5b6c/share-link \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns the agent's link, whether it is active, paused or expired, wrapped in `link`. `link` is
`null` when the agent has none, or its last one was turned off.

```json theme={null}
{
  "link": {
    "id": "6d1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
    "status": "disabled",
    "enabled": false,
    "...": "the rest of the link object"
  }
}
```

## Pause, resume or relabel a link

```http theme={null}
PATCH /agent/{agent_id}/share-link/{link_id}
```

Send only what you want to change.

| Body field | What it does |
| - | - |
| `enabled` | `false` pauses the link and ends any call running through it. `true` turns it back on. |
| `label` | A new note, up to 120 characters. Send `""` or `null` to clear it. |
| `expires_in` | A new expiry, counted from now. |

Pause a link while a prospect thinks it over:

```bash theme={null}
curl -X PATCH https://api.brilo.ai/v1/agent/0b6f3c1a-2d4e-4f5a-8b9c-1d2e3f4a5b6c/share-link/6d1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

Bring it back for another month:

```bash theme={null}
curl -X PATCH https://api.brilo.ai/v1/agent/0b6f3c1a-2d4e-4f5a-8b9c-1d2e3f4a5b6c/share-link/6d1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "expires_in": "30d" }'
```

Returns the updated [link object](#the-link-object). Anyone who opens a paused link is told it is
paused right now; the same `url` works again once you turn it back on.

## Replace a link

```http theme={null}
POST /agent/{agent_id}/share-link/{link_id}/regenerate
```

Use this when a link went further than you meant it to. The old `url` stops working at once, any
call running through it ends, and you get a new link with a new `url` and the same label. The new
link works for 7 days, or for good if the old one never expired. No body is needed.

```bash theme={null}
curl -X POST https://api.brilo.ai/v1/agent/0b6f3c1a-2d4e-4f5a-8b9c-1d2e3f4a5b6c/share-link/6d1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns `201` with the new [link object](#the-link-object). Replacing a link that was already
replaced returns the agent's current link, so it is safe to retry.

## Turn off a link

```http theme={null}
DELETE /agent/{agent_id}/share-link/{link_id}
```

Turns the link off for good and ends any call running through it. Anyone who opens it afterwards
is told it has been turned off. To share the agent again, [create a link](#create-a-link).

```bash theme={null}
curl -X DELETE https://api.brilo.ai/v1/agent/0b6f3c1a-2d4e-4f5a-8b9c-1d2e3f4a5b6c/share-link/6d1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{ "id": "6d1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "revoked": true }
```

Turning off a link twice changes nothing and returns the same answer.

## Errors

A missing or wrong API key returns `401`. Everything else:

| Status | `error_code` | What it means | What to do |
| - | - | - | - |
| `400` | `validation_failed` | `label` is over 120 characters, `expires_in` is not one of the values above, or `enabled` is not `true` or `false`. | Fix the field the `message` names. |
| `403` | `share_links_not_enabled` | Share links are not turned on for your workspace yet. | Contact Brilo support. |
| `404` | `agent_not_found` | No agent with this ID in your workspace. | Check the `agent_id`. |
| `404` | `share_link_not_found` | No link with this ID on this agent, or it was turned off (for `PATCH`). | Get the current link with `GET` and use its `id`. |
| `503` | `share_links_unavailable` | New links cannot be made right now. Reading, pausing and turning off still work. | Try again in a few minutes. |

## Limits that protect you

A link is meant for demos, so it has limits that stop a link that went further than intended
from running up your minutes:

* At most 2 calls run through one link at the same time.
* A link can start up to 6 calls in 10 minutes and 30 calls in a day.
* Each call ends at the agent's maximum call length, or after an hour if the agent has none.

Visitors who hit a limit are told to try again later. Your agent's other calls are not affected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.