REST API reference
Requests, responses and scopes for the regular workspace /v1 API.
On this page
- First request
- GET /bots
- POST /bots
- GET /bots/{id}/settings
- PATCH /bots/{id}/instructions
- GET /kb
- DELETE /kb/{id}
- GET /custom-answers
- POST /custom-answers
- PATCH /custom-answers/{id}
- DELETE /custom-answers/{id}
- POST /kb/ingest
- POST /chat
- POST /public/chat
- GET /conversations
- GET /conversations/{sessionId}
- GET /leads
- GET /analytics
- GET /bookings
- GET /bookings/{id}
- PATCH /bookings/{id}
This reference describes the regular workspace API at https://api-uat.famysync.com/v1. Authenticate with a scoped workspace token. The separate Enterprise Vendor API has different credentials, authorization and capabilities.
Specification version: 1.1.0. Download this documentation release’s OpenAPI. Read the API deployment’s specification.
First request
curl "https://api-uat.famysync.com/v1/bots" \ -H "Authorization: Bearer $FAMYSYNC_API_TOKEN"
Use API tokens and scopes for setup and API errors and limits for recovery. Lists are bounded; do not send undocumented page or cursor parameters.
GET /bots
List bots. Requires scope `bots:read`.
Responses
200 Bot list. A token covers one workspace (`workspace`).
application/json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"maxLength": 30
},
"slot_kind": {
"type": "string",
"enum": [
"plan",
"addon",
"vendor"
]
},
"language": {
"type": "string",
"example": "ja-JP",
"description": "Default reply language (as in the dashboard)."
},
"is_active": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"workspace": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": [
"string",
"null"
]
}
}
}
}
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}POST /bots
Create a bot. Requires scope `bots:write`. `language` becomes the bot’s default reply language. Bot-restricted tokens cannot create bots. Enterprise workspaces must supply `enterprise_plan_tier` and have an available slot in that tier.
Request body
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 30
},
"language": {
"type": "string",
"example": "en-US"
},
"enterprise_plan_tier": {
"type": "string",
"enum": [
"starter",
"growth",
"scale"
],
"description": "Required for enterprise workspaces"
}
}
}Responses
201 Created bot
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"maxLength": 30
},
"slot_kind": {
"type": "string",
"enum": [
"plan",
"addon",
"vendor"
]
},
"language": {
"type": "string",
"example": "ja-JP",
"description": "Default reply language (as in the dashboard)."
},
"is_active": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}409 Bot name is already used; inspect suggested_name.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}GET /bots/{id}/settings
Get a bot’s instructions and language settings. Requires scope `bots:read`.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
id | path | Yes | {"type":"string","format":"uuid"} |
Responses
200 Settings
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"chatbotId": {
"type": "string",
"format": "uuid"
},
"language": {
"type": "string"
},
"languageMode": {
"type": "string",
"enum": [
"match",
"fixed"
]
},
"supportedLanguages": {
"type": "array",
"items": {
"type": "string"
}
},
"instructions": {
"type": "string",
"description": "The instructions the bot follows now (a preset’s text when a preset is chosen)."
},
"instructionPreset": {
"type": "string"
},
"persona": {
"type": "string"
},
"personaPreset": {
"type": "string"
},
"fallbackMessage": {
"type": "string"
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}PATCH /bots/{id}/instructions
Replace instructions, persona and/or fallback message. Requires scope `settings:write`. Pass only what changes; each field replaces the whole text and switches its preset to custom. The response has the new settings in `data` and the old ones in `previous`, to undo the change.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
id | path | Yes | {"type":"string","format":"uuid"} |
Request body
{
"type": "object",
"minProperties": 1,
"properties": {
"instructions": {
"type": "string",
"maxLength": 4000
},
"persona": {
"type": "string",
"maxLength": 2000
},
"fallbackMessage": {
"type": "string",
"maxLength": 500
}
}
}Responses
200 Updated
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"chatbotId": {
"type": "string",
"format": "uuid"
},
"language": {
"type": "string"
},
"languageMode": {
"type": "string",
"enum": [
"match",
"fixed"
]
},
"supportedLanguages": {
"type": "array",
"items": {
"type": "string"
}
},
"instructions": {
"type": "string",
"description": "The instructions the bot follows now (a preset’s text when a preset is chosen)."
},
"instructionPreset": {
"type": "string"
},
"persona": {
"type": "string"
},
"personaPreset": {
"type": "string"
},
"fallbackMessage": {
"type": "string"
}
}
},
"previous": {
"type": "object",
"properties": {
"chatbotId": {
"type": "string",
"format": "uuid"
},
"language": {
"type": "string"
},
"languageMode": {
"type": "string",
"enum": [
"match",
"fixed"
]
},
"supportedLanguages": {
"type": "array",
"items": {
"type": "string"
}
},
"instructions": {
"type": "string",
"description": "The instructions the bot follows now (a preset’s text when a preset is chosen)."
},
"instructionPreset": {
"type": "string"
},
"persona": {
"type": "string"
},
"personaPreset": {
"type": "string"
},
"fallbackMessage": {
"type": "string"
}
}
}
}
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}GET /kb
List knowledge-base documents. Requires scope `kb:read`. Newest first. Without `limit` every document is returned; with it, page with `offset` (`total` says how many match).
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
chatbotId | query | No | {"type":"string","format":"uuid"} |
limit | query | No | {"type":"integer","minimum":1,"maximum":200} |
offset | query | No | {"type":"integer","minimum":0,"default":0} |
status | query | No | {"type":"string","enum":["queued","processing","ready","failed"]} |
type | query | No | {"type":"string","enum":["url","file","qa","snippet"]} |
q | query | No | {"type":"string","maxLength":200} |
Responses
200 Document list
application/json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string"
},
"source_url": {
"type": [
"string",
"null"
]
},
"source_type": {
"type": "string",
"enum": [
"url",
"file",
"qa",
"snippet"
]
},
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"ready",
"failed"
]
},
"chunk_count": {
"type": "integer"
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"synced_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Last successful training."
},
"last_attempt_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Last time it was sent to training."
},
"error_code": {
"type": [
"string",
"null"
],
"example": "embed_too_large"
},
"error": {
"type": [
"string",
"null"
],
"description": "Why the last training failed."
}
}
}
},
"total": {
"type": "integer"
},
"limit": {
"type": [
"integer",
"null"
]
},
"offset": {
"type": "integer"
}
}
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}DELETE /kb/{id}
Delete a knowledge-base document. Requires scope `kb:write`. Any kind (page, file, snippet, custom answer). The bot stops using it straight away; cannot be undone.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
id | path | Yes | {"type":"string","format":"uuid"} |
Responses
200 Deleted
application/json
{
"type": "object",
"properties": {
"deleted": {
"type": "string",
"format": "uuid"
}
}
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}GET /custom-answers
List custom answers. Requires scope `kb:read`. Custom answers take priority over other knowledge.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
chatbotId | query | No | {"type":"string","format":"uuid"} |
Responses
200 Custom answers
application/json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"question": {
"type": "string"
},
"answer": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"ready",
"failed"
]
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"synced_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}POST /custom-answers
Add a custom answer. Requires scope `kb:write`. Used once trained (about 2 minutes).
Request body
{
"type": "object",
"required": [
"chatbotId",
"question",
"answer"
],
"properties": {
"chatbotId": {
"type": "string",
"format": "uuid"
},
"question": {
"type": "string",
"maxLength": 500
},
"answer": {
"type": "string",
"maxLength": 5000
}
}
}Responses
202 Queued for training
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"question": {
"type": "string"
},
"answer": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"ready",
"failed"
]
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"synced_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}PATCH /custom-answers/{id}
Change a custom answer. Requires scope `kb:write`. The old answer is used until the new one is trained. `previous` has the old text.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
id | path | Yes | {"type":"string","format":"uuid"} |
Request body
{
"type": "object",
"minProperties": 1,
"properties": {
"question": {
"type": "string",
"maxLength": 500
},
"answer": {
"type": "string",
"maxLength": 5000
}
}
}Responses
202 Queued for training
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"question": {
"type": "string"
},
"answer": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"ready",
"failed"
]
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"synced_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"previous": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"question": {
"type": "string"
},
"answer": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"ready",
"failed"
]
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"synced_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}DELETE /custom-answers/{id}
Delete a custom answer. Requires scope `kb:write`. Cannot be undone.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
id | path | Yes | {"type":"string","format":"uuid"} |
Responses
200 Deleted
application/json
{
"type": "object",
"properties": {
"deleted": {
"type": "string",
"format": "uuid"
}
}
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}POST /kb/ingest
Add knowledge (URL or raw text). Requires scope `kb:write`. Queued for crawling/embedding; poll GET /kb for status.
Request body
{
"type": "object",
"required": [
"title"
],
"anyOf": [
{
"required": [
"url"
]
},
{
"required": [
"text"
],
"properties": {
"text": {
"minLength": 1
}
}
}
],
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"url": {
"type": "string",
"format": "uri"
},
"text": {
"type": "string",
"maxLength": 200000
},
"chatbotId": {
"type": "string",
"format": "uuid"
}
}
}Responses
202 Queued
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
}
}
}
}
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}POST /chat
Chat with a bot. Requires scope `chat:invoke`. Every message is saved as a conversation (channel `api`) and counts toward your monthly message quota; without `sessionId` a new conversation is started and its id returned (`X-Session-Id` header and the `done` event). By default the reply is a Server-Sent Events stream: text pieces as OpenAI-style chunks (`data: {"choices":[{"delta":{"content":"…"}}]}`), then `event: done` with the sources, suggested questions and actions (ChatDone), then `data: [DONE]`. With `"stream": false` the whole reply comes back as one JSON object (ChatReply).
Request body
{
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"chatbotId": {
"type": "string",
"format": "uuid"
},
"sessionId": {
"type": "string",
"maxLength": 120,
"description": "Stable id groups turns into one conversation"
},
"language": {
"type": "string",
"example": "ja-JP",
"description": "Reply language. Any supported code, e.g. en-US, es-US, fr-FR, pt-BR, ht-HT, ru-RU, de-DE, it-IT, pl-PL, fa-IR, en-IN, ja-JP, ko-KR, zh-CN, ms-MY, id-ID, th-TH, vi-VN, fil-PH, ar-AE, hi-IN, ta-IN, sw-KE, ha-NG, yo-NG. Omit to use the bot’s default; the bot still matches the language the user writes in."
},
"stream": {
"type": "boolean",
"default": true,
"description": "false: one JSON reply instead of a stream."
}
}
}Responses
200 SSE stream, or JSON with "stream": false
text/event-stream
{
"type": "string",
"description": "Text chunks, then `event: done` (ChatDone JSON), then `data: [DONE]`."
}data: {"choices":[{"delta":{"content":"Hello"}}]}
event: done
data: {"sessionId":"api-…","sources":["https://example.com/faq"],"suggestions":["How do I book?"],"handoff":false,"askContact":false,"offerBooking":false}
data: [DONE]
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"description": "Pass it back to continue the conversation."
},
"answer": {
"type": "string",
"description": "The reply text, without suggestion line or hidden markers."
},
"sources": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Pages the reply is based on: links the reply gives first, then the knowledge pages closest to the question."
},
"suggestions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Suggested follow-up questions."
},
"handoff": {
"type": "boolean",
"description": "The bot offered human support."
},
"askContact": {
"type": "boolean",
"description": "The bot asked for contact details."
},
"offerBooking": {
"type": "boolean",
"description": "The bot offered a booking."
}
},
"required": [
"sessionId",
"answer",
"sources",
"suggestions",
"handoff",
"askContact",
"offerBooking"
]
}
}
}{
"headers": {
"X-Session-Id": {
"description": "The conversation id.",
"schema": {
"type": "string"
}
}
}
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}POST /public/chat
Chat from your own web page (public key). For a browser: send the bot’s public key (`X-Famysync-Key: mpk_…`, from Dashboard → API). It can only chat with that one bot, and only from the bot’s allowed domains, which must be switched on. Same request and reply as POST /chat (without `chatbotId`). Rate limited per key and per visitor. Never put a secret token (mgpt_…) in a web page; it is refused here.
Request body
{
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"sessionId": {
"type": "string",
"maxLength": 120
},
"language": {
"type": "string",
"example": "ja-JP"
},
"stream": {
"type": "boolean",
"default": true
}
}
}Responses
200 Same as POST /chat
text/event-stream
{
"type": "string"
}application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"description": "Pass it back to continue the conversation."
},
"answer": {
"type": "string",
"description": "The reply text, without suggestion line or hidden markers."
},
"sources": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Pages the reply is based on: links the reply gives first, then the knowledge pages closest to the question."
},
"suggestions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Suggested follow-up questions."
},
"handoff": {
"type": "boolean",
"description": "The bot offered human support."
},
"askContact": {
"type": "boolean",
"description": "The bot asked for contact details."
},
"offerBooking": {
"type": "boolean",
"description": "The bot offered a booking."
}
},
"required": [
"sessionId",
"answer",
"sources",
"suggestions",
"handoff",
"askContact",
"offerBooking"
]
}
}
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Allowed domains are off for this bot (`domains_required`) or the page is not on them (`origin_not_allowed`).
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}GET /conversations
List conversations. Requires scope `conversations:read`. Supports `?q=` search, `?limit=`, `?chatbotId=`, `?channel=` (web, api, mcp, email, whatsapp). Default limit 50, maximum 200; no page or cursor parameter.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
q | query | No | {"type":"string","maxLength":200} |
channel | query | No | {"type":"string","enum":["web","api","mcp","email","whatsapp"]} |
limit | query | No | {"type":"integer","minimum":1,"maximum":200,"default":50} |
chatbotId | query | No | {"type":"string","format":"uuid"} |
Responses
200 Session list
application/json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"session_id": {
"type": "string"
},
"message_count": {
"type": "integer"
},
"first_at": {
"type": "string",
"format": "date-time"
},
"last_at": {
"type": "string",
"format": "date-time"
},
"preview": {
"type": [
"string",
"null"
]
},
"channel": {
"type": "string"
}
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}GET /conversations/{sessionId}
Get a conversation transcript. Requires scope `conversations:read`. Returns an array; a missing session can return an empty array. Restricted tokens may receive 403 for inaccessible sessions.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
sessionId | path | Yes | {"type":"string"} |
Responses
200 Messages in the session
application/json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"session_id": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"user",
"assistant"
]
},
"content": {
"type": "string"
},
"feedback": {
"type": [
"string",
"null"
],
"enum": [
"positive",
"negative",
null
]
},
"source_urls": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"channel": {
"type": "string"
},
"provider_message_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}GET /leads
List leads. Requires scope `leads:read`. At most 500 intent-scored leads, newest first; no cursor pagination; optional `?chatbotId=`. Each lead has score/band, an AI summary, contact details, qualification, and `external_user_id` when the visitor was signed in (Famysync.identify).
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
chatbotId | query | No | {"type":"string","format":"uuid"} |
Responses
200 Lead list
application/json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"session_id": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"email": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
},
"external_user_id": {
"type": [
"string",
"null"
]
},
"company": {
"type": [
"string",
"null"
]
},
"intent_category": {
"type": [
"string",
"null"
]
},
"intent_summary": {
"type": [
"string",
"null"
]
},
"score": {
"type": "integer"
},
"score_band": {
"type": "string",
"enum": [
"hot",
"warm",
"cold"
]
},
"sentiment": {
"type": [
"string",
"null"
]
},
"qualification": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"new",
"contacted",
"qualified",
"won",
"lost"
]
},
"captured_via": {
"type": "string",
"enum": [
"conversational",
"form",
"inferred"
]
},
"confidence": {
"type": [
"number",
"null"
]
},
"notified_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"asked_contact_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"notes": {
"type": [
"string",
"null"
]
},
"country": {
"type": [
"string",
"null"
]
},
"region": {
"type": [
"string",
"null"
]
},
"channel": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}GET /analytics
Analytics summary (30 days). Requires scope `analytics:read`. Daily volumes, top questions, unanswered rate, feedback, sessions.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
chatbotId | query | No | {"type":"string","format":"uuid"} |
Responses
200 Analytics summary
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"daily": {
"type": "array",
"items": {
"type": "object",
"properties": {
"day": {
"type": "string",
"format": "date"
},
"user_messages": {
"type": "integer"
},
"assistant_messages": {
"type": "integer"
}
}
}
},
"top_questions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"question": {
"type": "string"
},
"times": {
"type": "integer"
}
}
}
},
"unanswered": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"total": {
"type": "integer"
},
"rate": {
"type": "number",
"description": "Percentage from 0 to 100, rounded to one decimal place."
}
}
},
"feedback": {
"type": "object",
"properties": {
"positive": {
"type": "integer"
},
"negative": {
"type": "integer"
}
}
},
"sessions": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"avg_messages": {
"type": "number"
}
}
}
},
"required": [
"daily",
"top_questions",
"unanswered",
"feedback",
"sessions"
]
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}GET /bookings
List bookings. Requires scope `bookings:read`. Appointment requests newest first. Filter with `?status=pending|confirmed|rejected|cancelled`, `?chatbotId=`, `?limit=`.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
status | query | No | {"type":"string","enum":["pending","confirmed","rejected","cancelled"]} |
chatbotId | query | No | {"type":"string","format":"uuid"} |
limit | query | No | {"type":"integer","minimum":1,"maximum":200,"default":200} |
Responses
200 Booking list
application/json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
},
"notes": {
"type": [
"string",
"null"
]
},
"requested_slot": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"country": {
"type": [
"string",
"null"
]
},
"time_zone": {
"type": [
"string",
"null"
]
},
"custom_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"pending",
"confirmed",
"rejected",
"cancelled"
]
},
"rejection_comment": {
"type": [
"string",
"null"
]
},
"cancel_comment": {
"type": [
"string",
"null"
],
"description": "Why the business cancelled (sent to the visitor)."
},
"confirmed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"rejected_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}GET /bookings/{id}
Get a booking. Requires scope `bookings:read`.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
id | path | Yes | {"type":"string","format":"uuid"} |
Responses
200 Booking
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
},
"notes": {
"type": [
"string",
"null"
]
},
"requested_slot": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"country": {
"type": [
"string",
"null"
]
},
"time_zone": {
"type": [
"string",
"null"
]
},
"custom_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"pending",
"confirmed",
"rejected",
"cancelled"
]
},
"rejection_comment": {
"type": [
"string",
"null"
]
},
"cancel_comment": {
"type": [
"string",
"null"
],
"description": "Why the business cancelled (sent to the visitor)."
},
"confirmed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"rejected_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}PATCH /bookings/{id}
Update a booking. Requires scope `bookings:write`. `action` is `confirm`, `reject`, `reschedule`, or `cancel`. Confirm/reject apply to pending requests. Reschedule and cancel apply to pending or confirmed bookings and email the visitor. Reschedule requires `requestedSlot`. Optional `cancelComment` (saved as `cancel_comment`) / `rejectionComment` (saved as `rejection_comment`) is included in the visitor email.
| Parameter | Location | Required | Type / constraints |
|---|---|---|---|
id | path | Yes | {"type":"string","format":"uuid"} |
Request body
{
"type": "object",
"required": [
"action"
],
"allOf": [
{
"if": {
"properties": {
"action": {
"const": "reschedule"
}
}
},
"then": {
"required": [
"requestedSlot"
]
}
}
],
"properties": {
"action": {
"type": "string",
"enum": [
"confirm",
"reject",
"reschedule",
"cancel"
]
},
"requestedSlot": {
"type": "string",
"format": "date-time"
},
"rejectionComment": {
"type": "string",
"maxLength": 500
},
"cancelComment": {
"type": "string",
"maxLength": 500
}
}
}Responses
200 Updated booking
application/json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"chatbot_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
},
"notes": {
"type": [
"string",
"null"
]
},
"requested_slot": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"country": {
"type": [
"string",
"null"
]
},
"time_zone": {
"type": [
"string",
"null"
]
},
"custom_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"pending",
"confirmed",
"rejected",
"cancelled"
]
},
"rejection_comment": {
"type": [
"string",
"null"
]
},
"cancel_comment": {
"type": [
"string",
"null"
],
"description": "Why the business cancelled (sent to the visitor)."
},
"confirmed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"rejected_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}400 Invalid input or operation requirements. Validation can return a structured error.
application/json
{
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"additionalProperties": true,
"description": "Structured validation error; inspect its issues."
}
}
}
]
}401 Missing, invalid, expired or revoked API token.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}402 API/live service unavailable (api_locked), plan capacity or quota exhausted.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}403 Required scope or bot access is missing, or enterprise tier capacity is unavailable.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}404 Record or account not found in the accessible context.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}409 Slot taken, already decided or booking no longer active.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}429 Rate limit exceeded. Wait before retrying.
application/json
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retry_after": {
"type": "integer"
},
"suggested_name": {
"type": "string"
},
"available_slots": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
}{
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}