Skip to content

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

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
Ventana de terminal
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

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.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/agents/<agent_id>"

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

Ventana de terminal
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.

  • 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_ids outside them is 403 insufficient_scope.
  • If agents are created while you page, one may repeat on the next page: keep one per id.