Agents API
Conversational Agents are in Beta and available on Professional, Scale and Enterprise. On other plans every endpoint returns 403 {"detail": {"code": "feature_disabled", "feature": "ai_agents"}}.
Base URL: https://api.sendseven.com/api/v1/automation
| Method | Path | Scope | Success |
|---|---|---|---|
GET | /agents | automation:read | 200 paginated list |
POST | /agents | automation:create | 201 agent |
GET | /agents/{agent_id} | automation:read | 200 agent |
PATCH | /agents/{agent_id} | automation:update | 200 agent |
DELETE | /agents/{agent_id} | automation:delete | 200 {success, id, message} |
PUT | /agents/{agent_id}/skills | automation:update | 200 agent |
GET / PUT / DELETE | /agents/{agent_id}/draft | automation:read / automation:update | 200 draft — see Drafts & publishing |
POST | /agents/{agent_id}/publish | automation:publish | 200 agent — see Who can publish |
POST | /agents/{agent_id}/avatar | automation:update | 200 draft — see Avatar |
GET | /agents/insights/overview?days=30 | automation:read | 200 — see Insights overview |
GET | /agents/{agent_id}/knowledge-sources | automation:read | 200 list |
POST | /agents/{agent_id}/knowledge-sources | automation:update | 201 source |
PATCH | /agents/{agent_id}/knowledge-sources/{source_id} | automation:update | 200 source |
DELETE | /agents/{agent_id}/knowledge-sources/{source_id} | automation:update | 200 {success, id, message} |
GET / POST / PATCH / PUT / DELETE | /lookup-tables… | automation:* | see Lookup tables |
POST | /agents/{agent_id}/test | automation:update | 200 — see Test console |
GET | /agents/{agent_id}/turns | automation:read | 200 — see Turn log |
GET | /agent-turns/{turn_id} | automation:read | 200 — see One turn |
GET | /agents/{agent_id}/feedback | automation:read | 200 — see Answer ratings & feedback |
GET | /agents/{agent_id}/skill-suggestions | automation:read | 200 — see Skill suggestions |
POST | /agents/{agent_id}/skill-suggestions/generate | automation:update | 201 suggestion |
POST | /agents/{agent_id}/skill-suggestions/{suggestion_id}/approve | automation:update | 200 {suggestion, skill_version} |
POST | /agents/{agent_id}/skill-suggestions/{suggestion_id}/dismiss | automation:update | 200 suggestion |
GET | /hub/stats?days=30 | automation:read | 200 — see Agents overview |
POST | /bots/{bot_id}/duplicate | automation:create | 201 bot — see Duplicate an agent |
GET | /hub/templates | automation:read | 200 {items} — see Templates |
POST | /hub/templates/{key}/create | automation:create | 201 {agent_id, bot_id} |
List agents
GET /agents?page=1&page_size=50&search=support
| Parameter | Notes |
|---|---|
page | Default 1 |
page_size | Default 50, max 100 |
search | Optional, max 100 characters, matches the name |
Returns {"items": [Agent, …], "pagination": {…}}.
Create an agent
POST /agents — unknown fields are rejected with 422.
{
"name": "Shop Support",
"is_active": false,
"persona": "You are Mia, the friendly support assistant of Example Shop.",
"instructions": "Answer questions about orders, shipping and returns.",
"model_tier": "standard",
"display_name": "Mia",
"greeting_message": "Hi! I'm Mia. How can I help?",
"language_settings": {"base_language": "en", "response_language": null},
"escalation": {"enabled": true, "handoff_message": "I'm connecting you with a colleague."},
"tools_config": {"search_knowledge": true, "web_search": false, "handoff": true, "set_state": true},
"handoff_config": {"keywords": ["human"], "max_turns": 30, "max_consecutive_fallbacks": 2, "handoff_tag_ids": ["TAG_ID"], "handoff_tag_hints": {"TAG_ID": "billing questions, invoices, refunds"}},
"skills": [{"skill_id": "SKILL_ID", "mode": null, "pinned_version_id": null}],
"knowledge_sources": [{"source_type": "faq"}]
}
Fields
| Field | Type | Notes |
|---|---|---|
name | string | Required on create. 1-255 characters. |
is_active | boolean | Default true. Create agents inactive, test them, then activate. Switching a paused agent on needs automation:publish. |
publish | boolean | Create only. Default false (since 16 November 2026, before: true): the agent is created never-published (publish_state: "draft") and does not answer contacts until you publish it. true puts it live on create and needs automation:publish (see Who can publish). |
persona | string | Who the agent is and how it speaks. Max 20,000 characters. |
instructions | string | What the agent does. Max 20,000 characters. |
model_tier | standard | advanced | Default standard ("Fast", typically about 1 to 2 AI credits per reply). advanced ("Advanced") costs about 3.3 times as much for the same work (typically about 3 to 8 per reply) and always uses a 15-second turn budget (turn_timeout_ms is ignored). Web search credits are the same. |
display_name | string | Name shown to contacts. Max 255. |
greeting_message | string | Max 2,000. Blank clears it. |
ai_disclosure_message | string | The notice that the contact is talking to an AI. Max 2,000. It cannot be removed: blank or null uses the built-in, localized default. |
ai_disclosure_include_escalation | boolean | Also tell the contact how to reach a human. Default true. |
language_settings | object | See Language settings. |
escalation | object | See Escalation settings. |
tools_config | object | See Tools. |
handoff_config | object | See Hand-off config. |
max_tool_calls | integer | Tool calls allowed per turn. Default 4. Values outside 1..6 are clamped, not rejected. |
turn_timeout_ms | integer | Legacy automatic time budget per turn for model_tier: standard, used only while turn_time_limits.default is not set. Default 8000. Values outside 2000..15000 are clamped. advanced agents always get 15000. |
turn_time_limits | object | Response time limit per turn, in seconds. See Turn time limits. |
add_detected_languages | boolean | Add languages the agent detects from the contact to the contact's languages list. Default true. See Add detected languages to the contact. |
auto_language_switch | boolean | Switch the reply language and the contact's default language when the contact asks for a language or clearly writes in another one. Default true. See Automatic language switch. |
greeting_enabled | boolean | Send the agent's greeting. Default true. See Greeting options. |
skip_greeting_on_question | boolean | Skip the greeting when the first message is already a question or request. Default true. See Greeting options. |
greet_on_direct_start | boolean | Create only; read-only afterwards. true on every agent created through the API, a template, the AI builder or a duplicate (send false on create to keep the earlier behaviour). Agents created before this field existed return false. See Greeting options. |
email_settings | object | How the agent answers emails. See Email settings. |
flow_running_behavior | pause | stop | keep | What the agent does while a flow is running in the conversation. Default pause. See While a flow is running. |
source_footer_enabled | boolean | Show a "Sources" footer under answers based on your knowledge. Default false. |
source_footer_mode | urls_only | urls_and_kb | Default urls_only (links to your website pages only). urls_and_kb also adds a generic "Knowledge Base" line for FAQ and document sources. |
source_link_params | object | Query parameters added to your website links in the footer, per channel. See Source link parameters. |
settings | object | Free-form settings, max 16 KB, max 6 levels deep. |
skills | array | Create only. Up to 50 skill links. |
knowledge_sources | array | Create only. Up to 20 knowledge sources. |
PATCH /agents/{agent_id} accepts the same fields except skills and knowledge_sources, all optional. Use PUT /agents/{agent_id}/skills and the knowledge source endpoints for those.
Language settings
| Field | Notes |
|---|---|
base_language | Max 10 characters. The agent's main language. Response default en. |
response_language | null or auto = answer in the contact's language. A language code = always answer in that language. |
language_detection_strategy | cascade (default behaviour) or fixed (always answer in base_language). |
auto_translate_messages | boolean |
PATCH updates only the language fields you send; omitted fields keep their value.
Auto vs fixed. These are the two language modes the app and the agent builder use:
| Mode | language_detection_strategy | response_language | The agent answers in |
|---|---|---|---|
| Auto | cascade | null | The contact's language |
| Fixed | fixed | the base_language code | base_language |
To switch an agent from fixed to auto, send both fields. If you only change the strategy, the old response_language stays set and the agent keeps answering in that language:
PATCH /agents/{agent_id}
{"language_settings": {"language_detection_strategy": "cascade", "response_language": null}}
To switch to fixed, send {"language_detection_strategy": "fixed", "response_language": "<base_language>"}.
Add detected languages to the contact
add_detected_languages (boolean, default true, also for existing agents) lets the agent remember the languages a contact writes in. When the agent detects the contact's language for the first time in a conversation, or switches because the contact writes in a different language, it appends that code to the contact's languages list. Example: a contact with preferred language de writes in Turkish and the agent switches to tr; the contact's languages becomes de,tr.
- The contact's preferred
languagenever changes, and neither does the language the agent answers in. - Only languages detected from the contact count. A fallback to
base_languageorlanguage_detection_strategy: "fixed"never adds a code. - A code the contact already has (as
languageor inlanguages) is not added again. Each added code updates the contact and fires thecontact.updatedwebhook.
Send it as a top-level add_detected_languages field or inside settings.add_detected_languages (the top-level field wins). On PATCH, omitted or null keeps the current value. In the draft document it is saved with the other agent settings and goes live when you publish. Responses always return a boolean.
Automatic language switch
auto_language_switch (boolean, default true, also for existing agents) lets the agent change language when the contact wants it:
- Explicit request. A message such as "English please", "auf Deutsch bitte" or "Türkçe konuşabilir misiniz?" switches the reply language from that reply on and sets it as the contact's default
language. A message that only mentions a language ("I speak English poorly, but...") does not count. - Clear writing. When the contact keeps writing in another language, the agent switches and sets the new default
language. A language that was only inferred from the contact's phone number switches after one clear message. - A default
languageset by a person, an import or the API is kept unless the contact explicitly asks for another language. - Each change updates the contact (the previous default stays in
languages), fires thecontact.updatedwebhook and adds an internal note to the conversation. Test-console turns never change the contact.
With false, the agent still follows the contact's language in its replies but never changes the contact's default language. Agents with response_language set to a fixed language never switch.
Greeting options
| Field | Default | Effect |
|---|---|---|
greeting_enabled | true | With false the agent sends no greeting and answers the contact's first message directly. |
skip_greeting_on_question | true | When the first message is a question or request (not only "Hi"), the agent skips the greeting and answers it. |
The greeting carries the AI disclosure. It is sent when a flow starts the agent, when a live chat widget auto-starts it, or on Telegram /start. When skip_greeting_on_question skips it, the disclosure opens the agent's first chat reply once, in the language of that reply. Automatically sent emails carry the disclosure in the sign-off when they name the agent (see the table below for new agents). After a handoff between agents only the first agent sends it.
greet_on_direct_start changes these things:
greet_on_direct_start: true (new agents) | false (agents created earlier) | |
|---|---|---|
| Agent answers a channel directly through its activation rules (no flow) | Greeting and disclosure are sent first, exactly like a flow start (skip_greeting_on_question applies). Not on email and not for Assist drafts. | Nothing is sent before the answer. |
greeting_enabled: false, or greeting_message empty | No greeting and no disclosure, on every start path. | No greeting; the disclosure opens the first reply. An empty greeting_message uses the built-in default greeting. |
ai_disclosure_message empty | No disclosure; the greeting is still sent. | The built-in default disclosure is used. |
Automatically sent email (email_settings.reply_mode: "auto") | Only ai_disclosure_message is used. Names the agent: the sign-off carries it. Does not name the agent: it is appended once, to the first automatically sent email of the agent session. Empty ai_disclosure_message: no disclosure in any email. | Names the agent: sign-off with ai_disclosure_message, or the built-in "virtual AI assistant" text when empty. Does not name the agent: nothing is added. |
On create, greeting_message and ai_disclosure_message are filled with the built-in default texts in the agent's base_language (English when no built-in text exists for it) when you send no non-empty value. The disclosure default keeps the {name} placeholder. Blank values are stored as null. greet_on_direct_start itself is never changed by PATCH, settings or a draft publish: a value sent there is ignored.
The greeting itself is written in the language of the contact's first message when that message is long enough to identify the language.
Send greeting_enabled, skip_greeting_on_question and auto_language_switch as top-level fields or inside settings (the top-level field wins). On PATCH, omitted or null keeps the current value; any non-boolean inside settings returns 422. In the draft document they are saved with the other agent settings and go live when you publish. Responses always return booleans.
Escalation settings
Same names and meaning as on the FAQ Bot:
| Field | Notes |
|---|---|
enabled | Whether the agent may hand over to a human. With false, the handoff tool is not offered and the deterministic triggers do not fire. |
offers_escalation | boolean |
handoff_message | Sent to the contact on hand-over. Max 2,000. |
escalation_keywords | Used when handoff_config.keywords is not set. |
offline_escalation_behavior | Live chat: what happens when nobody is online. |
offline_message, outside_hours_message | Max 2,000 each. |
is_escalation_schedule_enabled, escalation_timezone, escalation_schedule | The agent's own hand-over schedule (used in custom mode). |
escalation_schedule_mode | "workspace" (follow the workspace business hours) or "custom" (own schedule). Always set in responses; see Team availability. |
Routing a hand-over to a team member is configured on the agent's bot record. See Hand-off & assignment.
Tools config
| Key | Default | Notes |
|---|---|---|
search_knowledge | true | |
web_search | false | Also needs an enabled web_search knowledge source. Set it explicitly. |
web_search_mode | model when web_search is on, else off | When the agent searches the web: off, model (the agent decides, using the web_search tool), kb_fallback (every search_knowledge call that finds nothing also searches the web with the same query) or always (the first search_knowledge call of each reply also searches the web). Setting a mode also sets web_search (off → false, anything else → true); setting web_search to false sets the mode to off. Agents created before this setting existed keep model. GET always returns the effective mode. See Web search modes. |
live_mode | model | When the agent reads its live sources (live_source knowledge sources with scope: "agent"): off, model (the agent decides, using the read_live_source tool), kb_fallback (read when the Knowledge Base finds nothing) or always (read on every reply). Send null to go back to the default. GET always returns the effective mode. |
web_cache_ttl_minutes | not set | 10-60. How long identical web searches of this agent are reused. Send null to remove it. |
handoff | true | Only offered while escalation is enabled. |
set_state | true | |
load_skill | true | |
read_images | false | Beta. Read images the contact sends. The agent opens a file only when the conversation needs it; reading it is part of the reply's AI work (typically about 0.5 AI credits per image on Fast, about 0.8 on Advanced). Also sets the bot record's vision_enabled. |
read_documents | false | Beta. Read PDF documents the contact sends, charged like images (part of the reply's AI work, typically about 0.8 AI credits per PDF on Fast, about 1.4 on Advanced). |
read_voice_messages | false | Beta. Transcribe the voice notes the contact sends and answer the text as if it had been typed. Audio files that are not voice notes are not transcribed. Charged like images (part of the reply's AI work). When off, the agent replies asking the contact to write their message instead. Up to 3 voice notes per reply, each up to 5 minutes and 20 MB. The transcription model follows the workspace Voice message transcription level, not model_tier. See Voice messages. |
max_images_per_message | 3 | 1-3. Further images in the same message are skipped. |
max_attachments_per_conversation | 10 | 1-50. Images, PDFs and voice notes read in one conversation; after that, files are skipped. |
Unknown keys are rejected. complete_task is not configurable: it exists only when a Flow gives the agent a task. Details in Tools & turn lifecycle.
On PATCH, tools_config is merged into the stored settings: send only the keys you want to change. Responses always contain every key with its effective value. Turn image reading on or off with read_images: it also updates the bot record's vision_enabled. An agent created before read_images existed reports its bot's vision_enabled until you set read_images. Limits and behaviour: Images and PDFs.
Hand-off config
| Field | Notes |
|---|---|
keywords | Up to 50 words (max 100 characters each, de-duplicated case-insensitively). A contact message containing one hands over immediately, before any AI call. When not set, the escalation keywords are used. |
max_turns | 1..200. Hands over once the conversation goes past this many contact turns. |
max_consecutive_fallbacks | 1..20, default 2. Hands over after this many turns in a row in which the agent could not answer. |
handoff_tag_ids | Up to 20 tag ids from your workspace. The agent may pick one of them when it hands over, and the tag is added to the conversation. Unknown tags: 422 {"code": "invalid_handoff_tags", "message": "Unknown handoff tag(s)", "tag_ids": […]}. |
handoff_tag_hints | Optional object {tag_id: "when to use"}, shown to the agent next to each tag. Text is trimmed, empty hints are dropped, each hint is at most 200 characters (longer: 422), at most 20 entries. Hints for tag ids not in handoff_tag_ids are dropped on save. Default {}. |
handoff_message | Max 2,000. Message sent on hand-over. |
handoff_config may be at most 8 KB serialized.
Turn time limits
turn_time_limits sets how long one turn may take before the agent answers with what it has, per channel group:
| Key | Notes |
|---|---|
default | Every channel. null means the legacy automatic budget (turn_timeout_ms, 15 seconds for advanced). |
live_chat | Live Chat override. null means the same as default. |
email | Email override. null means the same as default. |
- Allowed values are
30and60seconds (also listed in the response asturn_time_limit_options). 60 seconds is the maximum: a higher value returns422. A limit above 60 seconds saved earlier is returned and applied as60, and stored as60the next time the agent is saved. - New agents start with
{"default": 30}. Agents created before this setting existed keep the automatic budget until you setdefault. - Overrides apply only while
defaultis set. When it is set, the limit is the whole turn budget for both model tiers andturn_timeout_msis ignored. - Send it as a top-level
turn_time_limitsfield or insidesettings.turn_time_limits(the top-level field wins). Both are partial: omitted keys keep their value andnullclears a key. - Only the keys
default,live_chatandemailare accepted. Another key or value returns422with codeinvalid_turn_time_limit. - The response always contains all three keys.
While a flow is running
flow_running_behavior decides what the agent does in a conversation where a flow run is active:
| Value | Behaviour |
|---|---|
pause (default) | The agent stays silent while the run is active. It answers again from the next incoming message after the run completes, fails, is canceled or times out. A run that waits past its timeout no longer counts as active. |
stop | When a flow run starts in the conversation, the agent is turned off for that conversation, the same as when a person takes over. It answers again only after a person turns it back on, or when a flow step hands the conversation to the agent. |
keep | The agent keeps answering while the run is active. |
- Whether the agent may answer the incoming message that started a flow run is decided by the flow's
agent_reply_to_triggersetting, not by this one. A run that lets the agent answer that message does not pause the agent for it. A flow step that hands the conversation to the agent is the flow's own reply and is not blocked. - A flow can override this value with its own
agent_while_runningsetting. - Omitted on create means
pause; omitted onPATCHkeeps the current value. Any other value returns422. The response always contains a concrete value.
Email settings
email_settings controls how the agent answers emails:
| Key | Notes |
|---|---|
reply_mode | draft (default): every reply is saved as a draft for your team. auto: a reply whose confidence reaches confidence_threshold is sent, anything below becomes a draft. |
confidence_threshold | Integer 0 to 100. Default 80. |
triage_skill_id | A skill of this workspace that decides which emails get a reply at all, see Email triage skills. null (default) uses the built-in triage and clears a set skill. |
- Send it as a top-level
email_settingsfield or insidesettings.email_settings(the top-level field wins). Both are partial: omitted keys keep their value. - A wrong type, a value out of range or an unknown key returns
422with codeemail_settings.invalid. Atriage_skill_idthat is not a skill of this workspace returns422email_settings.invalid_skill. - Even with
reply_mode: "auto", a reply is saved as a draft when it is not backed by your knowledge, skills or verified contact data, when the sender could not be verified, or when a check could not run. - Contact-form emails: when a website contact form sends the email and names the customer in Reply-To, the agent treats that address as the sender and always saves its reply as a draft, also with
reply_mode: "auto".
Source link parameters
Add tracking parameters to links to your website pages in the sources footer. Keys are channel types, or default:
{
"source_link_params": {
"default": {"utm_source": "sendseven", "utm_medium": "{channel_type}"},
"live_chat": {"utm_source": "chat", "utm_content": "{widget_id}"}
}
}
Placeholders: {bot_id}, {bot_name} (as a URL slug), {channel_type}, {channel_id}, {tenant_id}, {widget_id} (Live Chat only). A parameter whose placeholder cannot be filled for a message is left out.
Response
{
"id": "…",
"bot_id": "…",
"tenant_id": "…",
"name": "Shop Support",
"is_active": false,
"persona": "…",
"display_name": "Mia",
"avatar_url": null,
"greeting_message": "…",
"ai_disclosure_message": null,
"ai_disclosure_include_escalation": true,
"instructions": "…",
"model_tier": "standard",
"language_settings": {"response_language": null, "base_language": "en", "auto_translate_messages": false, "language_detection_strategy": null},
"escalation": {"enabled": true, "offers_escalation": true, "handoff_message": "…", "escalation_keywords": null, "offline_escalation_behavior": "leave_message", "offline_message": null, "outside_hours_message": null, "is_escalation_schedule_enabled": false, "escalation_timezone": "UTC", "escalation_schedule": null, "escalation_schedule_mode": "workspace"},
"source_footer_enabled": false,
"source_footer_mode": "urls_only",
"source_link_params": null,
"tools_config": {"search_knowledge": true, "web_search": false, "handoff": true, "set_state": true, "load_skill": true, "read_images": false, "read_documents": false, "read_voice_messages": false, "max_images_per_message": 3, "max_attachments_per_conversation": 10},
"handoff_config": {"keywords": ["human"], "max_turns": 30, "max_consecutive_fallbacks": null, "handoff_tag_ids": [], "handoff_message": null},
"max_tool_calls": 4,
"turn_timeout_ms": 8000,
"turn_time_limits": {"default": 30, "live_chat": null, "email": 60},
"turn_time_limit_options": [30, 60],
"add_detected_languages": true,
"auto_language_switch": true,
"greeting_enabled": true,
"skip_greeting_on_question": true,
"greet_on_direct_start": true,
"email_settings": {"reply_mode": "draft", "confidence_threshold": 80, "triage_skill_id": null},
"flow_running_behavior": "pause",
"settings": null,
"skills": [
{"skill_id": "…", "slug": "order-return", "title": "Order returns", "mode": null, "effective_mode": "model_selected", "pinned_version_id": null, "current_version": 3, "pinned_version": null, "is_archived": false, "sort_order": 0}
],
"knowledge_sources": [
{"id": "…", "source_type": "faq", "kb_folder_id": null, "kb_folder_name": null, "allowed_domains": null, "is_enabled": true, "config": null, "sort_order": 0, "created_at": "2026-10-05T09:00:00Z", "updated_at": "2026-10-05T09:00:00Z"}
],
"publish_state": "published",
"has_unpublished_changes": false,
"draft_updated_at": null,
"published_at": "2026-10-05T09:00:00Z",
"created_at": "2026-10-05T09:00:00Z",
"updated_at": "2026-10-05T09:00:00Z"
}
publish_state, has_unpublished_changes, draft_updated_at and published_at are explained in Drafts & publishing. The fields above always show the live configuration.
Delete an agent
DELETE /agents/{agent_id} deletes the agent with its bot record, channel rules, sessions, skill links and knowledge sources. Skills themselves are kept.
While a published or paused Flow uses the agent, the delete is refused:
{
"detail": {
"code": "agent_in_use",
"message": "This agent is used by published or paused flows. Remove it from these flows first.",
"flows": [{"id": "…", "name": "Returns", "status": "published", "node_ids": ["node_7"]}]
}
}
Duplicate an agent
POST /bots/{bot_id}/duplicate (automation:create) copies a Conversational Agent inside the same workspace and returns the new bot (201, same shape as GET /bots/{bot_id}).
{"name": "Support (EN)"}
name is optional. Without it the copy is called <name> (Kopie) in German workspaces and <name> (copy) otherwise.
| Copied | Not copied |
|---|---|
| Persona, instructions, greeting, language, escalation and tool settings | Channel rules (the copy is not connected to any channel) |
| Skill links incl. mode and pinned versions (the skills are shared, not cloned) | Conversations, sessions, replies, ratings, feedback, skill suggestions |
| Knowledge sources: Knowledge Base folders, FAQ, web search domains, live sources | Usage counters and history |
The copy is paused (is_active: false) and placed last in the bot order. Only Conversational Agents can be duplicated: other bot types return 422 {"detail": {"code": "duplicate_classic_not_supported"}}. A bot from another workspace returns 404.
Templates
GET /hub/templates (automation:read) lists the ready-made agent templates in a fixed order:
{"items": [{"key": "product_faq", "has_goal": false, "suggested_channels": ["whatsapp", "live_chat", "email"], "skills": ["answer-product-questions"]}]}
Keys: product_faq, customer_support, lead_qualification, appointment_booking, email_reply, feedback_nps. has_goal is true when a template skill collects data with a goal. Titles and descriptions are not returned; show your own copy per key.
POST /hub/templates/{key}/create (automation:create) creates a paused agent with persona, greeting, hand-off message, skills and knowledge sources (Knowledge Base + FAQ) from the template, written in your workspace language (German or English; other languages get English). Returns 201 {"agent_id": "…", "bot_id": "…"}. No AI credits are used. Unknown key: 404 template_not_found. Duplicate and template create use the same plan gate as POST /agents.
Agents overview
GET /hub/stats?days=30 (automation:read) returns KPIs and one row per bot of the workspace (Conversational Agents and classic bots, paused ones included), in the same order as PUT /bots/reorder. days is 7, 30 (default) or 90 calendar days in your workspace timezone, today included; any other value returns 422.
{
"range_days": 30, "period_start": "2026-09-06T22:00:00Z", "period_end": "2026-10-06T21:59:59Z",
"series_dates": ["2026-09-07", "…", "2026-10-06"], "min_sample": 20, "truncated": false,
"totals": {"conversations": 808, "conversations_prev": 721, "conversations_delta_pct": 12.07,
"resolved": 513, "resolved_pct": 63.5, "handoffs": 295, "handoff_pct": 36.5,
"insufficient_data": false, "credits": 1412, "credits_eur": 14.12},
"agents": [{
"bot_id": "BOT_ID", "agent_id": "AGENT_ID", "name": "Support Agent", "bot_type": "agent", "kind": "agent",
"subtitle": {"type": "goal", "label": "Book a demo"}, "status": "live", "has_unpublished_changes": false,
"priority": 3, "avatar_url": null,
"channels": [{"channel_id": "CHANNEL_ID", "channel_type": "whatsapp", "name": "WA Support"}],
"skills_count": 5, "conversations": 120, "conversations_prev": 98, "resolved": 98, "resolved_pct": 81.7,
"handoffs": 22, "handoff_pct": 18.3, "insufficient_data": false, "credits": 310,
"sparkline": [0, 3, 5], "updated_at": "2026-10-04T10:12:00Z", "updated_by_name": null
}]
}
Definitions (shared with GET /analytics, GET /bots/{bot_id}/analytics and agent analytics, so the numbers always match):
- Conversation: a conversation the bot replied in during the period, counted once per bot, dated by its first reply. Test-console replies are not counted.
- Handoff: a conversation in which the bot handed over to your team. Resolved = conversations − handoffs. Both percentages are always between 0 and 100.
resolved_pct/handoff_pctper bot arenull(andinsufficient_data: true) belowmin_sample(20) conversations. Intotalsthey arenullonly without conversations; a conversation several bots replied in counts once there.conversations_previs the same-length window before;conversations_delta_pctisnullwhen it is 0.creditsare the AI credits Conversational Agents used (classic bots show0);credits_euruses your plan's AI credit price.status:paused= switched off;not_connected= switched on, but no active channel rule (or published Flow) can route a message to it; otherwiselive.subtitle.type:goal(label = title of the first skill with a goal),template(label = template key) ornone.
Skill links
PUT /agents/{agent_id}/skills replaces all of the agent's skill links. Send an empty list to unlink every skill.
{
"skills": [
{"skill_id": "SKILL_ID_BASICS", "mode": "always_on"},
{"skill_id": "SKILL_ID_RETURNS", "pinned_version_id": "VERSION_ID", "sort_order": 1}
]
}
| Field | Notes |
|---|---|
skill_id | Required. A skill in your workspace. |
mode | always_on, model_selected, flow_only or null (use the skill's default_mode). |
pinned_version_id | null = follow the skill's current version. Otherwise a version of this skill; the agent keeps using it when the skill changes. |
sort_order | 0..10000 |
sources | Optional per-skill source override (see below). Omit it to keep the stored override; send null to remove it. |
sources changes the agent's sources while this skill is loaded:
{"skill_id": "SKILL_ID_PRICES", "sources": {"web_search_mode": "off", "live_source_ids": ["LIVE_SOURCE_ID"], "live_mode": "always", "kb_folder_ids": ["KB_FOLDER_ID"], "kb_mode": "add"}}
| Key | Notes |
|---|---|
web_search_mode | off, model, kb_fallback, always or null (use the agent's mode). |
live_source_ids | Up to 5 ids of this agent's live_source knowledge sources. Any other id returns 422 {"code": "invalid_skill_sources"}. |
live_mode | model, kb_fallback, always or null (use the agent's live_mode). |
kb_folder_ids | Up to 10 Knowledge Base folder ids searched while this skill is loaded, subfolders included. Any folder of your workspace works (also one the agent has no source for), except the system folders for conversation history and ticket summaries. An unknown id returns 422 {"code": "invalid_skill_sources"}. |
kb_mode | add (default, also for null): the agent's own Knowledge Base sources plus these folders. only: only these folders while the skill is loaded. only needs at least one folder (422 otherwise); without folders kb_mode is ignored. |
Knowledge Base scope when several skills are loaded. One reply can load several skills, so SendSeven searches the union of what they allow:
- The folders of every loaded skill that has
kb_folder_idsare searched (addandonlyalike). - The agent's own Knowledge Base sources (its
kb_all,kb_folderandfaqsources, or the whole Knowledge Base when it has none) are searched too, unless every loaded skill with a Knowledge Base override isonly. A single loaded skill withadd, or with no Knowledge Base override at all, brings them back. - Skills with mode
always_onthat have no Knowledge Base override do not count: they are loaded on every reply, so they would otherwise cancelonlyeverywhere. Analways_onskill withkb_mode: "only"narrows every reply unless another loaded skill saysadd. - Conversation-history and ticket-summary folders are never searched, also not through a skill.
This is relevance scoping, not access control. The AI picks model_selected skills from the conversation, so a customer can steer which skill loads. Keep sensitive content behind a skill that only a Flow loads (flow_only) or behind identity verification.
Overrides are stored in the agent's settings.skill_sources (keyed by skill id) and can also be written there with PATCH /agents/{agent_id}, validated the same way. A PATCH whose settings leave out skill_sources keeps the stored overrides; "settings": null clears everything. Overrides of skills that are no longer linked are dropped, and deleting a live source removes its id from every override. A deleted Knowledge Base folder disappears from every override on read; when a skill loses all its folders, its Knowledge Base override is removed (kb_folder_ids: [], kb_mode: null), so only never searches nothing. Responses show each link's override in skills[].sources (null = none) with all five keys.
Max 50 links. Returns 422 for a duplicate skill_id, an unknown skill_id, an archived skill, or a pinned_version_id that does not belong to the skill. The response is the full agent; each link shows effective_mode, current_version and pinned_version.
Knowledge sources
source_type | Extra fields | Searches |
|---|---|---|
kb_folder | kb_folder_id (required) | One Knowledge Base folder |
kb_all | — | Every folder that is enabled for AI search |
faq | — | All published FAQ entries |
web_search | allowed_domains (optional, max 50) | The web, limited to these domains when set |
live_source | config (required, see below) | One web page, read live when the agent answers |
lookup_table | config (required, see below) | One lookup table: exact matches on its search columns |
curl -X POST "https://api.sendseven.com/api/v1/automation/agents/AGENT_ID/knowledge-sources" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"source_type": "web_search", "allowed_domains": ["https://www.example.com/help", "docs.example.com"]}'
| Field | Notes |
|---|---|
source_type | Create only, cannot be changed. |
kb_folder_id | Only for kb_folder. |
allowed_domains | Only for web_search. Entries are normalised to bare host names: https://Www.Example.com/path becomes www.example.com, *.example.com becomes example.com. IP addresses are rejected. |
is_enabled | Default true. A disabled source is ignored. |
config | Max 4 KB. Free-form, except for live_source and lookup_table (see below). |
sort_order | 0..10000 |
Live sources
A live_source is one public page whose current content the agent reads while answering — for example opening hours, prices or stock levels that change too often for the Knowledge Base.
{
"source_type": "live_source",
"config": {
"url": "https://www.example.com/opening-hours",
"label": "Opening hours",
"description": "Current opening hours of all stores",
"ttl_minutes": 15
}
}
config key | Default | Notes |
|---|---|---|
url | — | Required. Must start with http:// or https:// and point to a public address (private networks are rejected). Max 2048 characters. |
label | — | Required. 1-80 characters, unique per agent (case-insensitive). |
description | "" | Max 500 characters. Tells the agent when to read this source. |
match | exact | exact or prefix. |
ttl_minutes | 15 | 5-1440. How long a fetched page is reused. |
fetcher | auto | auto, own or linkup_render. |
scope | agent | agent (available on every reply, see tools_config.live_mode) or skills (only while a skill whose sources.live_source_ids lists it is loaded). |
allowed_domains and kb_folder_id must be absent or null. At most 10 live sources per agent. On PATCH, config is merged into the stored config and validated again.
Lookup-table sources
A lookup_table source gives the agent one of your lookup tables. The agent then finds the matching rows in one step (for example the branch responsible for a postcode or a town) instead of searching the Knowledge Base several times.
{
"source_type": "lookup_table",
"config": {
"table_id": "LOOKUP_TABLE_ID",
"label": "Branch by postcode",
"description": "Use when the customer gives a postcode or town and asks which branch is responsible"
}
}
config key | Default | Notes |
|---|---|---|
table_id | — | Required. A lookup table of this workspace. |
label | the table name | Max 80 characters. Only stored when you send it, so a renamed table shows its new name. |
description | — | Max 500 characters. Tells the agent when to use the table. |
allowed_domains and kb_folder_id must be absent or null. At most 5 lookup tables per agent, each table once. On PATCH, config is merged into the stored config (send null for label or description to clear it) and checked again. Responses add a read-only table object for these sources: {id, name, description, row_count, key_columns, version}, or null when the table no longer exists. The table's content is not part of the agent's draft: replacing a table's file is live for every agent at once.
- When the agent has no
kb_folder,kb_allorfaqsource, it searches your whole AI-searchable Knowledge Base. - Conversation-history and ticket-summary folders are never searched.
search_knowledgesearches up to 8 sources per call, FAQ first.
GET …/knowledge-sources returns {"items": [...], "pagination": {...}} with all sources (max 20, no paging parameters).
Knowledge source errors
| Status | Detail |
|---|---|
422 | "kb_folder_id does not exist" |
422 | "This folder cannot be used as an agent knowledge source" (conversation-history and ticket-summary folders) |
422 | {"code": "use_faq_source", "message": "…"} — the managed FAQ folder cannot be added as a folder. Add a faq source instead. |
422 | "At most 20 knowledge sources per agent" |
422 | kb_folder_id or allowed_domains on the wrong source_type |
422 | {"code": "live_source_limit", "message": "…"} — at most 10 live sources per agent |
422 | {"code": "live_source_label_taken", "message": "…"} — another live source of the agent has this label |
422 | {"code": "invalid_live_source_url", "error_code": "…", "message": "…"} — the URL cannot be used (for example a private address or a host that does not exist) |
422 | {"code": "invalid_live_source", "message": "…"} — invalid config on PATCH |
422 | {"code": "lookup_table_not_found", "message": "…"} — config.table_id is not a lookup table of this workspace |
422 | {"code": "lookup_table_already_attached", "message": "…"} — the agent already uses this table |
422 | {"code": "lookup_table_source_limit", "message": "…"} — at most 5 lookup tables per agent |
422 | {"code": "invalid_lookup_table_source", "message": "…"} — invalid config on PATCH |
404 | "Knowledge source not found" |
Lookup tables
A lookup table is a table you upload once (CSV or XLSX, or a table document from your Knowledge Base) and that agents search by exact value: postcode to branch, product number to price, town to district. Lookup tables belong to the workspace; attach one to an agent with a lookup_table source. They need Conversational Agents and the Knowledge Base on your plan (Professional, Scale, Enterprise); otherwise every endpoint returns 403 {"code": "feature_disabled"}.
| Method | Path | Scope | Success |
|---|---|---|---|
GET | /lookup-tables | automation:read | 200 {items, pagination} |
POST | /lookup-tables/inspect | automation:update | 200 sheets of an upload, nothing stored (multipart) |
POST | /lookup-tables | automation:update | 201 table with preview (multipart upload) |
POST | /lookup-tables/from-document | automation:update and knowledge_base:read | 201 table with preview |
GET | /lookup-tables/{table_id} | automation:read | 200 table with preview |
GET | /lookup-tables/{table_id}/rows?page=1&page_size=20 | automation:read | 200 {items, pagination} |
POST | /lookup-tables/{table_id}/lookup | automation:read | 200 lookup result |
PATCH | /lookup-tables/{table_id} | automation:update | 200 table with preview |
PUT | /lookup-tables/{table_id}/file | automation:update | 200 table with preview (new version) |
POST | /lookup-tables/{table_id}/refresh | automation:update and knowledge_base:read | 200 table with preview (new version) |
DELETE | /lookup-tables/{table_id} | automation:delete | 200 {success, id, message} |
A table created from a Knowledge Base document holds Knowledge Base content: its rows and lookup also need knowledge_base:read (403 without it), and its detail returns preview_rows: [] without that scope.
Upload a table
curl -X POST "https://api.sendseven.com/api/v1/automation/lookup-tables" \
-H "Authorization: Bearer $TOKEN" \
-F "[email protected]" \
-F "name=Branch by postcode" \
-F 'key_columns=["Postcode", "Town"]'
| Form field | Notes |
|---|---|
file | Required. .csv or .xlsx, at most 5 MB. CSV: UTF-8 or Windows-1252, separated by , ; tab or |. XLSX: the first sheet unless sheet is set; formulas are not calculated (the last saved value is used). The first non-empty row is the header. |
name | Required. 1-120 characters, unique in the workspace (case-insensitive). |
description | Max 500 characters. |
sheet | XLSX sheet name. |
key_columns | JSON list of 1-5 column names to search by. Leave it out and SendSeven picks suggested columns. |
return_columns | JSON list of the columns the agent gets back. Empty or left out = all columns. |
Limits: 20 lookup tables per workspace, 20,000 rows and 50 columns per table, 1,000 characters per cell.
Inspect a file (several sheets)
To import several sheets of one workbook, inspect the file first, then create one table per sheet with POST /lookup-tables and sheet=<name>. POST /lookup-tables/inspect (multipart, only file; same 5 MB limit and file checks as the upload) stores nothing:
curl -X POST "https://api.sendseven.com/api/v1/automation/lookup-tables/inspect" \
-H "Authorization: Bearer $TOKEN" \
-F "[email protected]"
{
"filename": "pricing.xlsx",
"file_format": "xlsx",
"sheets": [
{
"name": "Branches", "index": 0, "row_count": 912, "column_count": 4,
"columns": ["Postcode", "Town", "District", "Branch"],
"preview_rows": [["86830", "Schwabmünchen", "Augsburg", "Augsburg"]],
"warnings": [], "error": null
},
{
"name": "Raw export", "index": 2, "row_count": 0, "column_count": 0, "columns": [],
"preview_rows": [], "warnings": [],
"error": {"code": "too_many_columns", "message": "…", "detail": {"max_columns": 50, "columns": 51}}
}
],
"skipped_empty_sheets": ["Notes"],
"tables_remaining": 17
}
sheets: one entry per sheet with content, in workbook order (indexis the 0-based sheet position). A CSV file has exactly one entry, named after the file.preview_rowsholds up to 5 rows incolumnsorder.error:nullwhen the sheet can become a table. Otherwise thecodethatPOST /lookup-tableswith thissheetwould return (for exampletoo_many_rows,too_many_columns,no_header,empty_table); counts and preview then show what was read before the problem. One bad sheet never fails the whole request.- At most 20 sheets with content are read. Later sheets are listed with
error.codetoo_many_sheetsand no counts. skipped_empty_sheets: sheets without a single filled cell.tables_remaining: how many more tables the workspace can create (20 per workspace). Each sheet you import counts as one table.- Problems with the whole file (format, size, unreadable workbook) return the usual
422errors below;503 parser_busywhen too many files are being processed.
POST /lookup-tables/from-document takes JSON {"kb_document_id", "name", "description"?, "key_columns"?, "return_columns"?}. The Knowledge Base document must be an uploaded CSV or XLSX file, or contain exactly one Markdown table. POST /lookup-tables/{table_id}/refresh reads that document again (only for tables created this way).
Table object
{
"id": "LOOKUP_TABLE_ID",
"name": "Branch by postcode",
"description": null,
"origin": "upload",
"kb_document_id": null,
"original_filename": "branches.csv",
"file_format": "csv",
"sheet_name": null,
"columns": ["Postcode", "Town", "District", "Branch"],
"key_columns": ["Postcode", "Town"],
"return_columns": [],
"settings": {"prefix": true, "fuzzy": true},
"row_count": 912,
"size_bytes": 41230,
"version": 3,
"agents": [{"id": "AGENT_ID", "name": "Advice Agent"}],
"created_at": "2026-10-22T09:00:00Z",
"updated_at": "2026-10-22T09:30:00Z",
"preview_rows": [{"row_index": 0, "values": {"Postcode": "86830", "Town": "Schwabmünchen", "District": "Augsburg", "Branch": "Augsburg"}}],
"warnings": [],
"suggested_key_columns": ["Postcode", "Town"]
}
origin:uploadorkb_document.file_format:csv,xlsxormd.return_columns: empty = all columns.versiongoes up with every file replace or refresh.agents: agents whose live configuration or saved draft uses the table.preview_rows(first 20 rows),warningsandsuggested_key_columnsare only in single-table responses.warningsandsuggested_key_columnsare filled right after an upload, replace or refresh (for example a warning when a numeric column may have lost leading zeros), and empty onGET.- The list endpoint returns the same object without the three preview fields.
Change settings
PATCH /lookup-tables/{table_id} with any of name, description (null clears it), key_columns (1-5 columns, not null), return_columns (null or [] = all columns) and settings:
settings key | Default | Notes |
|---|---|---|
prefix | true | A search also matches values that start with the query (at least 3 characters). |
fuzzy | true | When nothing else matches, close spellings (at least 5 characters) are offered, and the agent asks the customer to confirm. |
Replace the file
PUT /lookup-tables/{table_id}/file (multipart: file, optional sheet, key_columns, return_columns) loads a new version. The switch is atomic and applies to every agent right away; a conversation never sees a mix of old and new rows. The current search and return columns are kept when they all still exist in the new file; otherwise send new ones or you get 422 lookup_table_columns_missing with missing.
Try a lookup
POST /lookup-tables/{table_id}/lookup with {"query": "Buxheim", "column": "Town"} (column optional) runs the same search the agent runs and costs nothing:
{
"status": "ok",
"match": "exact",
"total_matches": 2,
"truncated": false,
"rows": [
{"row_index": 14, "values": {"Postcode": "87740", "Town": "Buxheim", "Branch": "Memmingen"}, "matched_column": "Town"},
{"row_index": 15, "values": {"Postcode": "85114", "Town": "Buxheim", "Branch": "Ingolstadt"}, "matched_column": "Town"}
],
"latency_ms": 4.2,
"version": 3
}
status: ok, no_match, invalid_query or not_found. match shows which step found the rows: exact (the whole value), term (every word or number of the query, best matches first), prefix or fuzzy (confirm with the customer). Every matching row is returned, up to 20 (truncated is true when there are more), so an ambiguous value such as a town that exists twice shows all candidates.
Delete a table
DELETE /lookup-tables/{table_id} deletes the table and all its rows. While an agent uses it (live or in a saved draft) the response is 409 with the agents to change first:
{"detail": {"code": "lookup_table_in_use", "message": "…", "agents": [{"id": "AGENT_ID", "name": "Advice Agent"}]}}
Lookup table errors
Errors use {"detail": {"code", "message", …}}. File contents are never echoed back.
| Status | code | When |
|---|---|---|
404 | lookup_table_not_found | No such table in this workspace |
404 | document_not_found | The Knowledge Base document does not exist |
409 | lookup_table_in_use | Delete while agents use the table (agents) |
422 | unsupported_format | Not a .csv or .xlsx file |
422 | file_too_large | Over 5 MB (max_bytes) |
422 | too_many_rows / too_many_columns | Over 20,000 rows or 50 columns |
422 | no_header / empty_table | No header row, or no data rows |
422 | invalid_encoding / invalid_csv / invalid_xlsx | The file cannot be read |
422 | sheet_not_found | sheet is not in the workbook (sheet, sheets) |
422 | too_many_sheets | Only in an inspect sheet error: the workbook has more than 20 sheets with content |
422 | document_not_table / markdown_no_table | The document is not a table |
422 | lookup_table_name_taken | Another table has this name |
422 | lookup_table_limit | 20 tables per workspace reached |
422 | invalid_key_columns / invalid_return_columns | Unknown columns, more than 5 search columns, or not a JSON list |
422 | lookup_table_columns_missing | The new file lacks configured columns (missing) |
422 | lookup_table_not_kb_document | refresh on an uploaded table |
422 | invalid_field / invalid_config | Invalid name, description or settings (field) |
429 | rate_limit_exceeded | Too many files sent from this workspace (see below). Wait retry_after seconds (also in the Retry-After header) |
503 | parser_busy | Too many files are being processed right now (inspect, create, replace, from-document, refresh). Retry in a moment |
File uploads are limited per workspace: POST /lookup-tables/inspect 10 per minute and 60 per hour; POST /lookup-tables and PUT /lookup-tables/{table_id}/file together 30 per minute and 200 per hour. Over a limit the response is 429 with {"detail": {"code": "rate_limit_exceeded", "error": "rate_limit_exceeded", "message", "retry_after"}} and a Retry-After header. When you import several sheets of one workbook, create the tables one after another; the 20-tables-per-workspace cap stays well inside the create limit.
Analytics
GET /agents/{agent_id}/analytics?days=30 (automation:read). days is 7, 30 (default) or 90 calendar days in your workspace timezone, today included. Test-console replies are not counted. At most 20,000 replies are counted (truncated: true beyond).
{
"agent_id": "AGENT_ID", "days": 30, "from": "2026-09-06T22:00:00Z", "to": "2026-10-06T10:00:00Z",
"timezone": "Europe/Berlin", "truncated": false,
"totals": {"turns": 120, "conversations": 64, "answered": 101, "handoffs": 12, "fallbacks": 4, "errors": 3,
"kb_searches": 140, "kb_zero_hit_turns": 18, "kb_search_turns": 110, "web_searches": 25, "web_turns": 21,
"web_cache_hits": 6, "live_reads": 30, "live_turns": 28, "enforced_lookups": 9,
"grounding_checked": 80, "grounding_rewrites": 5, "grounding_handoffs": 1, "credits_billed": 260},
"rates": {"web_fallback_rate": 0.175, "kb_zero_hit_rate": 0.1636, "handoff_rate": 0.1, "grounding_rewrite_rate": 0.075},
"credits_per_conversation": 4.06,
"daily": [{"date": "2026-09-07", "turns": 3, "handoffs": 0, "web_searches": 1, "live_reads": 1,
"kb_zero_hit_turns": 0, "grounding_rewrites": 0, "credits_billed": 7}]
}
answeredcounts answered replies and completed Flow tasks.web_fallback_rate=web_turns / turns;kb_zero_hit_rate=kb_zero_hit_turns / kb_search_turns;handoff_rate=handoffs / turns;grounding_rewrite_rate=(grounding_rewrites + grounding_handoffs) / grounding_checked. A rate isnullwhen its denominator is 0;credits_per_conversationisnullwithout conversations.grounding_*count the answer check (replies whose facts were checked against the sources). Replies sent before the check existed are not ingrounding_checked.dailyhas one entry per day, days without replies included.
Knowledge-gap suggestions
Questions the agent answered from a web search because your Knowledge Base had nothing are turned into draft FAQ entries for you to review. Drafts are never published automatically; review them in the FAQ list.
POST /agents/{agent_id}/kb-gap-suggestions (automation:update and knowledge_base:create, because it writes FAQ drafts; missing either one returns 403), body {"days": 30} (optional, 1-90, default 30):
{"created": 3, "skipped_existing": 2, "skipped_volatile": 1, "candidates": 9, "draft_ids": ["FAQ_ID_1", "FAQ_ID_2", "FAQ_ID_3"]}
skipped_existing = already covered by your FAQ; skipped_volatile = answered from live sources (changing data, never drafted). One run per agent at a time: a second run returns 409 {"code": "gap_run_in_progress"}. Starting runs is rate-limited per workspace (429, 3 per minute and 20 per hour). 503 {"code": "kb_gap_unavailable"} when the feature is temporarily unavailable.
GET /agents/{agent_id}/kb-gap-suggestions?page=1&page_size=20 (automation:read, page_size max 100) lists this agent's drafts that are not archived, newest first:
{
"items": [{"id": "FAQ_ID_1", "question": "…", "answer": "…", "status": "draft", "created_at": "2026-10-06T08:00:00",
"review_notes": "…", "source_conversation_count": 3}],
"pagination": {"total": 1, "page": 1, "page_size": 20}
}
Common errors
| Status | When |
|---|---|
403 | {"code": "feature_disabled", "feature": "ai_agents"} (or ai_features; lookup tables also knowledge_base) — the plan does not include Conversational Agents. A missing scope returns 403 "Insufficient scopes". |
404 | "Agent not found" |
409 | agent_in_use on delete |
422 | Validation errors: unknown fields, lengths, enums, JSON size limits, handoff tags, skill links, knowledge sources |
See Billing, errors & limits for the full list.