This reference applies to both the REST API and MCP tools. The exported schemas describe the operations currently available to an individual key; this page describes all supported resource operations.
Supported scopes
Grant names use {scope}:{action}, such as contacts:read. MCP tool names use {action}_{scope}, such as read_contacts.
| Scope | Browse | Read | Edit | Add | Delete |
|---|---|---|---|---|---|
custom_agents |
Yes | Yes | Yes | Yes | Yes |
knowledge_articles |
Yes | Yes | Yes | Yes | Yes |
knowledge_categories |
Yes | Yes | Yes | Yes | Yes |
knowledge_documents |
Yes | Yes | Yes | — | Yes |
forms |
Yes | Yes | Yes | Yes | Yes |
contacts |
Yes | Yes | Yes | Yes | Yes |
contact_groups |
Yes | Yes | Yes | Yes | Yes |
chat_widgets |
Yes | Yes | Yes | Yes | Yes |
bookings |
Yes | Yes | Yes | — | Yes |
workflows |
Yes | Yes | Yes | — | Yes |
agent_tools |
Yes | Yes | Yes | — | Yes |
There are 51 supported operations across 11 scopes. A key receives only explicitly assigned operations that remain within its owner's access. Select all in API settings grants the available actions in one scope; future operations require an explicit assignment.
Common rules
- REST Add and Edit use a flat JSON object. MCP Add and Edit place the same object inside
arguments.attributes. - Fields marked Required on Add must be supplied when creating a resource. Edit sends only the fields to change and requires at least one attribute.
string(n)means a string with a maximum ofncharacters.textmeans a string with a maximum of 100,000 characters.nullablefields accept JSONnull.- Boolean fields use JSON
trueorfalse. IDs and integer fields use JSON numbers. Browse usespage,per_page, andsearchas described in the REST guide. - Resource references must point to the same company and workspace as the key. Category parents cannot form a cycle.
- Slugs contain only ASCII letters, numbers, underscores, and hyphens, with a maximum length of 255. For Add, omitted slugs are generated from the title or name with a random suffix. Slugs must be unique within the resource's company.
- Every Browse, Read, Add, and Edit result includes
id,created_at, andupdated_at. Browse adds onlyname, ortitlefor knowledge articles and documents. Read adds all fields listed for that scope, including any additional read fields. Write results include supplied attributes and any generated slug, rather than untouched fields. - Company IDs, workspace IDs, credentials, internal execution state, and arbitrary model attributes cannot be supplied or retrieved through this API.
Custom agents
Scope: custom_agents. All five operations are supported.
| Writable field | Type / constraint | Required on Add |
|---|---|---|
name |
string(255) | Yes |
description |
text, nullable | No |
conversation_tone |
string(255), nullable | No |
company_instructions |
text, nullable | No |
is_active, strict_mode |
boolean | No |
temperature |
number from 0 to 2 | No |
history_size, knowledge_size |
integer from 0 to 100 | No |
New custom agents use a configured active chat model. Add returns 422 if none is available. Model credentials and model selection are managed through the existing assistant configuration.
Knowledge articles
Scope: knowledge_articles. All five operations are supported.
| Writable field | Type / constraint | Required on Add |
|---|---|---|
title |
string(255) | Yes |
body |
text | Yes |
slug |
slug | No |
short_description |
string(2000), nullable | No |
category_id |
positive integer or null; same-company category | No |
featured, published |
boolean | No |
order |
integer from 0 to 100,000 | No |
meta_title |
string(255), nullable | No |
meta_description |
string(2000), nullable | No |
The key's owner becomes the author on Add. Setting published to true sets the publication time if it has not already been set. Publication time is not a field exposed by this API.
Knowledge categories
Scope: knowledge_categories. All five operations are supported.
| Writable field | Type / constraint | Required on Add |
|---|---|---|
name |
string(255) | Yes |
slug |
slug | No |
description |
string(2000), nullable | No |
parent_id |
positive integer or null; same-company category | No |
order |
integer from 0 to 100,000 | No |
A category cannot be its own parent or belong to a cycle of parents.
Knowledge documents
Scope: knowledge_documents. Browse, Read, Edit, and Delete are supported.
| Writable field | Type / constraint |
|---|---|
title |
string(255) |
Additional Read fields: filename, original_mimetype, status, file_size, and chunk_count. Uploading files and processing document content use the Knowledge Documents workflow.
Forms
Scope: forms. All five operations are supported.
| Writable field | Type / constraint | Required on Add |
|---|---|---|
name |
string(255) | Yes |
slug |
slug | No |
description |
text, nullable | No |
trigger |
string(2000) | Yes |
is_active, allow_multiple_entries, allow_entry_updates |
boolean | No |
fields |
array of up to 100 field objects | Yes |
Each field object accepts only the following properties:
| Property | Type / constraint | Required |
|---|---|---|
name |
Unique string, maximum 100 characters; starts with a letter and then uses letters, numbers, or underscores. | Yes |
label |
string(255) | Yes |
type |
TextInput, Textarea, Number, Email, Phone, Date, Select, or Checkbox |
Yes |
required |
boolean | No |
placeholder |
string(255) | No |
options |
array of up to 100 strings, each at most 255 characters | No |
Example REST Add payload:
{
"name": "Customer enquiry",
"trigger": "Collect the customer's enquiry details",
"fields": [
{"name":"email","label":"Email","type":"Email","required":true},
{"name":"topic","label":"Topic","type":"Select","options":["Sales","Support"]}
]
}
New forms start as drafts. For Edit, a supplied fields array replaces that attribute's value; it is not an instruction to append one field. Form generation, publishing, and advanced configuration use the AI Form Builder.
Contacts
Scope: contacts. All five operations are supported. These are the visitor/contact records in the company.
| Writable field | Type / constraint | Required on Add |
|---|---|---|
name |
string(255) | Yes |
email |
Valid email, maximum 255 characters, or null | No |
phone_number |
string(50), nullable | No |
Additional Read field: source. New contacts have the source api. Tags, audience memberships, and contact-group memberships are outside this scope's payload.
Contact groups
Scope: contact_groups. All five operations are supported.
| Writable field | Type / constraint | Required on Add |
|---|---|---|
name |
string(255) | Yes |
description |
string(2000), nullable | No |
These operations manage the group record. Use the existing Contact Groups interface to manage its members.
Chat widgets
Scope: chat_widgets. All five operations are supported.
| Writable field | Type / constraint | Required on Add |
|---|---|---|
name |
string(255) | Yes |
custom_agent_id |
positive integer or null; same-company custom agent | No |
header_text |
string(255), nullable | No |
welcome_message, offline_message |
string(2000), nullable | No |
is_active |
boolean | No |
theme_color |
Six-digit hexadecimal color, such as #2563eb |
No |
position |
bottom-right or bottom-left |
No |
Additional Read field: widget_key, the public widget identifier generated on Add. Use Read after Add to retrieve it if your key has the Read grant. Advanced website behavior and embedding are covered in Chat Widgets.
Bookings
Scope: bookings. Browse, Read, Edit, and Delete are supported.
| Writable field | Type / constraint |
|---|---|
name |
string(255) |
description |
text, nullable |
Additional Read fields: slug, status, and timezone. This scope manages booking configurations, rather than individual customer reservations. Scheduling, capacity, and availability settings use the Bookings editor.
Workflows
Scope: workflows. Browse, Read, Edit, and Delete are supported.
| Writable field | Type / constraint |
|---|---|
name |
string(255) |
description |
text, nullable |
Additional Read fields: is_active and channel. Workflow definitions, activation, and execution use the Workflows interface; this API does not expose an execution operation.
Agent tools
Scope: agent_tools. Browse, Read, Edit, and Delete are supported.
| Writable field | Type / constraint |
|---|---|
name |
string(255) |
description, response_instructions |
text, nullable |
Additional Read fields: custom_agent_id, type, and is_active. Tool connection credentials, configuration, and execution are managed through Agent Tools.