Agents
Your account's agents: what the API returns for each one, how to filter them by venue and how to rename them.
The agents endpoints return your account’s agents: their name, type, language, the venue they serve and their tags. They resolve the ids other endpoints take (agent_ids on Calls). Reading needs the bots:read scope; renaming an agent needs bots:write.
| Endpoint | Route | Scope |
|---|---|---|
| List agents | GET /v1/agents |
bots:read |
| One agent | GET /v1/agents/{agent_id} |
bots:read |
| Rename an agent | PATCH /v1/agents/{agent_id} |
bots:write |
List agents
Section titled “List agents”GET /v1/agents returns your account’s active agents, paged.
| Parameter | Type | Default | Rules |
|---|---|---|---|
venue_ids |
UUID, repeatable | all your venues | At most 100; only the agents of those venues (ids from GET /venues) |
agent_ids |
string, repeatable | all | At most 100; only those agents |
limit |
1 to 100 | 50 | Agents per page |
cursor |
string | none | meta.next_cursor of the previous page, with the same filters and the same limit |
customer_id |
UUID | the key’s customer | See what each key reads |
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/agents?limit=50"{ "data": [ { "id": "…", "name": "Front desk", "type": "HOTEL_BOT", "language": "ENGLISH", "venue_id": "…", "venue_group_id": null, "tags": [] } ], "meta": { "limit": 50, "next_cursor": null }}| Field | What it is |
|---|---|
id |
The agent’s identifier; the agent_id of the calls |
name |
The agent’s name in the portal |
type |
The agent’s kind, e.g. RESTAURANT, HOTEL_BOT, FLEXBOT_V2 |
language |
The agent’s default language, as set in the portal: SPANISH, CATALAN, ENGLISH… |
venue_id |
The venue it serves, if one |
venue_group_id |
The venue group it serves, if one |
tags |
The agent’s tags |
One agent
Section titled “One agent”GET /v1/agents/{agent_id} returns the same fields for one agent, with an ETag header: the version to send as If-Match when you rename it. An agent that is not your customer’s, or outside the venues your key is limited to, is 404 not_found.
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/agents/<agent_id>"Rename an agent
Section titled “Rename an agent”PATCH /v1/agents/{agent_id} changes the agent’s display name, and nothing else. name is required, 1 to 120 characters. Send the agent’s ETag as If-Match (see Writing data).
curl -s -X PATCH "$BASE/agents/<agent_id>" \ -H "apikey: $BOOKLINE_API_KEY" \ -H "Content-Type: application/json" \ -H 'If-Match: "<etag>"' \ -d '{"name": "Front desk"}'The answer is the agent as stored, with its new ETag. The agent’s configuration is changed in the portal.
Data rules
Section titled “Data rules”- Only the fields on this page. The agent’s internal configuration (texts, integrations, credentials) is not part of the API, and only the name can be changed.
- Active agents. Deleted agents are neither listed nor readable by id.
- Venue-restricted keys. The key lists only the agents of those venues, and a
venue_idsoutside them is 403insufficient_scope. - If agents are created while you page, one may repeat on the next page: keep one per
id.
Related
Section titled “Related”- Calls, Chats and Bookings: filter them with
agent_ids. - Writing data: versions, retries and the write limit.
