"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
},
"404": {
"description": "Assistant not found, or outside your account scope"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/assistants/prompt-templates/by-industry": {
"get": {
"operationId": "assistants-templates-by-industry",
"summary": "Active prompt templates, optionally filtered by industry",
"tags": [
"Assistants"
],
"parameters": [
{
"name": "industry",
"in": "query",
"required": false,
"description": "Industry filter. Rules: string — empty returns all active templates",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 5,
"name": "General Receptionist",
"description": "A friendly front-desk assistant that greets callers, answers common questions, and books or transfers as needed.",
"custom_fields": [
{
"name": "emergency_phone",
"label": "Emergency contact number",
"type": "text",
"required": false,
"placeholder": "+1 (555) 555-0123",
"default_value": "",
"options": []
},
{
"name": "booking_link",
"label": "Online booking link",
"type": "text",
"required": false,
"placeholder": "https://acmedental.com/book",
"default_value": "",
"options": []
}
],
"is_default": true,
"assistant_roles": [
{
"id": 1,
"name": "Receptionist",
"slug": "receptionist"
}
]
},
{
"id": 9,
"name": "Dental Front Desk",
"description": "Industry-tuned for dental practices: appointment booking, insurance questions, and emergency triage.",
"custom_fields": [
{
"name": "insurance_providers",
"label": "Accepted insurance providers",
"type": "text",
"required": false,
"placeholder": "Delta Dental, Cigna, Aetna",
"default_value": "",
"options": []
}
],
"is_default": false,
"assistant_roles": [
{
"id": 1,
"name": "Receptionist",
"slug": "receptionist"
}
]
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
}
}
}
},
"/api/assistants/{assistantId}/update-log": {
"get": {
"operationId": "assistants-update-log",
"summary": "Configuration version history",
"tags": [
"Assistants"
],
"parameters": [
{
"name": "assistantId",
"in": "path",
"required": true,
"description": "The assistant's public id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Rules: integer, clamped 1–100",
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Rules: integer, min 0",
"schema": {
"type": "integer",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 118,
"update_id": "b6b6c1d2-2222-4bbb-9ccc-1a2b3c4d5e6f",
"assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"timestamp": "2026-07-28T14:05:41.000000Z",
"updated_by": "jordan@acmedental.com",
"change_summary": "Updated greeting and business hours",
"full_config_after": {
"id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"name": "Reception",
"firstMessage": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"voicemailMessage": "Please leave a message after the tone and we'll call you back.",
"endCallMessage": "Thank you for calling Acme Dental, have a great day!",
"endCallPhrases": [
"goodbye",
"that's all, thank you"
],
"maxDurationSeconds": 1800,
"backgroundSound": "office",
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
]
},
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"server": {
"url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents"
},
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
}
}
},
{
"id": 117,
"update_id": "a5a5b0c1-1111-4aaa-8bbb-0a1b2c3d4e5f",
"assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"timestamp": "2026-07-15T09:12:07.000000Z",
"updated_by": "jordan@acmedental.com",
"change_summary": "Switched personality to Sarah",
"full_config_after": {
"id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"name": "Reception",
"firstMessage": "Thank you for calling Acme Dental, this is Sarah.",
"voicemailMessage": "Please leave a message after the tone and we'll call you back.",
"endCallMessage": "Thank you for calling Acme Dental, have a great day!",
"endCallPhrases": [
"goodbye",
"that's all, thank you"
],
"maxDurationSeconds": 1800,
"backgroundSound": "office",
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
]
},
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"server": {
"url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents"
},
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
}
}
}
],
"meta": {
"limit": 20,
"offset": 0,
"returned": 2
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
},
"404": {
"description": "Assistant not found, or outside your account scope"
},
"502": {
"description": "History store unavailable"
}
}
}
},
"/api/assistants/{assistantId}/update-log/{entryId}/restore": {
"post": {
"operationId": "assistants-restore-from-log",
"summary": "Restore a configuration from the version history",
"tags": [
"Assistants"
],
"parameters": [
{
"name": "assistantId",
"in": "path",
"required": true,
"description": "The assistant's public id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "entryId",
"in": "path",
"required": true,
"description": "The entry to restore, from the update-log listing.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Assistant restored successfully",
"data": {
"id": 42,
"name": "Reception",
"user_id": 17,
"created_by": 5,
"reseller_id": "3",
"workspace_id": 9,
"template_id": 5,
"personality_id": 12,
"base_config_id": null,
"type": "production",
"phone_number": "+14155550142",
"phone_number_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
},
"widget_embed_config": null,
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
],
"functionCall": "auto"
},
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"first_message": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"first_message_raw": "Thank you for calling {{companyName}}, this is {{personalityName}}. How can I help you today?",
"first_message_interruptions_enabled": true,
"first_message_mode": "assistant-speaks-first",
"voicemail_detection": {
"enabled": true,
"beepDetection": true,
"silenceDuration": 10,
"greetingDuration": 15
},
"client_messages": [
"transcript",
"status-update"
],
"server_messages": [
"end-of-call-report",
"status-update"
],
"max_duration_seconds": 1800,
"background_sound": "office",
"background_denoising_enabled": true,
"model_output_in_messages_enabled": false,
"transport_configurations": [],
"observability_plan": null,
"credential_ids": [],
"credentials": [],
"hooks": [],
"voicemail_message": "Please leave a message after the tone and we'll call you back.",
"end_call_message": "Thank you for calling Acme Dental, have a great day!",
"end_call_message_raw": "Thank you for calling {{companyName}}, have a great day!",
"end_call_phrases": [
"goodbye",
"that's all, thank you"
],
"compliance_plan": {
"recordingEnabled": true,
"transcriptionEnabled": true,
"dataRetentionDays": 365
},
"background_speech_denoising_plan": {
"smartDenoising": true,
"fourierDenoising": false
},
"analysis_plan": null,
"artifact_plan": {
"recording": true,
"transcript": true,
"summary": true,
"analysis": false
},
"start_speaking_plan": {
"initialDelayMs": 400,
"backgroundSoundVolume": 0.2
},
"stop_speaking_plan": {
"initialDelayMs": 0,
"backgroundSoundVolume": 0.1
},
"monitor_plan": {
"listenEnabled": false,
"controlEnabled": false,
"websocketUrl": null
},
"keypad_input_plan": {
"enabled": false,
"maxDigits": 4,
"terminateOnHash": true
},
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z",
"vapi_assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"coreData": {
"id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"name": "Reception",
"firstMessage": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"voicemailMessage": "Please leave a message after the tone and we'll call you back.",
"endCallMessage": "Thank you for calling Acme Dental, have a great day!",
"endCallPhrases": [
"goodbye",
"that's all, thank you"
],
"maxDurationSeconds": 1800,
"backgroundSound": "office",
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
]
},
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"server": {
"url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents"
},
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
},
"404": {
"description": "Assistant not found, or outside your account scope"
},
"422": {
"description": "Entry cannot be restored — message carries the reason"
},
"502": {
"description": "History store unavailable"
}
}
}
},
"/api/v2/assistants": {
"get": {
"operationId": "assistants-v2-list-assistants",
"summary": "List assistants with their v2 build context",
"tags": [
"Assistants"
],
"parameters": [
{
"name": "type",
"in": "query",
"required": false,
"description": "Rules: in: demo, production",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Rules: integer",
"schema": {
"type": "integer",
"default": 9
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 42,
"name": "Reception",
"user_id": 17,
"created_by": 5,
"reseller_id": "3",
"workspace_id": 9,
"template_id": 5,
"personality_id": 12,
"base_config_id": 3,
"type": "production",
"phone_number": "+14155550142",
"phone_number_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
},
"widget_embed_config": null,
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
],
"functionCall": "auto"
},
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"first_message": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"first_message_raw": "Thank you for calling {{companyName}}, this is {{personalityName}}. How can I help you today?",
"first_message_interruptions_enabled": true,
"first_message_mode": "assistant-speaks-first",
"voicemail_detection": {
"enabled": true,
"beepDetection": true,
"silenceDuration": 10,
"greetingDuration": 15
},
"client_messages": [
"transcript",
"status-update"
],
"server_messages": [
"end-of-call-report",
"status-update"
],
"max_duration_seconds": 1800,
"background_sound": "office",
"background_denoising_enabled": true,
"model_output_in_messages_enabled": false,
"transport_configurations": [],
"observability_plan": null,
"credential_ids": [],
"credentials": [],
"hooks": [],
"voicemail_message": "Please leave a message after the tone and we'll call you back.",
"end_call_message": "Thank you for calling Acme Dental, have a great day!",
"end_call_message_raw": "Thank you for calling {{companyName}}, have a great day!",
"end_call_phrases": [
"goodbye",
"that's all, thank you"
],
"compliance_plan": {
"recordingEnabled": true,
"transcriptionEnabled": true,
"dataRetentionDays": 365
},
"background_speech_denoising_plan": {
"smartDenoising": true,
"fourierDenoising": false
},
"analysis_plan": null,
"artifact_plan": {
"recording": true,
"transcript": true,
"summary": true,
"analysis": false
},
"start_speaking_plan": {
"initialDelayMs": 400,
"backgroundSoundVolume": 0.2
},
"stop_speaking_plan": {
"initialDelayMs": 0,
"backgroundSoundVolume": 0.1
},
"monitor_plan": {
"listenEnabled": false,
"controlEnabled": false,
"websocketUrl": null
},
"keypad_input_plan": {
"enabled": false,
"maxDigits": 4,
"terminateOnHash": true
},
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z",
"vapi_assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"build_context": {
"base_config_id": 3,
"layer2_key": "friendly-professional"
},
"base_config_name": "Standard Receptionist Base"
}
],
"pagination": {
"current_page": 1,
"last_page": 1,
"per_page": 9,
"total": 1,
"from": 1,
"to": 1
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
}
}
},
"post": {
"operationId": "assistants-v2-create-assistant",
"summary": "Create an assistant from the layered configuration",
"tags": [
"Assistants"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"base_config_id": {
"type": "integer",
"nullable": true,
"description": "The layered base configuration; may be derived from a template instead. Rules: required_without_all:prompt_template_id,industry_template_id|nullable|integer|exists:assistant_base_configs,id"
},
"name": {
"type": "string",
"description": "Rules: required|string|max:40"
},
"type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:demo,production"
},
"layer2_key": {
"type": "string",
"nullable": true,
"description": "Layer-2 preset key. Rules: nullable|string|max:64"
},
"prompt_template_id": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|exists:prompt_templates,id"
},
"industry_template_id": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|exists:industry_templates,id"
},
"system_prompt": {
"type": "string",
"nullable": true,
"description": "Free-form system prompt override. Rules: nullable|string"
},
"first_message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string (firstMessage also accepted)"
},
"end_call_message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string (endCallMessage also accepted)"
},
"server_url": {
"type": "string",
"nullable": true,
"description": "Webhook for call events. Rules: nullable|string|url"
},
"personality_id": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|exists:personalities,id"
},
"metadata": {
"type": "object",
"nullable": true,
"description": "Rules: nullable|array"
},
"variable_values": {
"type": "object",
"nullable": true,
"description": "Template variable values. Rules: nullable|array"
}
},
"required": [
"name"
]
},
"example": {
"base_config_id": 3,
"name": "Reception",
"type": "production",
"layer2_key": "friendly-professional",
"prompt_template_id": 5,
"industry_template_id": 7,
"system_prompt": "You are Sarah, the AI voice receptionist for Acme Dental.",
"first_message": "Thank you for calling {{companyName}}, this is {{personalityName}}. How can I help you today?",
"end_call_message": "Thank you for calling {{companyName}}, have a great day!",
"server_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality_id": 12,
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental"
},
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
}
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Assistant created successfully",
"data": {
"id": 42,
"name": "Reception",
"user_id": 17,
"created_by": 5,
"reseller_id": "3",
"workspace_id": 9,
"template_id": 5,
"personality_id": 12,
"base_config_id": 3,
"type": "production",
"phone_number": "+14155550142",
"phone_number_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
},
"widget_embed_config": null,
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
],
"functionCall": "auto"
},
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"first_message": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"first_message_raw": "Thank you for calling {{companyName}}, this is {{personalityName}}. How can I help you today?",
"first_message_interruptions_enabled": true,
"first_message_mode": "assistant-speaks-first",
"voicemail_detection": {
"enabled": true,
"beepDetection": true,
"silenceDuration": 10,
"greetingDuration": 15
},
"client_messages": [
"transcript",
"status-update"
],
"server_messages": [
"end-of-call-report",
"status-update"
],
"max_duration_seconds": 1800,
"background_sound": "office",
"background_denoising_enabled": true,
"model_output_in_messages_enabled": false,
"transport_configurations": [],
"observability_plan": null,
"credential_ids": [],
"credentials": [],
"hooks": [],
"voicemail_message": "Please leave a message after the tone and we'll call you back.",
"end_call_message": "Thank you for calling Acme Dental, have a great day!",
"end_call_message_raw": "Thank you for calling {{companyName}}, have a great day!",
"end_call_phrases": [
"goodbye",
"that's all, thank you"
],
"compliance_plan": {
"recordingEnabled": true,
"transcriptionEnabled": true,
"dataRetentionDays": 365
},
"background_speech_denoising_plan": {
"smartDenoising": true,
"fourierDenoising": false
},
"analysis_plan": null,
"artifact_plan": {
"recording": true,
"transcript": true,
"summary": true,
"analysis": false
},
"start_speaking_plan": {
"initialDelayMs": 400,
"backgroundSoundVolume": 0.2
},
"stop_speaking_plan": {
"initialDelayMs": 0,
"backgroundSoundVolume": 0.1
},
"monitor_plan": {
"listenEnabled": false,
"controlEnabled": false,
"websocketUrl": null
},
"keypad_input_plan": {
"enabled": false,
"maxDigits": 4,
"terminateOnHash": true
},
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z",
"vapi_assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"coreData": {
"id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"name": "Reception",
"firstMessage": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"voicemailMessage": "Please leave a message after the tone and we'll call you back.",
"endCallMessage": "Thank you for calling Acme Dental, have a great day!",
"endCallPhrases": [
"goodbye",
"that's all, thank you"
],
"maxDurationSeconds": 1800,
"backgroundSound": "office",
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
]
},
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"server": {
"url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents"
},
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
}
},
"base_config_name": "Standard Receptionist Base"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Creation quota reached"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Live platform write failed"
}
}
}
},
"/api/v2/assistants/form-options": {
"get": {
"operationId": "assistants-v2-form-options",
"summary": "Everything the builder form needs (base configs, templates, presets, personalities)",
"tags": [
"Assistants"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"base_configs": [
{
"id": 3,
"name": "Standard Receptionist Base"
},
{
"id": 4,
"name": "Outbound Follow-up Base"
}
],
"industry_templates": [
{
"id": 7,
"name": "Dental Front Desk",
"base_config_id": 3,
"base_config_name": "Standard Receptionist Base",
"custom_fields": [
{
"name": "insurance_providers",
"label": "Accepted insurance providers",
"type": "text",
"required": false,
"placeholder": "Delta Dental, Cigna, Aetna",
"default_value": "",
"options": []
}
]
}
],
"layer2_presets": [
{
"id": 1,
"key": "friendly-professional",
"name": "Friendly & Professional"
},
{
"id": 2,
"key": "concise-efficient",
"name": "Concise & Efficient"
}
],
"personalities": [
{
"id": 12,
"name": "Sarah"
},
{
"id": 13,
"name": "Marcus"
}
]
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
}
}
}
},
"/api/v2/assistants/preview": {
"post": {
"operationId": "assistants-v2-preview",
"summary": "Validate the merged configuration without creating anything",
"tags": [
"Assistants"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"base_config_id": {
"type": "integer",
"nullable": true,
"description": "The layered base configuration; may be derived from a template instead. Rules: required_without_all:prompt_template_id,industry_template_id|nullable|integer|exists:assistant_base_configs,id"
},
"name": {
"type": "string",
"description": "Rules: required|string|max:40"
},
"type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:demo,production"
},
"layer2_key": {
"type": "string",
"nullable": true,
"description": "Layer-2 preset key. Rules: nullable|string|max:64"
},
"prompt_template_id": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|exists:prompt_templates,id"
},
"industry_template_id": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|exists:industry_templates,id"
},
"system_prompt": {
"type": "string",
"nullable": true,
"description": "Free-form system prompt override. Rules: nullable|string"
},
"first_message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string (firstMessage also accepted)"
},
"end_call_message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string (endCallMessage also accepted)"
},
"server_url": {
"type": "string",
"nullable": true,
"description": "Webhook for call events. Rules: nullable|string|url"
},
"personality_id": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|exists:personalities,id"
},
"metadata": {
"type": "object",
"nullable": true,
"description": "Rules: nullable|array"
},
"variable_values": {
"type": "object",
"nullable": true,
"description": "Template variable values. Rules: nullable|array"
}
},
"required": [
"name"
]
},
"example": {
"base_config_id": 3,
"name": "Reception",
"type": "production",
"layer2_key": "friendly-professional",
"prompt_template_id": 5,
"industry_template_id": 7,
"system_prompt": "You are Sarah, the AI voice receptionist for Acme Dental.",
"first_message": "Thank you for calling {{companyName}}, this is {{personalityName}}. How can I help you today?",
"end_call_message": "Thank you for calling {{companyName}}, have a great day!",
"server_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality_id": 12,
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental"
},
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Config is valid. You can create the assistant.",
"data": {
"config": {
"id": null,
"name": "Reception",
"firstMessage": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"voicemailMessage": "Please leave a message after the tone and we'll call you back.",
"endCallMessage": "Thank you for calling Acme Dental, have a great day!",
"endCallPhrases": [
"goodbye",
"that's all, thank you"
],
"maxDurationSeconds": 1800,
"backgroundSound": "office",
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
]
},
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"server": {
"url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents"
},
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
},
"422": {
"description": "No buildable base"
}
}
}
},
"/api/v2/assistants/{assistantId}": {
"get": {
"operationId": "assistants-v2-get-assistant",
"summary": "Retrieve one assistant with live configuration",
"tags": [
"Assistants"
],
"parameters": [
{
"name": "assistantId",
"in": "path",
"required": true,
"description": "The assistant's public id (UUID).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 42,
"name": "Reception",
"user_id": 17,
"created_by": 5,
"reseller_id": "3",
"workspace_id": 9,
"template_id": 5,
"personality_id": 12,
"base_config_id": 3,
"type": "production",
"phone_number": "+14155550142",
"phone_number_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
},
"widget_embed_config": null,
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
],
"functionCall": "auto"
},
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"first_message": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"first_message_raw": "Thank you for calling {{companyName}}, this is {{personalityName}}. How can I help you today?",
"first_message_interruptions_enabled": true,
"first_message_mode": "assistant-speaks-first",
"voicemail_detection": {
"enabled": true,
"beepDetection": true,
"silenceDuration": 10,
"greetingDuration": 15
},
"client_messages": [
"transcript",
"status-update"
],
"server_messages": [
"end-of-call-report",
"status-update"
],
"max_duration_seconds": 1800,
"background_sound": "office",
"background_denoising_enabled": true,
"model_output_in_messages_enabled": false,
"transport_configurations": [],
"observability_plan": null,
"credential_ids": [],
"credentials": [],
"hooks": [],
"voicemail_message": "Please leave a message after the tone and we'll call you back.",
"end_call_message": "Thank you for calling Acme Dental, have a great day!",
"end_call_message_raw": "Thank you for calling {{companyName}}, have a great day!",
"end_call_phrases": [
"goodbye",
"that's all, thank you"
],
"compliance_plan": {
"recordingEnabled": true,
"transcriptionEnabled": true,
"dataRetentionDays": 365
},
"background_speech_denoising_plan": {
"smartDenoising": true,
"fourierDenoising": false
},
"analysis_plan": null,
"artifact_plan": {
"recording": true,
"transcript": true,
"summary": true,
"analysis": false
},
"start_speaking_plan": {
"initialDelayMs": 400,
"backgroundSoundVolume": 0.2
},
"stop_speaking_plan": {
"initialDelayMs": 0,
"backgroundSoundVolume": 0.1
},
"monitor_plan": {
"listenEnabled": false,
"controlEnabled": false,
"websocketUrl": null
},
"keypad_input_plan": {
"enabled": false,
"maxDigits": 4,
"terminateOnHash": true
},
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z",
"vapi_assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"coreData": {
"id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"name": "Reception",
"firstMessage": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"voicemailMessage": "Please leave a message after the tone and we'll call you back.",
"endCallMessage": "Thank you for calling Acme Dental, have a great day!",
"endCallPhrases": [
"goodbye",
"that's all, thank you"
],
"maxDurationSeconds": 1800,
"backgroundSound": "office",
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
]
},
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"server": {
"url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents"
},
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
}
},
"build_context": {
"base_config_id": 3,
"layer2_key": "friendly-professional"
},
"base_config_name": "Standard Receptionist Base"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
},
"404": {
"description": "Assistant not found"
},
"502": {
"description": "Live platform read failed"
}
}
},
"put": {
"operationId": "assistants-v2-update-assistant",
"summary": "Update through the layered engine",
"tags": [
"Assistants"
],
"parameters": [
{
"name": "assistantId",
"in": "path",
"required": true,
"description": "The assistant's public id (UUID).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"base_config_id": {
"type": "integer",
"nullable": true,
"description": "The layered base configuration; may be derived from a template instead. Rules: required_without_all:prompt_template_id,industry_template_id|nullable|integer|exists:assistant_base_configs,id"
},
"name": {
"type": "string",
"description": "Rules: required|string|max:40"
},
"type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:demo,production"
},
"layer2_key": {
"type": "string",
"nullable": true,
"description": "Layer-2 preset key. Rules: nullable|string|max:64"
},
"prompt_template_id": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|exists:prompt_templates,id"
},
"industry_template_id": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|exists:industry_templates,id"
},
"system_prompt": {
"type": "string",
"nullable": true,
"description": "Free-form system prompt override. Rules: nullable|string"
},
"first_message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string (firstMessage also accepted)"
},
"end_call_message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string (endCallMessage also accepted)"
},
"server_url": {
"type": "string",
"nullable": true,
"description": "Webhook for call events. Rules: nullable|string|url"
},
"personality_id": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|exists:personalities,id"
},
"metadata": {
"type": "object",
"nullable": true,
"description": "Rules: nullable|array"
},
"variable_values": {
"type": "object",
"nullable": true,
"description": "Template variable values. Rules: nullable|array"
}
},
"required": [
"name"
]
},
"example": {
"base_config_id": 3,
"name": "Reception",
"type": "production",
"layer2_key": "concise-efficient",
"first_message": "Thank you for calling {{companyName}}, this is {{personalityName}}. How can I help you today?",
"end_call_message": "Thank you for calling {{companyName}}, have a great day!",
"server_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality_id": 12,
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental"
},
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Assistant updated successfully",
"data": {
"id": 42,
"name": "Reception",
"user_id": 17,
"created_by": 5,
"reseller_id": "3",
"workspace_id": 9,
"template_id": 5,
"personality_id": 12,
"base_config_id": 3,
"type": "production",
"phone_number": "+14155550142",
"phone_number_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
},
"widget_embed_config": null,
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
],
"functionCall": "auto"
},
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"first_message": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"first_message_raw": "Thank you for calling {{companyName}}, this is {{personalityName}}. How can I help you today?",
"first_message_interruptions_enabled": true,
"first_message_mode": "assistant-speaks-first",
"voicemail_detection": {
"enabled": true,
"beepDetection": true,
"silenceDuration": 10,
"greetingDuration": 15
},
"client_messages": [
"transcript",
"status-update"
],
"server_messages": [
"end-of-call-report",
"status-update"
],
"max_duration_seconds": 1800,
"background_sound": "office",
"background_denoising_enabled": true,
"model_output_in_messages_enabled": false,
"transport_configurations": [],
"observability_plan": null,
"credential_ids": [],
"credentials": [],
"hooks": [],
"voicemail_message": "Please leave a message after the tone and we'll call you back.",
"end_call_message": "Thank you for calling Acme Dental, have a great day!",
"end_call_message_raw": "Thank you for calling {{companyName}}, have a great day!",
"end_call_phrases": [
"goodbye",
"that's all, thank you"
],
"compliance_plan": {
"recordingEnabled": true,
"transcriptionEnabled": true,
"dataRetentionDays": 365
},
"background_speech_denoising_plan": {
"smartDenoising": true,
"fourierDenoising": false
},
"analysis_plan": null,
"artifact_plan": {
"recording": true,
"transcript": true,
"summary": true,
"analysis": false
},
"start_speaking_plan": {
"initialDelayMs": 400,
"backgroundSoundVolume": 0.2
},
"stop_speaking_plan": {
"initialDelayMs": 0,
"backgroundSoundVolume": 0.1
},
"monitor_plan": {
"listenEnabled": false,
"controlEnabled": false,
"websocketUrl": null
},
"keypad_input_plan": {
"enabled": false,
"maxDigits": 4,
"terminateOnHash": true
},
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z",
"vapi_assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"assistant_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"coreData": {
"id": "9f8e7d6c-5b4a-4c3d-8e2f-1a2b3c4d5e6f",
"name": "Reception",
"firstMessage": "Thank you for calling Acme Dental, this is Sarah. How can I help you today?",
"voicemailMessage": "Please leave a message after the tone and we'll call you back.",
"endCallMessage": "Thank you for calling Acme Dental, have a great day!",
"endCallPhrases": [
"goodbye",
"that's all, thank you"
],
"maxDurationSeconds": 1800,
"backgroundSound": "office",
"voice": {
"voiceId": "sarah-professional-01",
"speed": 1
},
"model": {
"messages": [
{
"role": "system",
"content": "You are Sarah, the AI voice receptionist for Acme Dental. Greet callers warmly, answer questions about services and hours, and offer to book an appointment or transfer to the front desk as needed."
}
],
"maxTokens": 300,
"toolIds": [
"c3d4e5f6-7a8b-49c0-8d1e-2f3a4b5c6d7e"
]
},
"transcriber": {
"language": "en",
"confidenceThreshold": 0.4,
"formatTurns": true
},
"server": {
"url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents"
},
"metadata": {
"company_name": "Acme Dental",
"industry": "Dental",
"location": "Austin, TX",
"services_products": "General and cosmetic dentistry, teeth whitening, emergency dental care",
"country": "United States",
"assistant_phone_number": "+14155550142",
"webhook_url": "https://automations.sulus.ai/webhook/lhg-live-demo-agents",
"personality": "Sarah",
"personality_id": 12,
"user_id": 17,
"user": "Jordan Lee",
"type": "production",
"available24_7": false,
"standard_hours": "Mon-Fri 9:00 AM - 5:00 PM",
"business_hours": {
"monday": "9:00 AM - 5:00 PM",
"tuesday": "9:00 AM - 5:00 PM",
"wednesday": "9:00 AM - 5:00 PM",
"thursday": "9:00 AM - 5:00 PM",
"friday": "9:00 AM - 5:00 PM",
"saturday": "Closed",
"sunday": "Closed"
},
"always_say": [
"We look forward to seeing you!"
],
"never_say": [
"I don't know, let me transfer you"
],
"pronunciation": [
{
"word": "Sulus",
"soundsLike": "SOO-luss"
}
],
"spam_handling": "end_call",
"variable_values": {
"companyName": "Acme Dental",
"industry": "Dental",
"personalityName": "Sarah"
},
"sms_notifications": [
"+14155550199"
],
"email_notifications": [
"owner@acmedental.com"
],
"created_at": "2026-01-15T10:22:03.000000Z",
"updated_at": "2026-07-28T14:05:41.000000Z"
}
},
"base_config_name": "Standard Receptionist Base"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
},
"404": {
"description": "Assistant not found"
},
"422": {
"description": "Not a v2 assistant"
},
"500": {
"description": "Live platform write failed"
}
}
},
"delete": {
"operationId": "assistants-v2-delete-assistant",
"summary": "Delete an assistant",
"tags": [
"Assistants"
],
"parameters": [
{
"name": "assistantId",
"in": "path",
"required": true,
"description": "The assistant's public id (UUID).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Assistant deleted"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature assistants not enabled for the account"
},
"404": {
"description": "Assistant not found"
}
}
}
},
"/api/squads": {
"get": {
"operationId": "squads-list-squads",
"summary": "List squads you can access",
"tags": [
"Squads"
],
"parameters": [
{
"name": "search",
"in": "query",
"required": false,
"description": "Rules: string (name contains-filter)",
"schema": {
"type": "string"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Rules: only draft or published are honoured",
"schema": {
"type": "string"
}
},
{
"name": "sort_by",
"in": "query",
"required": false,
"description": "Rules: in: name, created_at, updated_at (fallback created_at)",
"schema": {
"type": "string",
"default": "created_at"
}
},
{
"name": "sort_order",
"in": "query",
"required": false,
"description": "Rules: asc|desc",
"schema": {
"type": "string",
"default": "desc"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Rules: integer",
"schema": {
"type": "integer",
"default": 15
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"name": "Front desk",
"external_squad_id": "e5f6a7b8-1c2d-4e3f-9a8b-7c6d5e4f3a2b",
"status": "published",
"user_id": 42,
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": 7,
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"firstMessage": "Thanks for calling, how can I help?"
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Booking",
"message": "One moment, transferring you.",
"description": "Caller wants to book an appointment",
"transferMode": "rolling-history"
}
],
"position": {
"x": 120.5,
"y": 240
}
},
{
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e",
"assistantOverrides": {
"name": "Booking"
},
"position": {
"x": 420,
"y": 240
}
}
],
"members_overrides": {
"voicemailMessage": "Please leave a message after the tone."
},
"variable_values": {
"business_name": "Acme Dental"
},
"metadata": {
"template_id": 5,
"personality_id": 16
},
"created_at": "2026-06-01T14:22:03+00:00",
"updated_at": "2026-07-15T09:10:44+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"memberCount": 2,
"entryAssistantName": "Reception",
"updatedAt": "2026-07-15T09:10:44+00:00",
"createdAt": "2026-06-01T14:22:03+00:00",
"coreData": null
}
],
"pagination": {
"current_page": 1,
"last_page": 1,
"per_page": 15,
"total": 1,
"from": 1,
"to": 1
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature squads not enabled for the account"
}
}
},
"post": {
"operationId": "squads-create-squad",
"summary": "Create and publish a squad (writes to the live platform first)",
"tags": [
"Squads"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Squad display name. Rules: required|string|max:100"
},
"user_id": {
"type": "integer",
"nullable": true,
"description": "Owner assignment — honoured only for admin roles. Rules: nullable|integer|exists:users,id"
},
"members": {
"type": "array",
"items": [],
"description": "The squad's assistants. The first member answers the call. Rules: required|array|min:1"
},
"members.*.assistantId": {
"type": "string",
"description": "The member assistant's public id (UUID). Rules: required|string"
},
"members.*.assistantOverrides": {
"type": "object",
"nullable": true,
"description": "Per-member overrides applied while this member is live (see Fields page). Rules: nullable|array"
},
"members.*.assistantDestinations": {
"type": "array",
"items": [],
"nullable": true,
"description": "Handoff targets this member can transfer the call to. Rules: nullable|array"
},
"members.*.assistantDestinations.*.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:assistant"
},
"members.*.assistantDestinations.*.assistantName": {
"type": "string",
"description": "Name of the destination member. Rules: required|string|max:255"
},
"members.*.assistantDestinations.*.message": {
"type": "string",
"nullable": true,
"description": "What is said while transferring. Rules: nullable|string|max:1000"
},
"members.*.assistantDestinations.*.description": {
"type": "string",
"nullable": true,
"description": "When the transfer should happen. Rules: nullable|string|max:2000"
},
"members.*.assistantDestinations.*.transferMode": {
"type": "string",
"nullable": true,
"description": "How conversation history carries into the destination. Rules: nullable|string|in:rolling-history,swap-system-message-in-history,swap-system-message-in-history-and-remove-transfer-tool-messages,delete-history"
},
"members.*.assistantDestinations.*.assistantId": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string"
},
"members.*.position": {
"type": "object",
"nullable": true,
"description": "Canvas position in the visual builder (UI-only). Rules: nullable|array (x/y: nullable|numeric)"
},
"membersOverrides": {
"type": "object",
"nullable": true,
"description": "Squad-wide overrides applied to every member. Rules: nullable|array"
},
"variableValues": {
"type": "object",
"nullable": true,
"description": "Template variable values shared by the squad. Rules: nullable|array"
},
"metadata": {
"type": "object",
"nullable": true,
"description": "Stored locally only — never forwarded to the live platform. Rules: nullable|array"
}
},
"required": [
"name",
"members",
"members.*.assistantId",
"members.*.assistantDestinations.*.assistantName"
]
},
"example": {
"name": "Front desk",
"user_id": null,
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"description": "Front-desk greeter",
"firstMessage": "Thanks for calling, how can I help?",
"firstMessageMode": "assistant-speaks-first",
"voicemailMessage": "Please leave a message after the tone.",
"endCallMessage": "Thanks for calling, goodbye!",
"model": {
"provider": "default",
"model": "standard",
"temperature": 0.7
},
"voice": {
"provider": "default",
"voiceId": "voice-standard-1"
},
"transcriber": {
"provider": "default",
"model": "standard",
"language": "en"
},
"variableValues": {
"business_name": "Acme Dental"
},
"metadata": {
"note": "front desk member"
}
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Booking",
"message": "One moment, transferring you.",
"description": "Caller wants to book an appointment",
"transferMode": "rolling-history",
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e"
}
],
"position": {
"x": 120.5,
"y": 240
}
},
{
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e",
"assistantOverrides": {
"name": "Booking"
},
"position": {
"x": 420,
"y": 240
}
}
],
"membersOverrides": {
"voicemailMessage": "Please leave a message after the tone.",
"variableValues": {
"business_name": "Acme Dental"
}
},
"variableValues": {
"business_name": "Acme Dental",
"business_hours": "Mon-Fri 9am-5pm"
},
"metadata": {
"template_id": 5,
"personality_id": 16,
"tags": [
"dental",
"front-desk"
]
}
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Front desk",
"external_squad_id": "e5f6a7b8-1c2d-4e3f-9a8b-7c6d5e4f3a2b",
"status": "published",
"user_id": 42,
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": 7,
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"firstMessage": "Thanks for calling, how can I help?"
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Booking",
"message": "One moment, transferring you.",
"description": "Caller wants to book an appointment",
"transferMode": "rolling-history",
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e"
}
],
"position": {
"x": 120.5,
"y": 240
}
},
{
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e",
"assistantOverrides": {
"name": "Booking"
},
"position": {
"x": 420,
"y": 240
}
}
],
"members_overrides": {
"voicemailMessage": "Please leave a message after the tone.",
"variableValues": {
"business_name": "Acme Dental"
}
},
"variable_values": {
"business_name": "Acme Dental",
"business_hours": "Mon-Fri 9am-5pm"
},
"metadata": {
"template_id": 5,
"personality_id": 16,
"tags": [
"dental",
"front-desk"
]
},
"created_at": "2026-07-30T14:22:03+00:00",
"updated_at": "2026-07-30T14:22:03+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"memberCount": 2,
"entryAssistantName": "Reception",
"updatedAt": "2026-07-30T14:22:03+00:00",
"createdAt": "2026-07-30T14:22:03+00:00",
"coreData": {
"id": "e5f6a7b8-1c2d-4e3f-9a8b-7c6d5e4f3a2b"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Assigning another owner without admin rights"
},
"422": {
"description": "Target owner unknown"
},
"500": {
"description": "Live write succeeded but local mirror failed — response carries upstream_id for support"
},
"502": {
"description": "Live platform write failed"
}
}
}
},
"/api/squads/draft": {
"post": {
"operationId": "squads-create-squad-draft",
"summary": "Save a local draft (never touches live routing)",
"tags": [
"Squads"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true,
"description": "Rules: lenient — empty auto-generates \"New Draft Squad N\""
},
"members": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: lenient — any composition is accepted while drafting"
},
"membersOverrides": {
"type": "object",
"nullable": true,
"description": "Rules: lenient"
},
"variableValues": {
"type": "object",
"nullable": true,
"description": "Rules: lenient"
},
"metadata": {
"type": "object",
"nullable": true,
"description": "Rules: lenient"
}
}
},
"example": {
"name": "",
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"firstMessage": "Thanks for calling, how can I help?"
},
"assistantDestinations": [],
"position": {
"x": 120.5,
"y": 240
}
}
],
"membersOverrides": {
"voicemailMessage": "Please leave a message after the tone."
},
"variableValues": {
"business_name": "Acme Dental"
},
"metadata": {
"template_id": 5,
"personality_id": 16
}
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "New Draft Squad 1",
"external_squad_id": "draft_Ab12Cd34Ef56",
"status": "draft",
"user_id": 42,
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": 7,
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"firstMessage": "Thanks for calling, how can I help?"
},
"assistantDestinations": [],
"position": {
"x": 120.5,
"y": 240
}
}
],
"members_overrides": {
"voicemailMessage": "Please leave a message after the tone."
},
"variable_values": {
"business_name": "Acme Dental"
},
"metadata": {
"template_id": 5,
"personality_id": 16
},
"created_at": "2026-07-30T14:22:03+00:00",
"updated_at": "2026-07-30T14:22:03+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"memberCount": 1,
"entryAssistantName": "Reception",
"updatedAt": "2026-07-30T14:22:03+00:00",
"createdAt": "2026-07-30T14:22:03+00:00",
"coreData": null
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature squads not enabled for the account"
}
}
}
},
"/api/squads/{id}/draft": {
"put": {
"operationId": "squads-update-squad-draft",
"summary": "Update a draft — or demote a published squad to draft locally",
"tags": [
"Squads"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The squad's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Front desk",
"external_squad_id": "draft_Ab12Cd34Ef56",
"status": "draft",
"user_id": 42,
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": 7,
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"firstMessage": "Thanks for calling, how can I help?"
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Booking",
"message": "One moment, transferring you.",
"description": "Caller wants to book an appointment",
"transferMode": "rolling-history"
}
],
"position": {
"x": 120.5,
"y": 240
}
},
{
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e",
"assistantOverrides": {
"name": "Booking"
},
"position": {
"x": 420,
"y": 240
}
}
],
"members_overrides": {
"voicemailMessage": "Please leave a message after the tone."
},
"variable_values": {
"business_name": "Acme Dental"
},
"metadata": {
"template_id": 5,
"personality_id": 16
},
"created_at": "2026-06-01T14:22:03+00:00",
"updated_at": "2026-07-30T14:25:11+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"memberCount": 2,
"entryAssistantName": "Reception",
"updatedAt": "2026-07-30T14:25:11+00:00",
"createdAt": "2026-06-01T14:22:03+00:00",
"coreData": null
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Workspace permission denied"
},
"404": {
"description": "Squad not found, or outside your account scope"
}
}
}
},
"/api/squads/{id}": {
"get": {
"operationId": "squads-get-squad",
"summary": "Retrieve one squad (local state — deliberately no live read)",
"tags": [
"Squads"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The squad's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Front desk",
"external_squad_id": "e5f6a7b8-1c2d-4e3f-9a8b-7c6d5e4f3a2b",
"status": "published",
"user_id": 42,
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": 7,
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"firstMessage": "Thanks for calling, how can I help?"
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Booking",
"message": "One moment, transferring you.",
"description": "Caller wants to book an appointment",
"transferMode": "rolling-history"
}
],
"position": {
"x": 120.5,
"y": 240
}
},
{
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e",
"assistantOverrides": {
"name": "Booking"
},
"position": {
"x": 420,
"y": 240
}
}
],
"members_overrides": {
"voicemailMessage": "Please leave a message after the tone."
},
"variable_values": {
"business_name": "Acme Dental"
},
"metadata": {
"template_id": 5,
"personality_id": 16
},
"created_at": "2026-06-01T14:22:03+00:00",
"updated_at": "2026-07-15T09:10:44+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"memberCount": 2,
"entryAssistantName": "Reception",
"updatedAt": "2026-07-15T09:10:44+00:00",
"createdAt": "2026-06-01T14:22:03+00:00",
"coreData": null
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature squads not enabled for the account"
},
"404": {
"description": "Squad not found, or outside your account scope"
}
}
},
"put": {
"operationId": "squads-update-squad",
"summary": "Publish changes — creates or patches the live squad, sets status published",
"tags": [
"Squads"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The squad's public id.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Squad display name. Rules: required|string|max:100"
},
"user_id": {
"type": "integer",
"nullable": true,
"description": "Owner assignment — honoured only for admin roles. Rules: nullable|integer|exists:users,id"
},
"members": {
"type": "array",
"items": [],
"description": "The squad's assistants. The first member answers the call. Rules: required|array|min:1"
},
"members.*.assistantId": {
"type": "string",
"description": "The member assistant's public id (UUID). Rules: required|string"
},
"members.*.assistantOverrides": {
"type": "object",
"nullable": true,
"description": "Per-member overrides applied while this member is live (see Fields page). Rules: nullable|array"
},
"members.*.assistantDestinations": {
"type": "array",
"items": [],
"nullable": true,
"description": "Handoff targets this member can transfer the call to. Rules: nullable|array"
},
"members.*.assistantDestinations.*.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:assistant"
},
"members.*.assistantDestinations.*.assistantName": {
"type": "string",
"description": "Name of the destination member. Rules: required|string|max:255"
},
"members.*.assistantDestinations.*.message": {
"type": "string",
"nullable": true,
"description": "What is said while transferring. Rules: nullable|string|max:1000"
},
"members.*.assistantDestinations.*.description": {
"type": "string",
"nullable": true,
"description": "When the transfer should happen. Rules: nullable|string|max:2000"
},
"members.*.assistantDestinations.*.transferMode": {
"type": "string",
"nullable": true,
"description": "How conversation history carries into the destination. Rules: nullable|string|in:rolling-history,swap-system-message-in-history,swap-system-message-in-history-and-remove-transfer-tool-messages,delete-history"
},
"members.*.assistantDestinations.*.assistantId": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string"
},
"members.*.position": {
"type": "object",
"nullable": true,
"description": "Canvas position in the visual builder (UI-only). Rules: nullable|array (x/y: nullable|numeric)"
},
"membersOverrides": {
"type": "object",
"nullable": true,
"description": "Squad-wide overrides applied to every member. Rules: nullable|array"
},
"variableValues": {
"type": "object",
"nullable": true,
"description": "Template variable values shared by the squad. Rules: nullable|array"
},
"metadata": {
"type": "object",
"nullable": true,
"description": "Stored locally only — never forwarded to the live platform. Rules: nullable|array"
}
},
"required": [
"name",
"members",
"members.*.assistantId",
"members.*.assistantDestinations.*.assistantName"
]
},
"example": {
"name": "Front desk",
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"description": "Front-desk greeter",
"firstMessage": "Thanks for calling, how can I help?",
"firstMessageMode": "assistant-speaks-first",
"voicemailMessage": "Please leave a message after the tone.",
"endCallMessage": "Thanks for calling, goodbye!",
"model": {
"provider": "default",
"model": "standard",
"temperature": 0.7
},
"voice": {
"provider": "default",
"voiceId": "voice-standard-1"
},
"transcriber": {
"provider": "default",
"model": "standard",
"language": "en"
},
"variableValues": {
"business_name": "Acme Dental"
},
"metadata": {
"note": "front desk member"
}
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Booking",
"message": "One moment, transferring you.",
"description": "Caller wants to book an appointment",
"transferMode": "rolling-history",
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e"
}
],
"position": {
"x": 120.5,
"y": 240
}
},
{
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e",
"assistantOverrides": {
"name": "Booking"
},
"position": {
"x": 420,
"y": 240
}
}
],
"membersOverrides": {
"voicemailMessage": "Please leave a message after the tone.",
"variableValues": {
"business_name": "Acme Dental"
}
},
"variableValues": {
"business_name": "Acme Dental",
"business_hours": "Mon-Fri 9am-5pm"
},
"metadata": {
"template_id": 5,
"personality_id": 16,
"tags": [
"dental",
"front-desk"
]
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Front desk",
"external_squad_id": "e5f6a7b8-1c2d-4e3f-9a8b-7c6d5e4f3a2b",
"status": "published",
"user_id": 42,
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": 7,
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"firstMessage": "Thanks for calling, how can I help?"
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Booking",
"message": "One moment, transferring you.",
"description": "Caller wants to book an appointment",
"transferMode": "rolling-history",
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e"
}
],
"position": {
"x": 120.5,
"y": 240
}
},
{
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e",
"assistantOverrides": {
"name": "Booking"
},
"position": {
"x": 420,
"y": 240
}
}
],
"members_overrides": {
"voicemailMessage": "Please leave a message after the tone.",
"variableValues": {
"business_name": "Acme Dental"
}
},
"variable_values": {
"business_name": "Acme Dental",
"business_hours": "Mon-Fri 9am-5pm"
},
"metadata": {
"template_id": 5,
"personality_id": 16,
"tags": [
"dental",
"front-desk"
]
},
"created_at": "2026-06-01T14:22:03+00:00",
"updated_at": "2026-07-30T14:30:52+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"memberCount": 2,
"entryAssistantName": "Reception",
"updatedAt": "2026-07-30T14:30:52+00:00",
"createdAt": "2026-06-01T14:22:03+00:00",
"coreData": {
"id": "e5f6a7b8-1c2d-4e3f-9a8b-7c6d5e4f3a2b"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Workspace permission denied"
},
"404": {
"description": "Squad not found, or outside your account scope"
},
"422": {
"description": "Composition invalid for the live platform"
},
"502": {
"description": "Live platform write failed"
}
}
},
"delete": {
"operationId": "squads-delete-squad",
"summary": "Delete a squad (live first for published; drafts are local-only)",
"tags": [
"Squads"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The squad's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Workspace permission denied"
},
"404": {
"description": "Squad not found, or outside your account scope"
}
}
}
},
"/api/squads/{id}/duplicate": {
"post": {
"operationId": "squads-duplicate-squad",
"summary": "Duplicate as a local draft copy",
"tags": [
"Squads"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The squad's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Front desk (Copy)",
"external_squad_id": "draft_Gh78Ij90Kl12",
"status": "draft",
"user_id": 42,
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": 7,
"members": [
{
"assistantId": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"assistantOverrides": {
"name": "Reception",
"firstMessage": "Thanks for calling, how can I help?"
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Booking",
"message": "One moment, transferring you.",
"description": "Caller wants to book an appointment",
"transferMode": "rolling-history"
}
],
"position": {
"x": 120.5,
"y": 240
}
},
{
"assistantId": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e",
"assistantOverrides": {
"name": "Booking"
},
"position": {
"x": 420,
"y": 240
}
}
],
"members_overrides": {
"voicemailMessage": "Please leave a message after the tone."
},
"variable_values": {
"business_name": "Acme Dental"
},
"metadata": {
"template_id": 5,
"personality_id": 16
},
"created_at": "2026-07-30T14:35:19+00:00",
"updated_at": "2026-07-30T14:35:19+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"memberCount": 2,
"entryAssistantName": "Reception",
"updatedAt": "2026-07-30T14:35:19+00:00",
"createdAt": "2026-07-30T14:35:19+00:00",
"coreData": null
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Workspace permission denied"
},
"404": {
"description": "Squad not found, or outside your account scope"
},
"500": {
"description": "Copy failed"
}
}
}
},
"/api/tools": {
"get": {
"operationId": "tools-list-tools",
"summary": "List tools you can access",
"tags": [
"Tools"
],
"parameters": [
{
"name": "search",
"in": "query",
"required": false,
"description": "Rules: string (name contains-filter)",
"schema": {
"type": "string"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Rules: only draft or published are honoured",
"schema": {
"type": "string"
}
},
{
"name": "type",
"in": "query",
"required": false,
"description": "Rules: in: apiRequest, function, transferCall, endCall, dtmf, voicemail, handoff, query, mcp",
"schema": {
"type": "string"
}
},
{
"name": "scope",
"in": "query",
"required": false,
"description": "Rules: global (user_id is null) or account (user_id is not null)",
"schema": {
"type": "string"
}
},
{
"name": "sort_by",
"in": "query",
"required": false,
"description": "Rules: in: name, created_at, updated_at (fallback created_at)",
"schema": {
"type": "string",
"default": "created_at"
}
},
{
"name": "sort_order",
"in": "query",
"required": false,
"description": "Rules: asc|desc",
"schema": {
"type": "string",
"default": "desc"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Rules: integer",
"schema": {
"type": "integer",
"default": 15
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"name": "Check Order Status",
"user_id": 42,
"external_tool_id": "d4e5f6a7-8b9c-4a1d-9e2f-3a4b5c6d7e8f",
"status": "published",
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"type": "apiRequest",
"description": "Looks up an order by ID and returns its current status.",
"function_def": {
"name": "check_order_status"
},
"server": {
"url": "https://api.example-business.com/orders/lookup",
"method": "POST",
"timeoutSeconds": 20,
"credentialId": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b"
},
"variable_extraction_plan": {
"properties": [
{
"name": "orderStatus",
"type": "string",
"description": "Current status of the order",
"required": false
}
]
},
"destinations": null,
"rejection_plan": null,
"messages": [
{
"type": "request-start",
"content": "Let me check on that order for you."
}
],
"metadata": {
"category": "orders"
},
"async": false,
"created_at": "2026-06-01T14:22:03+00:00",
"updated_at": "2026-07-15T09:10:44+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"read_only": false,
"coreData": null
}
],
"pagination": {
"current_page": 1,
"last_page": 1,
"per_page": 15,
"total": 1,
"from": 1,
"to": 1
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature tools not enabled for the account"
}
}
},
"post": {
"operationId": "tools-create-tool",
"summary": "Create and publish a tool (writes to the live platform first)",
"tags": [
"Tools"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Tool display name. Rules: required|string|max:100"
},
"type": {
"type": "string",
"description": "Tool-type discriminator. Fixed at creation — cannot be changed on update. Rules: required|string|in:apiRequest,function,transferCall,endCall,dtmf,voicemail,handoff,query,mcp"
},
"user_id": {
"type": "integer",
"nullable": true,
"description": "Owner assignment — honoured only for admin roles. Rules: nullable|integer|exists:users,id"
},
"reseller_id": {
"type": "string",
"nullable": true,
"description": "Reseller assignment — honoured only for super admins. Rules: nullable|uuid|exists:resellers,id"
},
"isGlobal": {
"type": "boolean",
"nullable": true,
"description": "Marks the tool a platform Global Tool (no owner). Super-admin only; clears user_id. Rules: nullable|boolean"
},
"functionName": {
"type": "string",
"nullable": true,
"description": "The callable name the model uses to invoke the tool. Falls back to a slug of name when omitted. Rules: nullable|string|max:64|regex:/^[a-zA-Z0-9_-]+$/"
},
"description": {
"type": "string",
"nullable": true,
"description": "Top-level tool description (apiRequest). Function tools keep their description inside function_def. Rules: nullable|string|max:2000"
},
"parameters": {
"type": "array",
"items": [],
"nullable": true,
"description": "Function/handoff parameter schema-builder rows: {name, type, description, required, enum}. Rules: nullable|array"
},
"parametersLockSchema": {
"type": "boolean",
"nullable": true,
"description": "Locks the parameters schema (additionalProperties:false). Rules: nullable|boolean"
},
"strict": {
"type": "boolean",
"nullable": true,
"description": "Enforce exact schema adherence on the tool call (function tools). Rules: nullable|boolean"
},
"server": {
"type": "object",
"nullable": true,
"description": "Request configuration (apiRequest) / webhook target (function). See Fields page. Rules: nullable|array"
},
"server.url": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|url|max:2000"
},
"server.method": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:GET,POST,PUT,PATCH,DELETE"
},
"server.timeoutSeconds": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:300"
},
"server.headers": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rows of {key, value}. Rules: nullable|array"
},
"server.bodyProperties": {
"type": "array",
"items": [],
"nullable": true,
"description": "Recursive request-body schema tree — validated as a whole array (see Fields page). Rules: nullable|array"
},
"server.staticFields": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rows of {key, type, value} merged into the request body as typed literals. Rules: nullable|array"
},
"server.lockSchema": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"server.encryptedFields": {
"type": "array",
"items": [],
"nullable": true,
"description": "Header/body field names whose values are stored encrypted. Rules: nullable|array"
},
"server.encryptedFields.*": {
"type": "string",
"description": "Rules: string|max:200"
},
"server.backoffPlan": {
"type": "object",
"nullable": true,
"description": "Retry policy for failed requests. Rules: nullable|array"
},
"server.backoffPlan.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:fixed,exponential"
},
"server.backoffPlan.maxRetries": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:0|max:10"
},
"server.backoffPlan.baseDelaySeconds": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:0|max:300"
},
"server.backoffPlan.excludedStatusCodes": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: nullable|array"
},
"server.backoffPlan.excludedStatusCodes.*": {
"type": "integer",
"description": "Rules: integer|min:100|max:599"
},
"server.credentialId": {
"type": "string",
"nullable": true,
"description": "A personal credential's id (see Credentials group) used to authenticate the outbound request. Rules: nullable|string|max:100"
},
"server.staticIpAddressesEnabled": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"server.serverEncryptedPaths": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: nullable|array"
},
"server.serverEncryptedPaths.*": {
"type": "string",
"description": "Rules: string|max:200"
},
"server.sipInfoDtmfEnabled": {
"type": "boolean",
"nullable": true,
"description": "dtmf tools only. Rules: nullable|boolean"
},
"server.beepDetectionEnabled": {
"type": "boolean",
"nullable": true,
"description": "voicemail tools only — wait for the answering-machine beep. Rules: nullable|boolean"
},
"server.protocol": {
"type": "string",
"nullable": true,
"description": "mcp tools only — transport: shttp (Streamable HTTP, default) or sse (legacy). Sent to the voice platform as metadata.protocol. Rules: nullable|string|in:shttp,sse"
},
"variableExtractionPlan": {
"type": "object",
"nullable": true,
"description": "Extracts variables from the API response (apiRequest). See Fields page. Rules: nullable|array"
},
"variableExtractionPlan.properties": {
"type": "array",
"items": [],
"nullable": true,
"description": "Schema rows: {name, type, description, required, enum}. Rules: nullable|array"
},
"variableExtractionPlan.aliases": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rows of {key, value}. Rules: nullable|array"
},
"destinations": {
"type": "array",
"items": [],
"nullable": true,
"description": "Transfer/handoff targets (transferCall, handoff). See Fields page. Rules: nullable|array"
},
"destinations.*.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:number,sip,assistant,dynamic,squad"
},
"destinations.*.server": {
"type": "object",
"nullable": true,
"description": "Handoff dynamic-destination server config. Rules: nullable|array"
},
"destinations.*.server.url": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|url|max:2000"
},
"destinations.*.server.timeoutSeconds": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:300"
},
"destinations.*.server.headers": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: nullable|array"
},
"destinations.*.squadId": {
"type": "string",
"nullable": true,
"description": "Handoff squad-destination reference. Rules: nullable|string|max:100"
},
"destinations.*.entryAssistantName": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:255"
},
"destinations.*.number": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:50"
},
"destinations.*.extension": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:20"
},
"destinations.*.callerId": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:50"
},
"destinations.*.sipUri": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:255"
},
"destinations.*.assistantId": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:100"
},
"destinations.*.assistantName": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:255"
},
"destinations.*.transferMode": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:rolling-history,swap-system-message-in-history,swap-system-message-in-history-and-remove-transfer-tool-messages,delete-history"
},
"destinations.*.message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"destinations.*.description": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"destinations.*.numberE164CheckEnabled": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"destinations.*.sipHeaders": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rows of {key, value}. Rules: nullable|array"
},
"destinations.*.contextEngineeringPlan": {
"type": "object",
"nullable": true,
"description": "Handoff destination context-carry strategy. Rules: nullable|array"
},
"destinations.*.contextEngineeringPlan.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:none,all,lastNMessages,userAndAssistantMessages,previousAssistantMessages"
},
"destinations.*.contextEngineeringPlan.maxMessages": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:1000"
},
"destinations.*.transferPlan": {
"type": "object",
"nullable": true,
"description": "Rules: nullable|array"
},
"destinations.*.transferPlan.mode": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:80"
},
"destinations.*.transferPlan.message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"destinations.*.transferPlan.sipVerb": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:refer,bye,dial"
},
"destinations.*.transferPlan.timeout": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:600"
},
"destinations.*.transferPlan.dialTimeout": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:600"
},
"destinations.*.transferPlan.holdAudioUrl": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"destinations.*.transferPlan.transferCompleteAudioUrl": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"destinations.*.transferPlan.twiml": {
"type": "string",
"nullable": true,
"description": "Raw call-control markup for the transfer (sipVerb: dial). Rules: nullable|string|max:4000"
},
"destinations.*.transferPlan.sipHeadersInReferToEnabled": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"toolMessages": {
"type": "array",
"items": [],
"nullable": true,
"description": "mcp tools only — spoken-message overrides for individual tools on the MCP server. An empty messages list silences that tool. Rules: nullable|array"
},
"toolMessages.*.name": {
"type": "string",
"description": "The name of the tool on the MCP server. Rules: required|string|max:64"
},
"toolMessages.*.messages": {
"type": "array",
"items": [],
"nullable": true,
"description": "Same message shape as messages. Rules: nullable|array"
},
"knowledgeBases": {
"type": "array",
"items": [],
"nullable": true,
"description": "query tools — knowledge bases the assistant can search. Rules: nullable|array"
},
"knowledgeBases.*.name": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:255"
},
"knowledgeBases.*.description": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"knowledgeBases.*.provider": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:google"
},
"knowledgeBases.*.fileIds": {
"type": "array",
"items": [],
"nullable": true,
"description": "Array of file ids, or a comma-separated string. Rules: nullable"
},
"rejectionPlan": {
"type": "object",
"nullable": true,
"description": "Conditions under which the model's tool call is rejected. Supported by every tool type. Rules: nullable|array"
},
"rejectionPlan.conditions": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: nullable|array"
},
"rejectionPlan.conditions.*.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:regex,liquid"
},
"rejectionPlan.conditions.*.value": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"messages": {
"type": "array",
"items": [],
"nullable": true,
"description": "Lifecycle messages. See Fields page. Rules: nullable|array"
},
"messages.*.type": {
"type": "string",
"description": "Rules: required_with:messages|string|in:request-start,request-complete,request-failed,request-response-delayed"
},
"messages.*.mode": {
"type": "string",
"nullable": true,
"description": "request-start only. Rules: nullable|string|in:default,none,custom"
},
"messages.*.content": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"messages.*.blocking": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"messages.*.role": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:assistant,system"
},
"messages.*.endCallAfterSpokenEnabled": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"messages.*.timingMilliseconds": {
"type": "integer",
"nullable": true,
"description": "request-response-delayed only. Rules: nullable|integer|min:100|max:120000"
},
"messages.*.contents": {
"type": "array",
"items": [],
"nullable": true,
"description": "Spoken-message variants — one is picked at random. Rules: nullable|array"
},
"messages.*.contents.*.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:20"
},
"messages.*.contents.*.text": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"messages.*.contents.*.language": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:20"
},
"messages.*.conditions": {
"type": "array",
"items": [],
"nullable": true,
"description": "Gating conditions for this message. Rules: nullable|array"
},
"messages.*.conditions.*.param": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:200"
},
"messages.*.conditions.*.operator": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:eq,neq,gt,gte,lt,lte"
},
"messages.*.conditions.*.value": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"async": {
"type": "boolean",
"nullable": true,
"description": "Run the tool call without blocking the conversation. Rules: nullable|boolean"
},
"metadata": {
"type": "object",
"nullable": true,
"description": "Arbitrary metadata. Rules: nullable|array"
}
},
"required": [
"name",
"type",
"toolMessages.*.name",
"messages.*.type"
]
},
"example": {
"name": "Check Order Status",
"type": "apiRequest",
"description": "Looks up an order by ID and returns its current status.",
"server": {
"url": "https://api.example-business.com/orders/lookup",
"method": "POST",
"timeoutSeconds": 20,
"headers": [
{
"key": "X-Api-Key",
"value": "{{env.ORDERS_API_KEY}}"
}
],
"bodyProperties": [
{
"name": "orderId",
"type": "string",
"description": "The order confirmation number",
"required": true
}
],
"staticFields": [
{
"key": "source",
"type": "string",
"value": "voice-assistant"
}
],
"lockSchema": false,
"encryptedFields": [
"X-Api-Key"
],
"backoffPlan": {
"type": "exponential",
"maxRetries": 3,
"baseDelaySeconds": 2,
"excludedStatusCodes": [
400,
404
]
},
"credentialId": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b"
},
"variableExtractionPlan": {
"properties": [
{
"name": "orderStatus",
"type": "string",
"description": "Current status of the order",
"required": false
}
],
"aliases": [
{
"key": "status",
"value": "orderStatus"
}
]
},
"rejectionPlan": {
"conditions": [
{
"type": "regex",
"value": "^(cancelled|refunded)$"
}
]
},
"messages": [
{
"type": "request-start",
"mode": "custom",
"content": "Let me check on that order for you."
},
{
"type": "request-failed",
"mode": "custom",
"content": "I'm having trouble reaching our order system right now."
}
],
"async": false,
"metadata": {
"category": "orders"
}
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Check Order Status",
"user_id": 42,
"external_tool_id": "d4e5f6a7-8b9c-4a1d-9e2f-3a4b5c6d7e8f",
"status": "published",
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"type": "apiRequest",
"description": "Looks up an order by ID and returns its current status.",
"function_def": {
"name": "check_order_status"
},
"server": {
"url": "https://api.example-business.com/orders/lookup",
"method": "POST",
"timeoutSeconds": 20,
"headers": [
{
"key": "X-Api-Key",
"value": "{{env.ORDERS_API_KEY}}"
}
],
"bodyProperties": [
{
"name": "orderId",
"type": "string",
"required": true,
"description": "The order confirmation number"
}
],
"staticFields": [
{
"key": "source",
"type": "string",
"value": "voice-assistant"
}
],
"encryptedFields": [
"X-Api-Key"
],
"backoffPlan": {
"type": "exponential",
"maxRetries": 3,
"baseDelaySeconds": 2,
"excludedStatusCodes": [
400,
404
]
},
"credentialId": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b"
},
"variable_extraction_plan": {
"properties": [
{
"name": "orderStatus",
"type": "string",
"description": "Current status of the order",
"required": false
}
],
"aliases": [
{
"key": "status",
"value": "orderStatus"
}
]
},
"destinations": null,
"rejection_plan": {
"conditions": [
{
"type": "regex",
"value": "^(cancelled|refunded)$"
}
]
},
"messages": [
{
"type": "request-start",
"content": "Let me check on that order for you."
},
{
"type": "request-failed",
"content": "I'm having trouble reaching our order system right now."
}
],
"metadata": {
"category": "orders"
},
"async": false,
"created_at": "2026-07-30T14:22:03+00:00",
"updated_at": "2026-07-30T14:22:03+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"read_only": false,
"coreData": {
"id": "d4e5f6a7-8b9c-4a1d-9e2f-3a4b5c6d7e8f"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Assigning another owner without admin rights"
},
"422": {
"description": "Target owner unknown"
},
"500": {
"description": "Live write succeeded but local mirror failed — response carries upstream_id for support"
},
"502": {
"description": "Live platform write failed"
}
}
}
},
"/api/tools/draft": {
"post": {
"operationId": "tools-create-tool-draft",
"summary": "Save a local draft (never touches the live platform)",
"tags": [
"Tools"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true,
"description": "Rules: lenient — empty auto-generates \"New Draft Tool N\""
},
"type": {
"type": "string",
"nullable": true,
"description": "Rules: lenient — falls back to apiRequest when unrecognised"
},
"description": {
"type": "string",
"nullable": true,
"description": "Rules: lenient"
},
"server": {
"type": "object",
"nullable": true,
"description": "Rules: lenient — any partial shape is accepted while drafting"
},
"destinations": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: lenient"
},
"messages": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: lenient"
},
"metadata": {
"type": "object",
"nullable": true,
"description": "Rules: lenient"
}
}
},
"example": {
"name": "",
"type": "function",
"description": "Looks up loyalty points for a phone number.",
"parameters": [
{
"name": "phoneNumber",
"type": "string",
"description": "Caller's phone number",
"required": true
}
]
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "New Draft Tool 1",
"user_id": 42,
"external_tool_id": "draft_Ab12Cd34Ef56",
"status": "draft",
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"type": "function",
"description": "Looks up loyalty points for a phone number.",
"function_def": {
"name": "new_draft_tool_1",
"parameters": [
{
"name": "phoneNumber",
"type": "string",
"required": true,
"description": "Caller's phone number"
}
]
},
"server": null,
"variable_extraction_plan": null,
"destinations": null,
"rejection_plan": null,
"messages": null,
"metadata": null,
"async": false,
"created_at": "2026-07-30T14:22:03+00:00",
"updated_at": "2026-07-30T14:22:03+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"read_only": false,
"coreData": null
}
}
}
}
},
"401": {
"description": "No authenticated user"
},
"403": {
"description": "Feature tools not enabled for the account"
}
}
}
},
"/api/tools/{id}/draft": {
"put": {
"operationId": "tools-update-tool-draft",
"summary": "Update a draft — or demote a published tool to draft locally",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The tool's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Loyalty Points Lookup",
"user_id": 42,
"external_tool_id": "draft_Ab12Cd34Ef56",
"status": "draft",
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"type": "function",
"description": "Looks up loyalty points for a phone number.",
"function_def": {
"name": "loyalty_points_lookup",
"strict": true,
"parameters": [
{
"name": "phoneNumber",
"type": "string",
"required": true,
"description": "Caller's phone number"
}
]
},
"server": null,
"variable_extraction_plan": null,
"destinations": null,
"rejection_plan": null,
"messages": null,
"metadata": null,
"async": false,
"created_at": "2026-07-30T14:22:03+00:00",
"updated_at": "2026-07-30T14:25:11+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"read_only": false,
"coreData": null
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Global tool mutation attempted by a non-super-admin"
},
"404": {
"description": "Tool not found, or outside your account scope"
}
}
}
},
"/api/tools/{id}/publish": {
"post": {
"operationId": "tools-publish-tool",
"summary": "Publish a stored tool — reconstructs the builder model from the database and pushes it live",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The tool's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Loyalty Points Lookup",
"user_id": 42,
"external_tool_id": "e5f6a7b8-1c2d-4e3f-9a8b-7c6d5e4f3a2b",
"status": "published",
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"type": "function",
"description": "Looks up loyalty points for a phone number.",
"function_def": {
"name": "loyalty_points_lookup",
"strict": true,
"parameters": [
{
"name": "phoneNumber",
"type": "string",
"required": true,
"description": "Caller's phone number"
}
]
},
"server": null,
"variable_extraction_plan": null,
"destinations": null,
"rejection_plan": null,
"messages": null,
"metadata": null,
"async": false,
"created_at": "2026-07-30T14:22:03+00:00",
"updated_at": "2026-07-30T14:30:52+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"read_only": false,
"coreData": {
"id": "e5f6a7b8-1c2d-4e3f-9a8b-7c6d5e4f3a2b"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Global tool mutation attempted by a non-super-admin"
},
"404": {
"description": "Tool not found, or outside your account scope"
},
"422": {
"description": "Composition invalid for the live platform (e.g. a transferCall with no destinations)"
},
"502": {
"description": "Live platform write failed"
}
}
}
},
"/api/tools/{id}": {
"get": {
"operationId": "tools-get-tool",
"summary": "Retrieve one tool",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The tool's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Check Order Status",
"user_id": 42,
"external_tool_id": "d4e5f6a7-8b9c-4a1d-9e2f-3a4b5c6d7e8f",
"status": "published",
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"type": "apiRequest",
"description": "Looks up an order by ID and returns its current status.",
"function_def": {
"name": "check_order_status"
},
"server": {
"url": "https://api.example-business.com/orders/lookup",
"method": "POST",
"timeoutSeconds": 20,
"credentialId": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b"
},
"variable_extraction_plan": {
"properties": [
{
"name": "orderStatus",
"type": "string",
"description": "Current status of the order",
"required": false
}
]
},
"destinations": null,
"rejection_plan": null,
"messages": [
{
"type": "request-start",
"content": "Let me check on that order for you."
}
],
"metadata": {
"category": "orders"
},
"async": false,
"created_at": "2026-06-01T14:22:03+00:00",
"updated_at": "2026-07-15T09:10:44+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"read_only": false,
"coreData": {
"id": "d4e5f6a7-8b9c-4a1d-9e2f-3a4b5c6d7e8f"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature tools not enabled for the account"
},
"404": {
"description": "Tool not found, or outside your account scope"
}
}
},
"put": {
"operationId": "tools-update-tool",
"summary": "Publish changes — creates or patches the live tool, sets status published",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The tool's public id.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Tool display name. Rules: required|string|max:100"
},
"type": {
"type": "string",
"description": "Tool-type discriminator. Fixed at creation — cannot be changed on update. Rules: required|string|in:apiRequest,function,transferCall,endCall,dtmf,voicemail,handoff,query,mcp"
},
"user_id": {
"type": "integer",
"nullable": true,
"description": "Owner assignment — honoured only for admin roles. Rules: nullable|integer|exists:users,id"
},
"reseller_id": {
"type": "string",
"nullable": true,
"description": "Reseller assignment — honoured only for super admins. Rules: nullable|uuid|exists:resellers,id"
},
"isGlobal": {
"type": "boolean",
"nullable": true,
"description": "Marks the tool a platform Global Tool (no owner). Super-admin only; clears user_id. Rules: nullable|boolean"
},
"functionName": {
"type": "string",
"nullable": true,
"description": "The callable name the model uses to invoke the tool. Falls back to a slug of name when omitted. Rules: nullable|string|max:64|regex:/^[a-zA-Z0-9_-]+$/"
},
"description": {
"type": "string",
"nullable": true,
"description": "Top-level tool description (apiRequest). Function tools keep their description inside function_def. Rules: nullable|string|max:2000"
},
"parameters": {
"type": "array",
"items": [],
"nullable": true,
"description": "Function/handoff parameter schema-builder rows: {name, type, description, required, enum}. Rules: nullable|array"
},
"parametersLockSchema": {
"type": "boolean",
"nullable": true,
"description": "Locks the parameters schema (additionalProperties:false). Rules: nullable|boolean"
},
"strict": {
"type": "boolean",
"nullable": true,
"description": "Enforce exact schema adherence on the tool call (function tools). Rules: nullable|boolean"
},
"server": {
"type": "object",
"nullable": true,
"description": "Request configuration (apiRequest) / webhook target (function). See Fields page. Rules: nullable|array"
},
"server.url": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|url|max:2000"
},
"server.method": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:GET,POST,PUT,PATCH,DELETE"
},
"server.timeoutSeconds": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:300"
},
"server.headers": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rows of {key, value}. Rules: nullable|array"
},
"server.bodyProperties": {
"type": "array",
"items": [],
"nullable": true,
"description": "Recursive request-body schema tree — validated as a whole array (see Fields page). Rules: nullable|array"
},
"server.staticFields": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rows of {key, type, value} merged into the request body as typed literals. Rules: nullable|array"
},
"server.lockSchema": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"server.encryptedFields": {
"type": "array",
"items": [],
"nullable": true,
"description": "Header/body field names whose values are stored encrypted. Rules: nullable|array"
},
"server.encryptedFields.*": {
"type": "string",
"description": "Rules: string|max:200"
},
"server.backoffPlan": {
"type": "object",
"nullable": true,
"description": "Retry policy for failed requests. Rules: nullable|array"
},
"server.backoffPlan.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:fixed,exponential"
},
"server.backoffPlan.maxRetries": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:0|max:10"
},
"server.backoffPlan.baseDelaySeconds": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:0|max:300"
},
"server.backoffPlan.excludedStatusCodes": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: nullable|array"
},
"server.backoffPlan.excludedStatusCodes.*": {
"type": "integer",
"description": "Rules: integer|min:100|max:599"
},
"server.credentialId": {
"type": "string",
"nullable": true,
"description": "A personal credential's id (see Credentials group) used to authenticate the outbound request. Rules: nullable|string|max:100"
},
"server.staticIpAddressesEnabled": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"server.serverEncryptedPaths": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: nullable|array"
},
"server.serverEncryptedPaths.*": {
"type": "string",
"description": "Rules: string|max:200"
},
"server.sipInfoDtmfEnabled": {
"type": "boolean",
"nullable": true,
"description": "dtmf tools only. Rules: nullable|boolean"
},
"server.beepDetectionEnabled": {
"type": "boolean",
"nullable": true,
"description": "voicemail tools only — wait for the answering-machine beep. Rules: nullable|boolean"
},
"server.protocol": {
"type": "string",
"nullable": true,
"description": "mcp tools only — transport: shttp (Streamable HTTP, default) or sse (legacy). Sent to the voice platform as metadata.protocol. Rules: nullable|string|in:shttp,sse"
},
"variableExtractionPlan": {
"type": "object",
"nullable": true,
"description": "Extracts variables from the API response (apiRequest). See Fields page. Rules: nullable|array"
},
"variableExtractionPlan.properties": {
"type": "array",
"items": [],
"nullable": true,
"description": "Schema rows: {name, type, description, required, enum}. Rules: nullable|array"
},
"variableExtractionPlan.aliases": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rows of {key, value}. Rules: nullable|array"
},
"destinations": {
"type": "array",
"items": [],
"nullable": true,
"description": "Transfer/handoff targets (transferCall, handoff). See Fields page. Rules: nullable|array"
},
"destinations.*.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:number,sip,assistant,dynamic,squad"
},
"destinations.*.server": {
"type": "object",
"nullable": true,
"description": "Handoff dynamic-destination server config. Rules: nullable|array"
},
"destinations.*.server.url": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|url|max:2000"
},
"destinations.*.server.timeoutSeconds": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:300"
},
"destinations.*.server.headers": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: nullable|array"
},
"destinations.*.squadId": {
"type": "string",
"nullable": true,
"description": "Handoff squad-destination reference. Rules: nullable|string|max:100"
},
"destinations.*.entryAssistantName": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:255"
},
"destinations.*.number": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:50"
},
"destinations.*.extension": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:20"
},
"destinations.*.callerId": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:50"
},
"destinations.*.sipUri": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:255"
},
"destinations.*.assistantId": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:100"
},
"destinations.*.assistantName": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:255"
},
"destinations.*.transferMode": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:rolling-history,swap-system-message-in-history,swap-system-message-in-history-and-remove-transfer-tool-messages,delete-history"
},
"destinations.*.message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"destinations.*.description": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"destinations.*.numberE164CheckEnabled": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"destinations.*.sipHeaders": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rows of {key, value}. Rules: nullable|array"
},
"destinations.*.contextEngineeringPlan": {
"type": "object",
"nullable": true,
"description": "Handoff destination context-carry strategy. Rules: nullable|array"
},
"destinations.*.contextEngineeringPlan.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:none,all,lastNMessages,userAndAssistantMessages,previousAssistantMessages"
},
"destinations.*.contextEngineeringPlan.maxMessages": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:1000"
},
"destinations.*.transferPlan": {
"type": "object",
"nullable": true,
"description": "Rules: nullable|array"
},
"destinations.*.transferPlan.mode": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:80"
},
"destinations.*.transferPlan.message": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"destinations.*.transferPlan.sipVerb": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:refer,bye,dial"
},
"destinations.*.transferPlan.timeout": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:600"
},
"destinations.*.transferPlan.dialTimeout": {
"type": "integer",
"nullable": true,
"description": "Rules: nullable|integer|min:1|max:600"
},
"destinations.*.transferPlan.holdAudioUrl": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"destinations.*.transferPlan.transferCompleteAudioUrl": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"destinations.*.transferPlan.twiml": {
"type": "string",
"nullable": true,
"description": "Raw call-control markup for the transfer (sipVerb: dial). Rules: nullable|string|max:4000"
},
"destinations.*.transferPlan.sipHeadersInReferToEnabled": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"toolMessages": {
"type": "array",
"items": [],
"nullable": true,
"description": "mcp tools only — spoken-message overrides for individual tools on the MCP server. An empty messages list silences that tool. Rules: nullable|array"
},
"toolMessages.*.name": {
"type": "string",
"description": "The name of the tool on the MCP server. Rules: required|string|max:64"
},
"toolMessages.*.messages": {
"type": "array",
"items": [],
"nullable": true,
"description": "Same message shape as messages. Rules: nullable|array"
},
"knowledgeBases": {
"type": "array",
"items": [],
"nullable": true,
"description": "query tools — knowledge bases the assistant can search. Rules: nullable|array"
},
"knowledgeBases.*.name": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:255"
},
"knowledgeBases.*.description": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"knowledgeBases.*.provider": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:google"
},
"knowledgeBases.*.fileIds": {
"type": "array",
"items": [],
"nullable": true,
"description": "Array of file ids, or a comma-separated string. Rules: nullable"
},
"rejectionPlan": {
"type": "object",
"nullable": true,
"description": "Conditions under which the model's tool call is rejected. Supported by every tool type. Rules: nullable|array"
},
"rejectionPlan.conditions": {
"type": "array",
"items": [],
"nullable": true,
"description": "Rules: nullable|array"
},
"rejectionPlan.conditions.*.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:regex,liquid"
},
"rejectionPlan.conditions.*.value": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:2000"
},
"messages": {
"type": "array",
"items": [],
"nullable": true,
"description": "Lifecycle messages. See Fields page. Rules: nullable|array"
},
"messages.*.type": {
"type": "string",
"description": "Rules: required_with:messages|string|in:request-start,request-complete,request-failed,request-response-delayed"
},
"messages.*.mode": {
"type": "string",
"nullable": true,
"description": "request-start only. Rules: nullable|string|in:default,none,custom"
},
"messages.*.content": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"messages.*.blocking": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"messages.*.role": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:assistant,system"
},
"messages.*.endCallAfterSpokenEnabled": {
"type": "boolean",
"nullable": true,
"description": "Rules: nullable|boolean"
},
"messages.*.timingMilliseconds": {
"type": "integer",
"nullable": true,
"description": "request-response-delayed only. Rules: nullable|integer|min:100|max:120000"
},
"messages.*.contents": {
"type": "array",
"items": [],
"nullable": true,
"description": "Spoken-message variants — one is picked at random. Rules: nullable|array"
},
"messages.*.contents.*.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:20"
},
"messages.*.contents.*.text": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"messages.*.contents.*.language": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:20"
},
"messages.*.conditions": {
"type": "array",
"items": [],
"nullable": true,
"description": "Gating conditions for this message. Rules: nullable|array"
},
"messages.*.conditions.*.param": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:200"
},
"messages.*.conditions.*.operator": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:eq,neq,gt,gte,lt,lte"
},
"messages.*.conditions.*.value": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:1000"
},
"async": {
"type": "boolean",
"nullable": true,
"description": "Run the tool call without blocking the conversation. Rules: nullable|boolean"
},
"metadata": {
"type": "object",
"nullable": true,
"description": "Arbitrary metadata. Rules: nullable|array"
}
},
"required": [
"name",
"type",
"toolMessages.*.name",
"messages.*.type"
]
},
"example": {
"name": "Check Order Status",
"type": "apiRequest",
"description": "Looks up an order by ID and returns its current status, including estimated delivery date.",
"server": {
"url": "https://api.example-business.com/orders/lookup",
"method": "POST",
"timeoutSeconds": 25,
"headers": [
{
"key": "X-Api-Key",
"value": "{{env.ORDERS_API_KEY}}"
}
],
"bodyProperties": [
{
"name": "orderId",
"type": "string",
"description": "The order confirmation number",
"required": true
}
],
"credentialId": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b"
},
"variableExtractionPlan": {
"properties": [
{
"name": "orderStatus",
"type": "string",
"description": "Current status of the order",
"required": false
},
{
"name": "estimatedDelivery",
"type": "string",
"description": "Estimated delivery date",
"required": false
}
]
},
"messages": [
{
"type": "request-start",
"mode": "custom",
"content": "Let me check on that order for you."
}
],
"async": false,
"metadata": {
"category": "orders"
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Check Order Status",
"user_id": 42,
"external_tool_id": "d4e5f6a7-8b9c-4a1d-9e2f-3a4b5c6d7e8f",
"status": "published",
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"type": "apiRequest",
"description": "Looks up an order by ID and returns its current status, including estimated delivery date.",
"function_def": {
"name": "check_order_status"
},
"server": {
"url": "https://api.example-business.com/orders/lookup",
"method": "POST",
"timeoutSeconds": 25,
"headers": [
{
"key": "X-Api-Key",
"value": "{{env.ORDERS_API_KEY}}"
}
],
"bodyProperties": [
{
"name": "orderId",
"type": "string",
"required": true,
"description": "The order confirmation number"
}
],
"credentialId": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b"
},
"variable_extraction_plan": {
"properties": [
{
"name": "orderStatus",
"type": "string",
"description": "Current status of the order",
"required": false
},
{
"name": "estimatedDelivery",
"type": "string",
"description": "Estimated delivery date",
"required": false
}
]
},
"destinations": null,
"rejection_plan": null,
"messages": [
{
"type": "request-start",
"content": "Let me check on that order for you."
}
],
"metadata": {
"category": "orders"
},
"async": false,
"created_at": "2026-06-01T14:22:03+00:00",
"updated_at": "2026-07-30T14:30:52+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"read_only": false,
"coreData": {
"id": "d4e5f6a7-8b9c-4a1d-9e2f-3a4b5c6d7e8f"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Global tool mutation attempted by a non-super-admin"
},
"404": {
"description": "Tool not found, or outside your account scope"
},
"422": {
"description": "Composition invalid for the live platform"
},
"502": {
"description": "Live platform write failed"
}
}
},
"delete": {
"operationId": "tools-delete-tool",
"summary": "Delete a tool (live first for published; drafts are local-only)",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The tool's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Tool \"Check Order Status\" deleted."
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Global tool mutation attempted by a non-super-admin"
},
"404": {
"description": "Tool not found, or outside your account scope"
}
}
}
},
"/api/tools/{id}/duplicate": {
"post": {
"operationId": "tools-duplicate-tool",
"summary": "Duplicate as a local draft copy",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The tool's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"name": "Check Order Status (Copy)",
"user_id": 42,
"external_tool_id": "draft_Gh78Ij90Kl12",
"status": "draft",
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"type": "apiRequest",
"description": "Looks up an order by ID and returns its current status.",
"function_def": {
"name": "check_order_status"
},
"server": {
"url": "https://api.example-business.com/orders/lookup",
"method": "POST",
"timeoutSeconds": 20,
"credentialId": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b"
},
"variable_extraction_plan": {
"properties": [
{
"name": "orderStatus",
"type": "string",
"description": "Current status of the order",
"required": false
}
]
},
"destinations": null,
"rejection_plan": null,
"messages": [
{
"type": "request-start",
"content": "Let me check on that order for you."
}
],
"metadata": {
"category": "orders"
},
"async": false,
"created_at": "2026-07-30T14:35:19+00:00",
"updated_at": "2026-07-30T14:35:19+00:00",
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"read_only": false,
"coreData": null
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Global tool mutation attempted by a non-super-admin"
},
"404": {
"description": "Tool not found, or outside your account scope"
},
"500": {
"description": "Copy failed"
}
}
}
},
"/api/tools/{id}/assistants": {
"get": {
"operationId": "tools-get-tool-assistants",
"summary": "List the caller's assistants with an attached flag for this tool",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The tool's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"assistant_id": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"name": "Front Desk",
"attached": true
},
{
"assistant_id": "b2c3d4e5-2f3a-4b4c-9d0e-1f2a3b4c5d6e",
"name": "After Hours",
"attached": false
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature tools not enabled for the account"
},
"404": {
"description": "Tool not found, or outside your account scope"
}
}
},
"put": {
"operationId": "tools-sync-tool-assistants",
"summary": "Bulk attach/detach this tool across the caller's assistants",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The tool's public id.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"assistant_ids": {
"type": "array",
"items": [],
"description": "The full desired set of assistant public ids this tool should be attached to. Rules: present|array"
},
"assistant_ids.*": {
"type": "string",
"description": "Rules: string"
}
},
"required": [
"assistant_ids"
]
},
"example": {
"assistant_ids": [
"a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Assistant assignments updated.",
"data": {
"attached": [
"Front Desk"
],
"detached": [
"After Hours"
],
"failed": []
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Global tool mutation attempted by a non-super-admin"
},
"404": {
"description": "Tool not found, or outside your account scope"
},
"422": {
"description": "Tool is still a draft"
},
"502": {
"description": "One or more assistant updates failed live"
}
}
}
},
"/api/tools/credentials": {
"get": {
"operationId": "tools-list-credentials",
"summary": "Slim list of the caller's active credentials, for the Authorization dropdown",
"tags": [
"Tools"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b",
"provider": "custom-credential",
"name": "Orders API"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature tools not enabled for the account"
}
}
},
"post": {
"operationId": "tools-create-credential",
"summary": "Create a personal server-auth credential",
"tags": [
"Tools"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Credential kind. Defaults to custom-credential when omitted. Rules: required|string|in:custom-credential,webhook"
},
"name": {
"type": "string",
"nullable": true,
"description": "Display name. Rules: nullable|string|max:40"
},
"authenticationPlan": {
"type": "object",
"description": "The auth configuration — shape depends on type. Rules: required|array"
},
"authenticationPlan.type": {
"type": "string",
"description": "Immutable after creation — update rejects a differing type. Rules: required|string|in:bearer,oauth2,hmac"
},
"authenticationPlan.token": {
"type": "string",
"nullable": true,
"description": "Bearer token value. Rules: required when type=bearer"
},
"authenticationPlan.headerName": {
"type": "string",
"nullable": true,
"description": "bearer only — defaults to Authorization. Rules: nullable|string"
},
"authenticationPlan.bearerPrefixEnabled": {
"type": "boolean",
"nullable": true,
"description": "bearer only. Rules: nullable|boolean"
},
"authenticationPlan.url": {
"type": "string",
"nullable": true,
"description": "OAuth2 token URL. Rules: required when type=oauth2"
},
"authenticationPlan.clientId": {
"type": "string",
"nullable": true,
"description": "Rules: required when type=oauth2"
},
"authenticationPlan.clientSecret": {
"type": "string",
"nullable": true,
"description": "Rules: required when type=oauth2"
},
"authenticationPlan.scope": {
"type": "string",
"nullable": true,
"description": "oauth2 only. Rules: nullable|string"
},
"authenticationPlan.secretKey": {
"type": "string",
"nullable": true,
"description": "Rules: required when type=hmac"
},
"authenticationPlan.algorithm": {
"type": "string",
"nullable": true,
"description": "Rules: required when type=hmac"
},
"authenticationPlan.signatureHeader": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.signaturePrefix": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.timestampHeader": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.messageIdHeader": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.includeTimestamp": {
"type": "boolean",
"nullable": true,
"description": "hmac only. Rules: nullable|boolean"
},
"authenticationPlan.payloadFormat": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.signatureEncoding": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.secretIsBase64": {
"type": "boolean",
"nullable": true,
"description": "hmac only. Rules: nullable|boolean"
},
"encryptionPlan": {
"type": "object",
"nullable": true,
"description": "Optional public-key encryption for the stored secret. Rules: nullable|array"
},
"encryptionPlan.publicKey": {
"type": "string",
"nullable": true,
"description": "Requests are encrypted with this key before being sent. Rules: nullable — PEM-formatted public key"
}
},
"required": [
"provider",
"authenticationPlan",
"authenticationPlan.type"
]
},
"example": {
"provider": "custom-credential",
"name": "Orders API",
"authenticationPlan": {
"type": "bearer",
"token": "sk_live_51Hxxxxxxxxxxxxxxxxxxxxxxxx",
"bearerPrefixEnabled": true
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b",
"provider": "custom-credential",
"name": "Orders API",
"auth_type": "bearer",
"encryption_enabled": false,
"status": "active"
}
}
}
}
},
"401": {
"description": "No authenticated user"
},
"403": {
"description": "Feature tools not enabled for the account"
},
"422": {
"description": "Missing per-type required fields"
},
"502": {
"description": "Live credential creation failed"
}
}
}
},
"/api/tools/credentials/manage": {
"get": {
"operationId": "tools-manage-credentials",
"summary": "Full list of the caller's personal credentials, for the credential manager",
"tags": [
"Tools"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b",
"provider": "custom-credential",
"name": "Orders API",
"auth_type": "bearer",
"encryption_enabled": false,
"status": "active"
},
{
"id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
"provider": "webhook",
"name": "Loyalty Service",
"auth_type": "hmac",
"encryption_enabled": true,
"status": "inactive"
}
]
}
}
}
},
"401": {
"description": "No authenticated user"
},
"403": {
"description": "Feature tools not enabled for the account"
}
}
}
},
"/api/tools/credentials/{id}": {
"put": {
"operationId": "tools-update-credential",
"summary": "Update an owned credential (auth type is immutable)",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The credential's public id.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Credential kind. Defaults to custom-credential when omitted. Rules: required|string|in:custom-credential,webhook"
},
"name": {
"type": "string",
"nullable": true,
"description": "Display name. Rules: nullable|string|max:40"
},
"authenticationPlan": {
"type": "object",
"description": "The auth configuration — shape depends on type. Rules: required|array"
},
"authenticationPlan.type": {
"type": "string",
"description": "Immutable after creation — update rejects a differing type. Rules: required|string|in:bearer,oauth2,hmac"
},
"authenticationPlan.token": {
"type": "string",
"nullable": true,
"description": "Bearer token value. Rules: required when type=bearer"
},
"authenticationPlan.headerName": {
"type": "string",
"nullable": true,
"description": "bearer only — defaults to Authorization. Rules: nullable|string"
},
"authenticationPlan.bearerPrefixEnabled": {
"type": "boolean",
"nullable": true,
"description": "bearer only. Rules: nullable|boolean"
},
"authenticationPlan.url": {
"type": "string",
"nullable": true,
"description": "OAuth2 token URL. Rules: required when type=oauth2"
},
"authenticationPlan.clientId": {
"type": "string",
"nullable": true,
"description": "Rules: required when type=oauth2"
},
"authenticationPlan.clientSecret": {
"type": "string",
"nullable": true,
"description": "Rules: required when type=oauth2"
},
"authenticationPlan.scope": {
"type": "string",
"nullable": true,
"description": "oauth2 only. Rules: nullable|string"
},
"authenticationPlan.secretKey": {
"type": "string",
"nullable": true,
"description": "Rules: required when type=hmac"
},
"authenticationPlan.algorithm": {
"type": "string",
"nullable": true,
"description": "Rules: required when type=hmac"
},
"authenticationPlan.signatureHeader": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.signaturePrefix": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.timestampHeader": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.messageIdHeader": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.includeTimestamp": {
"type": "boolean",
"nullable": true,
"description": "hmac only. Rules: nullable|boolean"
},
"authenticationPlan.payloadFormat": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.signatureEncoding": {
"type": "string",
"nullable": true,
"description": "hmac only. Rules: nullable|string"
},
"authenticationPlan.secretIsBase64": {
"type": "boolean",
"nullable": true,
"description": "hmac only. Rules: nullable|boolean"
},
"encryptionPlan": {
"type": "object",
"nullable": true,
"description": "Optional public-key encryption for the stored secret. Rules: nullable|array"
},
"encryptionPlan.publicKey": {
"type": "string",
"nullable": true,
"description": "Requests are encrypted with this key before being sent. Rules: nullable — PEM-formatted public key"
}
},
"required": [
"provider",
"authenticationPlan",
"authenticationPlan.type"
]
},
"example": {
"provider": "custom-credential",
"name": "Orders API (v2)",
"authenticationPlan": {
"type": "bearer",
"token": "sk_live_51Hyyyyyyyyyyyyyyyyyyyyyyyy",
"bearerPrefixEnabled": true
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b",
"provider": "custom-credential",
"name": "Orders API (v2)",
"auth_type": "bearer",
"encryption_enabled": false,
"status": "active"
}
}
}
}
},
"401": {
"description": "No authenticated user"
},
"403": {
"description": "Feature tools not enabled for the account"
},
"404": {
"description": "Credential not found, or not owned by the caller"
},
"422": {
"description": "Auth type differs from the stored credential"
},
"502": {
"description": "Live credential update failed"
}
}
},
"delete": {
"operationId": "tools-delete-credential",
"summary": "Delete an owned credential (live platform, then locally)",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The credential's public id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Credential \"Orders API\" deleted."
}
}
}
},
"401": {
"description": "No authenticated user"
},
"403": {
"description": "Feature tools not enabled for the account"
},
"404": {
"description": "Credential not found, or not owned by the caller"
},
"502": {
"description": "Live delete failed — local row is kept"
}
}
}
},
"/api/tools/credentials/{id}/status": {
"patch": {
"operationId": "tools-update-credential-status",
"summary": "Toggle a credential active/inactive",
"tags": [
"Tools"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The credential's public id.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Rules: required|string|in:active,inactive"
}
},
"required": [
"status"
]
},
"example": {
"status": "inactive"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b",
"provider": "custom-credential",
"name": "Orders API",
"auth_type": "bearer",
"encryption_enabled": false,
"status": "inactive"
}
}
}
}
},
"401": {
"description": "No authenticated user"
},
"403": {
"description": "Feature tools not enabled for the account"
},
"404": {
"description": "Credential not found, or not owned by the caller"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/phone-numbers/available": {
"get": {
"operationId": "phone-numbers-available-phone-numbers",
"summary": "Search purchasable phone number inventory",
"tags": [
"Phone Numbers"
],
"parameters": [
{
"name": "country",
"in": "query",
"required": false,
"description": "Country name; mapped to a 2-letter country_code when provided. Rules: nullable|string|in:United States,Canada,Australia,United Kingdom",
"schema": {
"type": "string"
}
},
{
"name": "country_code",
"in": "query",
"required": false,
"description": "ISO country code used when country is omitted. Rules: nullable|string|max:2",
"schema": {
"type": "string",
"default": "US"
}
},
{
"name": "area_code",
"in": "query",
"required": false,
"description": "Rules: nullable|string|max:3 (exactly 3 digits when set; only US, CA, AU, GB)",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Rules: nullable|integer|min:1|max:50",
"schema": {
"type": "integer",
"default": 10
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"phone_number": "+14155551234",
"locality": "San Francisco",
"region": "CA"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature phone_numbers not enabled for the account"
},
"422": {
"description": "Area code not supported or not 3 digits"
},
"500": {
"description": "Inventory search failed"
}
}
}
},
"/api/phone-numbers": {
"post": {
"operationId": "phone-numbers-purchase-phone-number",
"summary": "Purchase a phone number and register it unassigned",
"tags": [
"Phone Numbers"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone_number": {
"type": "string",
"description": "E.164 number from GET /phone-numbers/available. Rules: required|string|max:20|regex:/^\\+[1-9]\\d{1,14}$/"
},
"country_code": {
"type": "string",
"nullable": true,
"description": "Optional ISO country code for the purchase. Rules: nullable|string|max:2"
},
"name": {
"type": "string",
"nullable": true,
"description": "Optional friendly label. Rules: nullable|string|max:255"
}
},
"required": [
"phone_number"
]
},
"example": {
"phone_number": "+14155551234",
"country_code": "US",
"name": "Main Line"
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Phone number purchased. Assign it to an assistant or squad when ready.",
"data": {
"id": 7,
"phone_number": "+14155551234",
"vapi_phone_number_id": "c3d4e5f6-1a2b-4c3d-9e0f-1a2b3c4d5e6f",
"assistant_id": null,
"vapi_assistant_id": null,
"vapi_squad_id": null,
"vapi_workflow_id": null,
"name": "Main Line",
"provider": "twilio",
"sms_enabled": false,
"static_ip_enabled": false
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature phone_numbers not enabled for the account"
},
"422": {
"description": "Invalid E.164 or number already in account"
},
"500": {
"description": "Purchase failed at the telephony provider"
},
"502": {
"description": "Purchased but voice-platform import failed"
}
}
},
"get": {
"operationId": "phone-numbers-list-phone-numbers",
"summary": "List phone numbers you can access",
"tags": [
"Phone Numbers"
],
"parameters": [
{
"name": "search",
"in": "query",
"required": false,
"description": "Rules: string (matches phone_number or name)",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Rules: clamped to a minimum of 1",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Rules: clamped between 1 and 100",
"schema": {
"type": "integer",
"default": 15
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 7,
"phone_number": "+14155551234",
"vapi_assistant_id": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"vapi_squad_id": null,
"vapi_workflow_id": null,
"name": "Front Desk Line",
"provider": "twilio",
"sms_enabled": true,
"unassigned": false,
"assistant": {
"name": "Front Desk"
}
},
{
"id": 8,
"phone_number": "+14155557890",
"vapi_assistant_id": null,
"vapi_squad_id": null,
"vapi_workflow_id": null,
"name": "Spare Line",
"provider": "twilio",
"sms_enabled": false,
"unassigned": true,
"assistant": null
}
],
"pagination": {
"current_page": 1,
"last_page": 1,
"per_page": 15,
"total": 2,
"from": 1,
"to": 2
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature phone_numbers not enabled for the account"
}
}
}
},
"/api/phone-numbers/{id}": {
"get": {
"operationId": "phone-numbers-get-phone-number",
"summary": "Open a number for editing (materialises its configuration on first touch)",
"tags": [
"Phone Numbers"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The phone number to configure.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 7,
"phone_number": "+14155551234",
"vapi_phone_number_id": "c3d4e5f6-1a2b-4c3d-9e0f-1a2b3c4d5e6f",
"assistant_id": 12,
"vapi_assistant_id": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"vapi_squad_id": null,
"vapi_workflow_id": null,
"name": "Front Desk Line",
"provider": "twilio",
"fallback_destination": {
"type": "number",
"number": "+14155559876",
"message": "Please hold while we connect you.",
"description": "Used when the assistant is unavailable",
"callerId": "+14155551234"
},
"server": {
"url": "https://api.example-business.com/webhooks/calls",
"timeoutSeconds": 20,
"headers": {
"X-Source": "sulus"
},
"staticIpAddressesEnabled": false
},
"hooks": [],
"sms_enabled": true,
"static_ip_enabled": false,
"metadata": null,
"last_synced_at": "2026-07-30T14:22:03.000000Z",
"user_id": 42,
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"created_at": "2026-06-01T14:22:03.000000Z",
"updated_at": "2026-07-15T09:10:44.000000Z",
"assistant": {
"id": 12,
"name": "Front Desk",
"vapi_assistant_id": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d"
},
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"sms_available": true
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature phone_numbers not enabled for the account"
},
"404": {
"description": "Number not found, or outside your account scope"
}
}
},
"put": {
"operationId": "phone-numbers-update-phone-number",
"summary": "Update a number's configuration (writes to the live voice platform first, then mirrors locally)",
"tags": [
"Phone Numbers"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The phone number to configure.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true,
"description": "Reference label for the number. Rules: nullable|string|max:255"
},
"vapi_assistant_id": {
"type": "string",
"nullable": true,
"description": "Inbound routing target: the assistant that answers this number. Mutually exclusive with vapi_squad_id and vapi_workflow_id. Rules: nullable|string|max:255"
},
"vapi_squad_id": {
"type": "string",
"nullable": true,
"description": "Inbound routing target: the squad that answers this number. Mutually exclusive with vapi_assistant_id and vapi_workflow_id. Rules: nullable|string|max:255"
},
"vapi_workflow_id": {
"type": "string",
"nullable": true,
"description": "Inbound routing target: the workflow that answers this number. Mutually exclusive with vapi_assistant_id and vapi_squad_id. Rules: nullable|string|max:255"
},
"sms_enabled": {
"type": "boolean",
"nullable": true,
"description": "Toggles the messaging webhook for this number. Rules: nullable|boolean"
},
"static_ip_enabled": {
"type": "boolean",
"nullable": true,
"description": "Routes webhook requests through the provider's static IP range for firewall whitelisting. Always mirrored onto server.staticIpAddressesEnabled. Rules: nullable|boolean"
},
"fallback_destination": {
"type": "object",
"nullable": true,
"description": "Where the call goes when the assistant is unavailable. null or {} clears the whole block. Rules: nullable|array"
},
"fallback_destination.type": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|in:number,sip"
},
"fallback_destination.number": {
"type": "string",
"nullable": true,
"description": "E.164 format. Rules: nullable|required_if:fallback_destination.type,number|string|regex:/^\\+[1-9]\\d{6,14}$/"
},
"fallback_destination.sipUri": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|required_if:fallback_destination.type,sip|string|max:255"
},
"fallback_destination.message": {
"type": "string",
"nullable": true,
"description": "What is said before the fallback transfer. Rules: nullable|string|max:1000"
},
"fallback_destination.description": {
"type": "string",
"nullable": true,
"description": "Internal note on when the fallback applies. Rules: nullable|string|max:1000"
},
"fallback_destination.extension": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:255"
},
"fallback_destination.callerId": {
"type": "string",
"nullable": true,
"description": "E.164 format. Rules: nullable|string|regex:/^\\+[1-9]\\d{6,14}$/"
},
"server": {
"type": "object",
"nullable": true,
"description": "Webhook target for call events. null or {} clears the whole block. Rules: nullable|array"
},
"server.url": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|url|max:2048"
},
"server.secret": {
"type": "string",
"nullable": true,
"description": "Shared secret sent with webhook requests. Rules: nullable|string|max:2048"
},
"server.timeoutSeconds": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|numeric|min:1|max:300"
},
"server.credentialId": {
"type": "string",
"nullable": true,
"description": "A personal credential's id used to authenticate the webhook request (see the Tools module's Credentials group). Rules: nullable|string|max:255"
},
"server.headers": {
"type": "object",
"nullable": true,
"description": "Header name/value map sent with webhook requests. Rules: nullable|array"
},
"server.headers.*": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:4096"
},
"hooks": {
"type": "array",
"items": [],
"nullable": true,
"description": "Event-triggered actions (e.g. on ringing, on call end). Rules: nullable|array"
}
}
},
"example": {
"name": "Front Desk Line",
"vapi_assistant_id": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"sms_enabled": true,
"static_ip_enabled": false,
"fallback_destination": {
"type": "number",
"number": "+14155559876",
"message": "Please hold while we connect you.",
"description": "Used when the assistant is unavailable",
"callerId": "+14155551234"
},
"server": {
"url": "https://api.example-business.com/webhooks/calls",
"secret": "whsec_5f4dcc3b5aa765d61d8327deb882cf99",
"timeoutSeconds": 20,
"headers": {
"X-Source": "sulus"
}
},
"hooks": []
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Phone number configuration updated.",
"data": {
"id": 7,
"phone_number": "+14155551234",
"vapi_phone_number_id": "c3d4e5f6-1a2b-4c3d-9e0f-1a2b3c4d5e6f",
"assistant_id": 12,
"vapi_assistant_id": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
"vapi_squad_id": null,
"vapi_workflow_id": null,
"name": "Front Desk Line",
"provider": "twilio",
"fallback_destination": {
"type": "number",
"number": "+14155559876",
"message": "Please hold while we connect you.",
"description": "Used when the assistant is unavailable",
"callerId": "+14155551234"
},
"server": {
"url": "https://api.example-business.com/webhooks/calls",
"secret": "whsec_5f4dcc3b5aa765d61d8327deb882cf99",
"timeoutSeconds": 20,
"headers": {
"X-Source": "sulus"
},
"staticIpAddressesEnabled": false
},
"hooks": [],
"sms_enabled": true,
"static_ip_enabled": false,
"metadata": null,
"last_synced_at": "2026-07-30T14:35:19.000000Z",
"user_id": 42,
"created_by": 42,
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"created_at": "2026-06-01T14:22:03.000000Z",
"updated_at": "2026-07-30T14:35:19.000000Z",
"assistant": {
"id": 12,
"name": "Front Desk",
"vapi_assistant_id": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d"
},
"user": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature phone_numbers not enabled for the account"
},
"404": {
"description": "Number not found, or outside your account scope"
},
"422": {
"description": "More than one inbound routing target set"
},
"502": {
"description": "Live platform write failed"
}
}
}
},
"/api/v1/kb/knowledge-bases": {
"get": {
"operationId": "knowledge-docs-list-libraries",
"summary": "List libraries you can access (auto-provisions your default library)",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "search",
"in": "query",
"required": false,
"description": "Rules: string (matches name, description, or the owner's name/email)",
"schema": {
"type": "string"
}
},
{
"name": "owner_user_id",
"in": "query",
"required": false,
"description": "Rules: honoured only for super admins and reseller admins",
"schema": {
"type": "integer"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Rules: in: published, draft, archived — filters to libraries containing at least one document in that status",
"schema": {
"type": "string"
}
},
{
"name": "sort_by",
"in": "query",
"required": false,
"description": "Rules: in: name, created_at, updated_at, articles_count (falls back to name)",
"schema": {
"type": "string",
"default": "name"
}
},
{
"name": "sort_dir",
"in": "query",
"required": false,
"description": "Rules: anything other than desc (case-insensitive) is treated as asc",
"schema": {
"type": "string",
"default": "asc"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"owner_user_id": 42,
"created_by": 42,
"name": "My Library",
"description": null,
"audience": "assistant",
"created_at": "2026-06-01T14:22:03.000000Z",
"updated_at": "2026-07-15T09:10:44.000000Z",
"articles_count": 5,
"assignments_count": 3,
"creator": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"owner": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
}
}
],
"meta": {
"can_set_kb_audience": false,
"default_knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"single_owned_library": true,
"can_filter_by_owner": false,
"owners": []
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature knowledge_docs not enabled for the account"
}
}
},
"post": {
"operationId": "knowledge-docs-create-library",
"summary": "Create a library",
"tags": [
"Knowledge Docs"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Library name. Rules: required|string|max:255"
},
"description": {
"type": "string",
"nullable": true,
"description": "Rules: nullable|string|max:5000"
},
"audience": {
"type": "string",
"nullable": true,
"description": "Super admins only — chooses builder (feeds the AI-chat/build flows) vs assistant (feeds voice assistants). Ignored for everyone else, who always get assistant. Defaults to assistant when omitted. Rules: nullable|string|in:builder,assistant"
}
},
"required": [
"name"
]
},
"example": {
"name": "Product FAQs",
"description": "Customer-facing answers for the support line."
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"owner_user_id": 42,
"created_by": 42,
"name": "Product FAQs",
"description": "Customer-facing answers for the support line.",
"audience": "assistant",
"created_at": "2026-07-30T14:22:03.000000Z",
"updated_at": "2026-07-30T14:22:03.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"422": {
"description": "Caller (non–super-admin) already owns a library"
}
}
}
},
"/api/v1/kb/knowledge-bases/{knowledge_base}": {
"delete": {
"operationId": "knowledge-docs-delete-library",
"summary": "Delete a library and every document in it",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Deleted"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Library not found"
}
}
}
},
"/api/v1/kb/knowledge-bases/ensure-default": {
"post": {
"operationId": "knowledge-docs-ensure-default-library",
"summary": "Resolve or provision a usable library for an assistant, without visiting Knowledge Docs first",
"tags": [
"Knowledge Docs"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"assistant_id": {
"type": "integer",
"description": "The assistant the caller is about to attach documents to. Rules: required|integer|exists:assistants,id"
}
},
"required": [
"assistant_id"
]
},
"example": {
"assistant_id": 12
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"owner_user_id": 42,
"created_by": 42,
"name": "My Library",
"description": null,
"audience": "assistant",
"created_at": "2026-06-01T14:22:03.000000Z",
"updated_at": "2026-06-01T14:22:03.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Assistant belongs to a different organization"
},
"422": {
"description": "No library could be created or resolved"
}
}
}
},
"/api/v1/kb/knowledge-bases/{knowledge_base}/articles": {
"get": {
"operationId": "knowledge-docs-list-documents",
"summary": "List documents in a library (summary projection)",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"title": "Return Policy",
"status": "published",
"sync_status": "synced",
"char_count": 73,
"updated_at": "2026-07-30T14:35:19.000000Z",
"shared_user_count": 2
},
{
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"title": "Shipping FAQ",
"status": "draft",
"sync_status": "pending",
"char_count": 0,
"updated_at": "2026-07-29T10:02:11.000000Z",
"shared_user_count": 0
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Library not found"
}
}
},
"post": {
"operationId": "knowledge-docs-create-document",
"summary": "Create a document in a library",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Rules: required|string|max:255"
},
"content": {
"type": "string",
"description": "Rich HTML content. No length limit — stored in a longtext column. Rules: required|string"
},
"status": {
"type": "string",
"nullable": true,
"description": "Defaults to draft. archived is not settable at creation. Rules: nullable|in:draft,published"
}
},
"required": [
"title",
"content"
]
},
"example": {
"title": "Return Policy",
"content": "Returns
Items can be returned within 30 days of purchase with a receipt.
",
"status": "published"
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"title": "Return Policy",
"content": "Returns
Items can be returned within 30 days of purchase with a receipt.
",
"plain_text": "Returns Items can be returned within 30 days of purchase with a receipt.",
"structured_text": "\n\n## Returns\n\nItems can be returned within 30 days of purchase with a receipt.",
"content_hash": "3f9c2a106b4e4a2d9f0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5",
"embedded_content_hash": "3f9c2a106b4e4a2d9f0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5",
"status": "published",
"char_count": 73,
"chunk_count": 1,
"sync_status": "synced",
"sync_error": null,
"last_synced_at": "2026-07-30T14:22:04.000000Z",
"created_at": "2026-07-30T14:22:03.000000Z",
"updated_at": "2026-07-30T14:22:04.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Library not found"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}": {
"get": {
"operationId": "knowledge-docs-get-document",
"summary": "Retrieve one document (full content)",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
},
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"title": "Return Policy",
"content": "Returns
Items can be returned within 30 days of purchase with a receipt.
",
"plain_text": "Returns Items can be returned within 30 days of purchase with a receipt.",
"structured_text": "\n\n## Returns\n\nItems can be returned within 30 days of purchase with a receipt.",
"content_hash": "3f9c2a106b4e4a2d9f0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5",
"embedded_content_hash": "3f9c2a106b4e4a2d9f0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5",
"status": "published",
"char_count": 73,
"chunk_count": 1,
"sync_status": "synced",
"sync_error": null,
"last_synced_at": "2026-07-30T14:22:04.000000Z",
"created_at": "2026-07-30T14:22:03.000000Z",
"updated_at": "2026-07-30T14:22:04.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Library not found"
}
}
},
"put": {
"operationId": "knowledge-docs-update-document",
"summary": "Update a document",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
},
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Rules: sometimes|string|max:255"
},
"content": {
"type": "string",
"description": "No length limit — stored in a longtext column. Rules: sometimes|string"
},
"status": {
"type": "string",
"description": "Rules: sometimes|in:draft,published,archived"
}
}
},
"example": {
"content": "Returns
Items can be returned within 60 days of purchase with a receipt.
",
"status": "published"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"title": "Return Policy",
"content": "Returns
Items can be returned within 60 days of purchase with a receipt.
",
"plain_text": "Returns Items can be returned within 60 days of purchase with a receipt.",
"structured_text": "\n\n## Returns\n\nItems can be returned within 60 days of purchase with a receipt.",
"content_hash": "9a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
"embedded_content_hash": "9a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
"status": "published",
"char_count": 73,
"chunk_count": 1,
"sync_status": "synced",
"sync_error": null,
"last_synced_at": "2026-07-30T14:40:52.000000Z",
"created_at": "2026-07-30T14:22:03.000000Z",
"updated_at": "2026-07-30T14:40:52.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Library not found"
},
"422": {
"description": "Validation failed"
}
}
},
"delete": {
"operationId": "knowledge-docs-delete-document",
"summary": "Delete a document",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
},
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Article deleted"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Library not found"
},
"500": {
"description": "Removal from search indexes failed — the document is kept, not deleted"
}
}
}
},
"/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}/sync": {
"post": {
"operationId": "knowledge-docs-sync-document",
"summary": "Force an immediate re-sync of a published document to search",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
},
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Document synced to search.",
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"title": "Return Policy",
"content": "Returns
Items can be returned within 30 days of purchase with a receipt.
",
"plain_text": "Returns Items can be returned within 30 days of purchase with a receipt.",
"structured_text": "\n\n## Returns\n\nItems can be returned within 30 days of purchase with a receipt.",
"content_hash": "3f9c2a106b4e4a2d9f0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5",
"embedded_content_hash": "3f9c2a106b4e4a2d9f0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5",
"status": "published",
"char_count": 73,
"chunk_count": 1,
"sync_status": "synced",
"sync_error": null,
"last_synced_at": "2026-07-30T14:45:10.000000Z",
"created_at": "2026-07-30T14:22:03.000000Z",
"updated_at": "2026-07-30T14:45:10.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Library not found"
},
"422": {
"description": "Document is not published"
},
"500": {
"description": "Sync failed"
}
}
}
},
"/api/v1/kb/article-assign": {
"post": {
"operationId": "knowledge-docs-assign-documents",
"summary": "Assign one or more published documents to one or more assistants",
"tags": [
"Knowledge Docs"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"knowledge_article_id": {
"type": "string",
"description": "Single-document form. One of knowledge_article_id / knowledge_article_ids is required. Rules: sometimes|uuid|exists:knowledge_articles,id"
},
"knowledge_article_ids": {
"type": "array",
"items": [],
"description": "Multi-document form. Rules: sometimes|array|min:1"
},
"knowledge_article_ids.*": {
"type": "string",
"description": "Rules: uuid|exists:knowledge_articles,id"
},
"assistant_id": {
"type": "integer",
"description": "Single-assistant form. One of assistant_id / assistant_ids is required. Rules: sometimes|integer|exists:assistants,id"
},
"assistant_ids": {
"type": "array",
"items": [],
"description": "Multi-assistant form. Rules: sometimes|array|min:1"
},
"assistant_ids.*": {
"type": "integer",
"description": "Rules: integer|exists:assistants,id"
}
}
},
"example": {
"knowledge_article_ids": [
"b2c3d4e5-f6a7-8901-bcde-f23456789012"
],
"assistant_ids": [
12
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "d4e5f6a7-b8c9-0123-defa-456789012345",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"assistant_id": 12,
"knowledge_article_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"created_at": "2026-07-30T14:50:00.000000Z",
"updated_at": "2026-07-30T14:50:00.000000Z"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Assistant belongs to a different organization"
},
"404": {
"description": "Document not found, or it does not belong to that library"
},
"422": {
"description": "Neither document field supplied"
}
}
}
},
"/api/v1/kb/article-assign/{id}": {
"delete": {
"operationId": "knowledge-docs-unassign-document",
"summary": "Remove one assignment",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The assignment to remove (not the document or assistant id).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Unassigned"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Assignment not found"
}
}
}
},
"/api/v1/kb/knowledge-bases/{knowledge_base}/assignments": {
"get": {
"operationId": "knowledge-docs-library-assignments",
"summary": "List every assignment for documents in a library, across all assistants",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "d4e5f6a7-b8c9-0123-defa-456789012345",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"assistant_id": 12,
"knowledge_article_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"created_at": "2026-07-30T14:50:00.000000Z",
"updated_at": "2026-07-30T14:50:00.000000Z",
"assistant": {
"id": 12,
"name": "Front Desk",
"vapi_assistant_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
"phone_number": "+14155551234"
},
"knowledge_article": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"title": "Return Policy",
"status": "published",
"knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Library not found"
}
}
}
},
"/api/v1/kb/assistant/{assistantId}": {
"get": {
"operationId": "knowledge-docs-assistant-documents",
"summary": "List documents linked to an assistant (for the assistant editor)",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "assistantId",
"in": "path",
"required": true,
"description": "The assistant.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "d4e5f6a7-b8c9-0123-defa-456789012345",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"assistant_id": 12,
"knowledge_article_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"created_at": "2026-07-30T14:50:00.000000Z",
"updated_at": "2026-07-30T14:50:00.000000Z",
"knowledge_article": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"title": "Return Policy",
"status": "published",
"knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"char_count": 73,
"updated_at": "2026-07-30T14:35:19.000000Z",
"knowledge_base": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "My Library",
"description": null,
"audience": "assistant",
"reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
"owner_user_id": 42,
"created_by": 42
}
}
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Assistant belongs to a different organization"
}
}
}
},
"/api/v1/kb/assistant/{assistantId}/assignable-articles": {
"get": {
"operationId": "knowledge-docs-assistant-assignable-documents",
"summary": "Search published documents the caller could still attach to an assistant",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "assistantId",
"in": "path",
"required": true,
"description": "The assistant.",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"required": false,
"description": "Title contains-filter. Rules: nullable|string|max:200",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Shipping FAQ",
"status": "published",
"updated_at": "2026-07-29T10:02:11.000000Z",
"char_count": 210
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Assistant belongs to a different organization, or not owned by the caller (non-admin)"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}/share": {
"get": {
"operationId": "knowledge-docs-document-share-recipients",
"summary": "Get who a document is shared with, and who has a pending invite",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
},
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"shared": [
{
"id": 7,
"name": "John Doe",
"email": "john@example.com",
"can_view": true,
"can_edit": false
}
],
"pending": [
{
"email": "newhire@example.com",
"can_view": true,
"can_edit": false
}
]
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Document not found, or it does not belong to that library"
}
}
}
},
"/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}/share/invite": {
"post": {
"operationId": "knowledge-docs-document-share-invite",
"summary": "Share a document with one email address",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
},
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Recipient email — there is no picker of existing users. Rules: required|string|email|max:255"
},
"can_view": {
"type": "boolean",
"description": "Optional — not required or nullable, but must be boolean when present. Rules: boolean"
},
"can_edit": {
"type": "boolean",
"description": "Optional — not required or nullable, but must be boolean when present. Rules: boolean"
}
},
"required": [
"email"
]
},
"example": {
"email": "john@example.com",
"can_view": true,
"can_edit": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Document shared — they've been emailed a link.",
"data": {
"status": "shared",
"shared": {
"id": 7,
"name": "John Doe",
"email": "john@example.com",
"can_view": true,
"can_edit": false
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Document not found, or it does not belong to that library"
},
"422": {
"description": "Email belongs to the library owner already"
}
}
}
},
"/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}/share/permission": {
"post": {
"operationId": "knowledge-docs-document-share-permission",
"summary": "Change a recipient's Read/Write permission",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
},
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Recipient email — there is no picker of existing users. Rules: required|string|email|max:255"
},
"can_view": {
"type": "boolean",
"description": "Optional — not required or nullable, but must be boolean when present. Rules: boolean"
},
"can_edit": {
"type": "boolean",
"description": "Optional — not required or nullable, but must be boolean when present. Rules: boolean"
}
},
"required": [
"email"
]
},
"example": {
"email": "john@example.com",
"can_view": true,
"can_edit": true
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Permission updated."
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Document not found, or it does not belong to that library"
},
"422": {
"description": "Invalid email"
}
}
}
},
"/api/v1/kb/knowledge-bases/{knowledge_base}/articles/{article}/share/remove": {
"post": {
"operationId": "knowledge-docs-document-share-remove",
"summary": "Remove one recipient's access",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "knowledge_base",
"in": "path",
"required": true,
"description": "The library.",
"schema": {
"type": "string"
}
},
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Recipient email — there is no picker of existing users. Rules: required|string|email|max:255"
}
},
"required": [
"email"
]
},
"example": {
"email": "john@example.com"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Access removed."
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
},
"404": {
"description": "Document not found, or it does not belong to that library"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/v1/kb/shared-with-me": {
"get": {
"operationId": "knowledge-docs-shared-with-me-list",
"summary": "List documents other people have shared with the current user",
"tags": [
"Knowledge Docs"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Return Policy",
"status": "published",
"char_count": 73,
"updated_at": "2026-07-30T14:35:19.000000Z",
"shared_at": "2026-07-30T15:00:00.000000Z",
"can_view": true,
"can_edit": false,
"shared_by": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"knowledge_base": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "My Library"
}
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Policy denied — outside your organization, or you cannot write to this resource"
}
}
}
},
"/api/v1/kb/shared-with-me/{article}": {
"get": {
"operationId": "knowledge-docs-shared-with-me-show",
"summary": "Open a document shared with the current user",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Return Policy",
"content": "Returns
Items can be returned within 30 days of purchase with a receipt.
",
"status": "published",
"updated_at": "2026-07-30T14:35:19.000000Z",
"can_view": true,
"can_edit": false,
"shared_by": {
"id": 42,
"name": "Jane Cooper",
"email": "jane@example.com"
},
"knowledge_base": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "My Library"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Not shared with the caller (and they cannot otherwise view it)"
},
"404": {
"description": "Document not found, or it does not belong to that library"
}
}
},
"put": {
"operationId": "knowledge-docs-shared-with-me-update",
"summary": "Edit a document shared with the current user (title/content only)",
"tags": [
"Knowledge Docs"
],
"parameters": [
{
"name": "article",
"in": "path",
"required": true,
"description": "The document.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Rules: sometimes|string|max:255"
},
"content": {
"type": "string",
"description": "Rules: sometimes|string"
}
}
},
"example": {
"content": "Returns
Items can be returned within 45 days of purchase with a receipt.
"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Document updated.",
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"title": "Return Policy",
"content": "Returns
Items can be returned within 45 days of purchase with a receipt.
",
"status": "published",
"updated_at": "2026-07-30T15:05:33.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "No write access — view-only share, or not shared at all"
},
"404": {
"description": "Document not found, or it does not belong to that library"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/v1/chat/completions": {
"post": {
"operationId": "agents-chat-completions",
"summary": "Send a chat-completions request to an agent",
"tags": [
"Agents"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"model": {
"type": "string",
"nullable": true,
"description": "Model id from GET /models. Omit for the default. Rules: sometimes|nullable|string|max:255"
},
"messages": {
"type": "array",
"items": [],
"description": "Conversation turns. Must contain at least one user-role message. Rules: required|array|min:1"
},
"messages.*.role": {
"type": "string",
"description": "Turn role. Rules: required|string|in:system,user,assistant"
},
"messages.*.content": {
"type": "string",
"description": "Turn text, max 20,000 characters. Rules: required|string|max:20000"
},
"agent": {
"type": "string",
"nullable": true,
"description": "Sulus extension: which agent answers. Defaults to your most recently active agent. Rules: sometimes|nullable|string|max:64"
},
"chat": {
"type": "string",
"nullable": true,
"description": "Sulus extension: continue this existing thread statefully. Rules: sometimes|nullable|string|max:64"
},
"stream": {
"type": "boolean",
"description": "Must be false or omitted — streaming is not supported. Rules: sometimes|boolean"
}
},
"required": [
"messages",
"messages.*.role",
"messages.*.content"
]
},
"example": {
"model": "sulus-chat-1",
"messages": [
{
"role": "system",
"content": "You are speaking with a returning customer."
},
{
"role": "user",
"content": "What are your opening hours?"
}
],
"agent": "a1b2c3d4-0000-4000-8000-000000000001",
"chat": "b2c3d4e5-0000-4000-8000-000000000002",
"stream": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"id": "chatcmpl-7f3a9c2e-1111-4222-8333-000000000010",
"object": "chat.completion",
"created": 1769800000,
"model": "sulus-chat-1",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "We're open Monday to Friday, 9am to 6pm Eastern, and Saturday 10am to 2pm."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 210,
"completion_tokens": 88,
"total_tokens": 298
},
"sulus": {
"agent": "a1b2c3d4-0000-4000-8000-000000000001",
"chat": "b2c3d4e5-0000-4000-8000-000000000002",
"tools_used": []
}
}
}
}
},
"400": {
"description": "invalid_request_error — streaming requested, or no user-role message"
},
"401": {
"description": "Missing or invalid bearer token"
},
"402": {
"description": "insufficient_quota — prepaid token balance exhausted"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "invalid_request_error — agent or chat not found"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "api_error — the assistant could not generate a response"
}
}
}
},
"/api/v1/models": {
"get": {
"operationId": "agents-list-models",
"summary": "List available model ids",
"tags": [
"Agents"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "list",
"data": [
{
"id": "sulus-chat-1",
"object": "model",
"owned_by": "sulus",
"label": "Sulus Chat 1",
"available": true
},
{
"id": "sulus-chat-2",
"object": "model",
"owned_by": "sulus",
"label": "Sulus Chat 2",
"available": true
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
}
}
}
},
"/api/v1/usage": {
"get": {
"operationId": "agents-get-usage",
"summary": "Prepaid-USD balance and account counts",
"tags": [
"Agents"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "usage",
"billing_active": true,
"balance_tokens": 1250000,
"balance_usd": 6.25,
"agents": 4,
"chats": 31
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
}
}
}
},
"/api/v1/agents": {
"get": {
"operationId": "agents-list-agents",
"summary": "List agents you can access",
"tags": [
"Agents"
],
"parameters": [
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Items per page. Rules: integer, clamped 1–100",
"schema": {
"type": "integer",
"default": 50
}
},
{
"name": "q",
"in": "query",
"required": false,
"description": "Search filter. Rules: string (name/description contains-filter)",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "Sort order. Rules: in: updated, name",
"schema": {
"type": "string",
"default": "updated"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "list",
"data": [
{
"id": "a1b2c3d4-0000-4000-8000-000000000001",
"object": "agent",
"name": "Support Agent",
"description": "Answers customer support questions.",
"instructions": "Be concise and friendly.",
"memory": "The customer prefers email follow-ups over phone calls.",
"created_at": "2026-06-01T14:32:07.000000Z",
"last_activity_at": "2026-07-29T09:15:44.000000Z"
},
{
"id": "c9d8e7f6-0000-4000-8000-000000000009",
"object": "agent",
"name": "Sales Agent",
"description": null,
"instructions": null,
"memory": null,
"created_at": "2026-07-10T08:00:00.000000Z",
"last_activity_at": null
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
}
}
},
"post": {
"operationId": "agents-create-agent",
"summary": "Create an agent",
"tags": [
"Agents"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Agent display name. Rules: required|string|max:255"
},
"description": {
"type": "string",
"nullable": true,
"description": "What the agent is for. Rules: sometimes|nullable|string|max:5000"
},
"instructions": {
"type": "string",
"nullable": true,
"description": "Persistent system prompt. Rules: sometimes|nullable|string|max:10000"
}
},
"required": [
"name"
]
},
"example": {
"name": "Support Agent",
"description": "Answers customer support questions.",
"instructions": "Be concise and friendly."
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "agent",
"data": {
"id": "a1b2c3d4-0000-4000-8000-000000000001",
"object": "agent",
"name": "Support Agent",
"description": "Answers customer support questions.",
"instructions": "Be concise and friendly.",
"memory": null,
"created_at": "2026-07-30T14:12:03.000000Z",
"last_activity_at": "2026-07-30T14:12:03.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/v1/agents/{agent_id}": {
"get": {
"operationId": "agents-get-agent",
"summary": "Retrieve one agent",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "agent",
"data": {
"id": "a1b2c3d4-0000-4000-8000-000000000001",
"object": "agent",
"name": "Support Agent",
"description": "Answers customer support questions.",
"instructions": "Be concise and friendly.",
"memory": "The customer prefers email follow-ups over phone calls.",
"created_at": "2026-06-01T14:32:07.000000Z",
"last_activity_at": "2026-07-29T09:15:44.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
}
}
},
"patch": {
"operationId": "agents-update-agent",
"summary": "Update an agent (PUT also accepted)",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "New name. When present it must not be empty. Rules: sometimes|required|string|max:255"
},
"description": {
"type": "string",
"nullable": true,
"description": "New description; null clears it. Rules: sometimes|nullable|string|max:5000"
},
"instructions": {
"type": "string",
"nullable": true,
"description": "New instructions; null clears them. Rules: sometimes|nullable|string|max:10000"
}
}
},
"example": {
"name": "Support Agent",
"description": "Handles pre-sales questions too.",
"instructions": "Be concise, friendly, and offer to connect the caller with a specialist for pricing."
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "agent",
"data": {
"id": "a1b2c3d4-0000-4000-8000-000000000001",
"object": "agent",
"name": "Support Agent",
"description": "Handles pre-sales questions too.",
"instructions": "Be concise, friendly, and offer to connect the caller with a specialist for pricing.",
"memory": "The customer prefers email follow-ups over phone calls.",
"created_at": "2026-06-01T14:32:07.000000Z",
"last_activity_at": "2026-07-29T09:15:44.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
},
"422": {
"description": "Validation failed"
}
}
},
"delete": {
"operationId": "agents-delete-agent",
"summary": "Delete an agent and everything in it",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "agent.deleted",
"id": "a1b2c3d4-0000-4000-8000-000000000001",
"deleted": true
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you are not its owner (delete requires ownership, not just write access)"
}
}
}
},
"/api/v1/agents/{agent_id}/chats": {
"get": {
"operationId": "agents-list-chats",
"summary": "List your chats in an agent",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "list",
"data": [
{
"id": "b2c3d4e5-0000-4000-8000-000000000002",
"object": "chat",
"title": "Pricing questions",
"model": "sulus-chat-1",
"provider": "sulus-primary",
"last_message_at": "2026-07-30T14:20:11.000000Z",
"created_at": "2026-07-30T14:12:40.000000Z"
},
{
"id": "d4e5f6a7-0000-4000-8000-000000000003",
"object": "chat",
"title": "New chat",
"model": null,
"provider": "sulus-primary",
"last_message_at": null,
"created_at": "2026-07-30T15:01:02.000000Z"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
}
}
},
"post": {
"operationId": "agents-create-chat",
"summary": "Start a new chat thread",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"model": {
"type": "string",
"nullable": true,
"description": "Model id for this thread; omit for the default. Rules: sometimes|nullable|string|max:255"
}
}
},
"example": {
"model": "sulus-chat-1"
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "chat",
"data": {
"id": "b2c3d4e5-0000-4000-8000-000000000002",
"object": "chat",
"title": "New chat",
"model": "sulus-chat-1",
"provider": "sulus-primary",
"last_message_at": null,
"created_at": "2026-07-30T14:12:40.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"402": {
"description": "Out of prepaid USD — blocked before the thread is created"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/v1/agents/{agent_id}/chats/{chat_id}": {
"get": {
"operationId": "agents-get-chat",
"summary": "Retrieve one chat",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "chat_id",
"in": "path",
"required": true,
"description": "The chat id (UUID).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "chat",
"data": {
"id": "b2c3d4e5-0000-4000-8000-000000000002",
"object": "chat",
"title": "Pricing questions",
"model": "sulus-chat-1",
"provider": "sulus-primary",
"last_message_at": "2026-07-30T14:20:11.000000Z",
"created_at": "2026-07-30T14:12:40.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
}
}
},
"patch": {
"operationId": "agents-rename-chat",
"summary": "Rename a chat (PUT also accepted)",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "chat_id",
"in": "path",
"required": true,
"description": "The chat id (UUID).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "New chat title. Rules: required|string|max:255"
}
},
"required": [
"title"
]
},
"example": {
"title": "Pricing questions"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "chat",
"data": {
"id": "b2c3d4e5-0000-4000-8000-000000000002",
"object": "chat",
"title": "Pricing questions",
"model": "sulus-chat-1",
"provider": "sulus-primary",
"last_message_at": "2026-07-30T14:20:11.000000Z",
"created_at": "2026-07-30T14:12:40.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
},
"422": {
"description": "Validation failed"
}
}
},
"delete": {
"operationId": "agents-delete-chat",
"summary": "Delete a chat and its messages",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "chat_id",
"in": "path",
"required": true,
"description": "The chat id (UUID).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "chat.deleted",
"id": "b2c3d4e5-0000-4000-8000-000000000002",
"deleted": true
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
}
}
}
},
"/api/v1/agents/{agent_id}/chats/{chat_id}/messages": {
"get": {
"operationId": "agents-list-messages",
"summary": "List messages (oldest first)",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "chat_id",
"in": "path",
"required": true,
"description": "The chat id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Messages per page. Rules: integer, clamped 1–100",
"schema": {
"type": "integer",
"default": 30
}
},
{
"name": "before_id",
"in": "query",
"required": false,
"description": "Cursor for older pages: pass the id of the first message from the previous response. Rules: integer — fetch messages with id < before_id",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "list",
"data": [
{
"id": 9001,
"object": "message",
"role": "user",
"content": "Summarise our refund policy.",
"model": null,
"created_at": "2026-07-30T14:19:58.000000Z"
},
{
"id": 9002,
"object": "message",
"role": "assistant",
"content": "Refunds are available within 30 days of purchase, provided the item is unused.",
"model": "sulus-chat-1",
"created_at": "2026-07-30T14:20:11.000000Z"
}
],
"has_more": false
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
}
}
},
"post": {
"operationId": "agents-send-message",
"summary": "Send a message and get the assistant reply",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "chat_id",
"in": "path",
"required": true,
"description": "The chat id (UUID).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "Your message, max 20,000 characters. Rules: required|string|max:20000"
},
"model": {
"type": "string",
"nullable": true,
"description": "Override the thread model for this turn. Rules: sometimes|nullable|string|max:255"
}
},
"required": [
"content"
]
},
"example": {
"content": "Summarise our refund policy.",
"model": "sulus-chat-1"
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "message",
"data": {
"user_message": {
"id": 9001,
"object": "message",
"role": "user",
"content": "Summarise our refund policy.",
"model": null,
"created_at": "2026-07-30T14:19:58.000000Z"
},
"assistant_message": {
"id": 9002,
"object": "message",
"role": "assistant",
"content": "Refunds are available within 30 days of purchase, provided the item is unused.",
"model": "sulus-chat-1",
"created_at": "2026-07-30T14:20:11.000000Z",
"usage": {
"prompt_tokens": 210,
"completion_tokens": 88,
"total_tokens": 298
}
}
},
"model": "sulus-chat-1",
"tools_used": [],
"wallet": {
"usd_cost": 0.0149,
"balance_tokens": 1249702,
"balance_usd": 6.2485,
"payer_user_id": 501
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"402": {
"description": "Out of prepaid USD"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/v1/agents/{agent_id}/files": {
"get": {
"operationId": "agents-list-files",
"summary": "List an agent's knowledge files",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "list",
"data": [
{
"id": 51,
"project_id": 7,
"original_name": "faq.md",
"mime": "text/markdown",
"size": 6120,
"created_at": "2026-07-28T10:05:22.000000Z",
"extractable": true,
"vector_count": 12,
"indexed": true,
"url": "/storage/ai-projects/7/files/9f8e7d6c-0000-4000-8000-000000000020.md",
"preview_kind": "text"
},
{
"id": 52,
"project_id": 7,
"original_name": "pricing-sheet.pdf",
"mime": "application/pdf",
"size": 184320,
"created_at": "2026-07-29T16:41:09.000000Z",
"extractable": false,
"vector_count": 0,
"indexed": false,
"url": "/storage/ai-projects/7/files/a1b0c9d8-0000-4000-8000-000000000021.pdf",
"preview_kind": "pdf"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
}
}
},
"post": {
"operationId": "agents-upload-file",
"summary": "Upload a knowledge file (multipart)",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "file",
"data": {
"id": 51,
"project_id": 7,
"original_name": "faq.md",
"mime": "text/markdown",
"size": 6120,
"created_at": "2026-07-30T14:25:03.000000Z",
"extractable": true,
"extracted": true,
"indexed": true
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
},
"422": {
"description": "Disallowed extension"
}
}
}
},
"/api/v1/agents/{agent_id}/files/{file_id}": {
"delete": {
"operationId": "agents-delete-file",
"summary": "Delete a knowledge file",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "file_id",
"in": "path",
"required": true,
"description": "The file id from the list response.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "file.deleted",
"id": 51,
"deleted": true
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ai_chat not enabled for the account"
},
"404": {
"description": "Agent not found, or you do not have access to it"
}
}
}
},
"/api/v1/agents/{agent_id}/connectors": {
"get": {
"operationId": "agents-list-connectors",
"summary": "List connectors available to an agent",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"object": "list",
"data": [
{
"uid": "c3d4e5f6-0000-4000-8000-000000000030",
"name": "Docs search",
"description": "Searches the internal knowledge base and returns matching articles.",
"purpose": "Answer product questions from the knowledge base.",
"use_case": "When a caller asks how a feature works.",
"connector_description": "Searches the internal knowledge base and returns matching articles.",
"connector_purpose": "Answer product questions from the knowledge base.",
"connector_use_case": "When a caller asks how a feature works.",
"context_overridden": false,
"server_key": "docs-search",
"server_url": "https://connectors.example.com/docs-search/mcp",
"ghl_location_id": null,
"enabled": true,
"tools_count": 2,
"tools": [
{
"name": "search-docs",
"description": "Full-text search over indexed documentation.",
"enabled": true
},
{
"name": "get-doc",
"description": "Fetch a single document by id.",
"enabled": false
}
],
"reachable": true
},
{
"uid": "d4e5f6a7-0000-4000-8000-000000000031",
"name": "Order lookup",
"description": "Looks up order status by order number or customer email.",
"purpose": null,
"use_case": null,
"connector_description": "Looks up order status by order number or customer email.",
"connector_purpose": null,
"connector_use_case": null,
"context_overridden": false,
"server_key": "orders",
"server_url": "https://connectors.example.com/orders/mcp",
"ghl_location_id": null,
"enabled": false,
"tools_count": 3,
"tools": []
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "You do not have MCP access to this agent."
},
"404": {
"description": "Agent not found, or you do not have access to it"
}
}
}
},
"/api/v1/agents/{agent_id}/connectors/{connector_id}": {
"put": {
"operationId": "agents-toggle-connector",
"summary": "Enable or disable a connector for this agent",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "connector_id",
"in": "path",
"required": true,
"description": "The connector uid from the list response.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Desired state. Rules: required|boolean"
}
},
"required": [
"enabled"
]
},
"example": {
"enabled": true
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "\"Docs search\" enabled for this agent.",
"data": {
"uid": "c3d4e5f6-0000-4000-8000-000000000030",
"enabled": true
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "You do not have MCP access to this agent."
},
"404": {
"description": "Agent not found, or you do not have access to it"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/v1/agents/{agent_id}/connectors/{connector_id}/tools": {
"put": {
"operationId": "agents-toggle-connector-tool",
"summary": "Switch one tool of an enabled connector on or off",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "connector_id",
"in": "path",
"required": true,
"description": "The connector uid from the list response.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"description": "The tool name as returned in the connector's tools list. Rules: required|string|max:255"
},
"enabled": {
"type": "boolean",
"description": "Desired state. A disabled tool is never offered to the model. Rules: required|boolean"
}
},
"required": [
"tool",
"enabled"
]
},
"example": {
"tool": "search-docs",
"enabled": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Tool \"search-docs\" disabled.",
"data": {
"tool": "search-docs",
"enabled": false
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "You do not have MCP access to this agent."
},
"404": {
"description": "Agent not found, or you do not have access to it"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/v1/agents/{agent_id}/connectors/{connector_id}/context": {
"put": {
"operationId": "agents-update-connector-context",
"summary": "Set per-agent description, purpose, and use case for an enabled connector",
"tags": [
"Agents"
],
"parameters": [
{
"name": "agent_id",
"in": "path",
"required": true,
"description": "The agent id (UUID).",
"schema": {
"type": "string"
}
},
{
"name": "connector_id",
"in": "path",
"required": true,
"description": "The connector uid from the list response.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true,
"description": "Agent overlay. Blank or null inherits the connector description. Rules: sometimes|nullable|string|max:2000"
},
"purpose": {
"type": "string",
"nullable": true,
"description": "Agent overlay. Blank or null inherits the connector purpose. Rules: sometimes|nullable|string|max:2000"
},
"use_case": {
"type": "string",
"nullable": true,
"description": "Agent overlay. Blank or null inherits the connector use case. Rules: sometimes|nullable|string|max:2000"
}
}
},
"example": {
"description": "Use this connector only for this agent's customer lookups.",
"purpose": "Look up the caller in the customer directory before quoting hours.",
"use_case": "When the caller asks about their account or a recent order."
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Connector context updated for this agent.",
"data": {
"uid": "c3d4e5f6-0000-4000-8000-000000000030",
"description": "Use this connector only for this agent's customer lookups.",
"purpose": "Look up the caller in the customer directory before quoting hours.",
"use_case": "When the caller asks about their account or a recent order.",
"connector_description": "Searches the internal knowledge base and returns matching articles.",
"connector_purpose": "Answer product questions from the knowledge base.",
"connector_use_case": "When a caller asks how a feature works.",
"context_overridden": true
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "You do not have MCP access to this agent."
},
"404": {
"description": "Agent not found, or you do not have access to it"
},
"422": {
"description": "Connector is not enabled on this agent"
}
}
}
},
"/api/call-logs/list": {
"get": {
"operationId": "call-history-call-logs-list",
"summary": "List call logs (dashboard default)",
"tags": [
"Call History"
],
"parameters": [
{
"name": "assistant_id",
"in": "query",
"required": false,
"description": "Limit results to one local assistant id.",
"schema": {
"type": "integer"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "When present, filters call_logs.status exactly (the dashboard clears \"all\" client-side before calling).",
"schema": {
"type": "string"
}
},
{
"name": "direction",
"in": "query",
"required": false,
"description": "When present, filters call_logs.direction exactly (the dashboard clears \"all\" client-side before calling).",
"schema": {
"type": "string"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"description": "Inclusive lower bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "end_date",
"in": "query",
"required": false,
"description": "Inclusive upper bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Substring match on call_id and summary (list/index). On /search it is required and also matches transcript.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Page size. Not clamped in this controller.",
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Laravel paginator page number.",
"schema": {
"type": "integer",
"default": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 1842,
"call_id": "call_01hxyz9abcdeFGHIjklmnopq",
"assistant_id": 57,
"phone_number": "+14155550100",
"caller_number": "+14155550199",
"duration": 142,
"status": "completed",
"direction": "inbound",
"start_time": "2026-07-30T14:02:11.000000Z",
"end_time": "2026-07-30T14:04:33.000000Z",
"summary": "Caller asked about return policy; assistant confirmed 30-day window.",
"call_record_file_name": "rec_01hxyz9abcdeFGHIjklmnopq.mp3",
"assistant_name": "Front Desk",
"assistant_phone": "+14155550100",
"has_recording": true,
"public_audio_url": "https://app.example.com/play/rec_01hxyz9abcdeFGHIjklmnopq.mp3",
"public_audio_player_url": "https://app.example.com/p/rec_01hxyz9abcdeFGHIjklmnopq.mp3"
}
],
"meta": {
"current_page": 1,
"last_page": 3,
"per_page": 20,
"total": 47,
"from": 1,
"to": 20
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature call_logs not enabled for the account"
}
}
}
},
"/api/call-logs/search": {
"get": {
"operationId": "call-history-call-logs-search",
"summary": "Full-text search call logs (call id, summary, transcript)",
"tags": [
"Call History"
],
"parameters": [
{
"name": "search",
"in": "query",
"required": true,
"description": "Search term. Matched with LIKE against call_id, summary, and transcript. Rules: required; minimum length 3 (enforced in controller, not FormRequest)",
"schema": {
"type": "string"
}
},
{
"name": "assistant_id",
"in": "query",
"required": false,
"description": "Limit results to one local assistant id.",
"schema": {
"type": "integer"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters call_logs.status.",
"schema": {
"type": "string"
}
},
{
"name": "direction",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters call_logs.direction.",
"schema": {
"type": "string"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"description": "Inclusive lower bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "end_date",
"in": "query",
"required": false,
"description": "Inclusive upper bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Page size. Not clamped in this controller.",
"schema": {
"type": "integer",
"default": 15
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Laravel paginator page number.",
"schema": {
"type": "integer",
"default": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 1842,
"call_id": "call_01hxyz9abcdeFGHIjklmnopq",
"assistant_id": 57,
"phone_number": "+14155550100",
"caller_number": "+14155550199",
"duration": 142,
"status": "completed",
"direction": "inbound",
"start_time": "2026-07-30T14:02:11.000000Z",
"end_time": "2026-07-30T14:04:33.000000Z",
"summary": "Caller asked about return policy; assistant confirmed 30-day window.",
"call_record_file_name": "rec_01hxyz9abcdeFGHIjklmnopq.mp3",
"assistant_name": "Front Desk",
"assistant_phone": "+14155550100",
"has_recording": true,
"public_audio_url": "https://app.example.com/play/rec_01hxyz9abcdeFGHIjklmnopq.mp3",
"public_audio_player_url": "https://app.example.com/p/rec_01hxyz9abcdeFGHIjklmnopq.mp3"
}
],
"meta": {
"current_page": 1,
"last_page": 1,
"per_page": 15,
"total": 2,
"from": 1,
"to": 2
}
}
}
}
},
"400": {
"description": "Missing search or fewer than 3 characters"
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature call_logs not enabled for the account"
}
}
}
},
"/api/call-logs": {
"get": {
"operationId": "call-history-call-logs-index",
"summary": "List call logs (legacy index; includes created_at)",
"tags": [
"Call History"
],
"parameters": [
{
"name": "assistant_id",
"in": "query",
"required": false,
"description": "Limit results to one local assistant id.",
"schema": {
"type": "integer"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters call_logs.status.",
"schema": {
"type": "string"
}
},
{
"name": "direction",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters call_logs.direction.",
"schema": {
"type": "string"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"description": "Inclusive lower bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "end_date",
"in": "query",
"required": false,
"description": "Inclusive upper bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Substring match on call_id and summary (list/index). On /search it is required and also matches transcript.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Page size. Not clamped in this controller.",
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Laravel paginator page number.",
"schema": {
"type": "integer",
"default": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 1842,
"call_id": "call_01hxyz9abcdeFGHIjklmnopq",
"assistant_id": 57,
"phone_number": "+14155550100",
"caller_number": "+14155550199",
"duration": 142,
"status": "completed",
"direction": "inbound",
"start_time": "2026-07-30T14:02:11.000000Z",
"end_time": "2026-07-30T14:04:33.000000Z",
"summary": "Caller asked about return policy; assistant confirmed 30-day window.",
"call_record_file_name": "rec_01hxyz9abcdeFGHIjklmnopq.mp3",
"created_at": "2026-07-30T14:04:40.000000Z",
"assistant_name": "Front Desk",
"assistant_phone": "+14155550100",
"has_recording": true,
"public_audio_url": "https://app.example.com/play/rec_01hxyz9abcdeFGHIjklmnopq.mp3",
"public_audio_player_url": "https://app.example.com/p/rec_01hxyz9abcdeFGHIjklmnopq.mp3"
}
],
"meta": {
"current_page": 1,
"last_page": 3,
"per_page": 20,
"total": 47,
"from": 1,
"to": 20
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature call_logs not enabled for the account"
}
}
}
},
"/api/call-logs/stats": {
"get": {
"operationId": "call-history-call-logs-stats",
"summary": "Aggregate call statistics for the scoped account",
"tags": [
"Call History"
],
"parameters": [
{
"name": "start_date",
"in": "query",
"required": false,
"description": "Inclusive lower bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "end_date",
"in": "query",
"required": false,
"description": "Inclusive upper bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "assistant_id",
"in": "query",
"required": false,
"description": "Limit aggregates to one local assistant id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"totalCalls": 47,
"completedCalls": 39,
"totalDuration": 6120,
"inboundCalls": 40,
"outboundCalls": 7,
"totalCost": 0,
"averageDuration": 130,
"statusBreakdown": {
"completed": 39,
"no-answer": 5,
"failed": 3
},
"assistantPerformance": [
{
"assistant_id": 57,
"total_calls": 30,
"completed_calls": 26,
"avg_duration": 128.4
}
]
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature call_logs not enabled for the account"
}
}
}
},
"/api/call-logs/{callId}": {
"get": {
"operationId": "call-history-call-logs-show",
"summary": "Retrieve one call log and its structured conversation",
"tags": [
"Call History"
],
"parameters": [
{
"name": "callId",
"in": "path",
"required": true,
"description": "Public call identifier (not the numeric primary key).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 1842,
"call_id": "call_01hxyz9abcdeFGHIjklmnopq",
"assistant_id": 57,
"user_id": 12,
"reseller_id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"phone_number": "+14155550100",
"caller_number": "+14155550199",
"duration": 142,
"status": "completed",
"direction": "inbound",
"start_time": "2026-07-30T14:02:11.000000Z",
"end_time": "2026-07-30T14:04:33.000000Z",
"transcript": "Assistant: Thanks for calling. How can I help?\nCustomer: What is your return policy?\nAssistant: You can return items within 30 days with a receipt.",
"summary": "Caller asked about return policy; assistant confirmed 30-day window.",
"call_record_file_name": "rec_01hxyz9abcdeFGHIjklmnopq.mp3",
"created_at": "2026-07-30T14:04:40.000000Z",
"updated_at": "2026-07-30T14:04:40.000000Z",
"has_recording": true,
"public_audio_url": "https://app.example.com/play/rec_01hxyz9abcdeFGHIjklmnopq.mp3",
"public_audio_player_url": "https://app.example.com/p/rec_01hxyz9abcdeFGHIjklmnopq.mp3",
"assistant_name": "Front Desk",
"assistant_phone": "+14155550100"
},
"conversation": {
"conversation": [
{
"id": 1,
"speaker": "Assistant",
"message": "Thanks for calling. How can I help?",
"timestamp": null,
"original_speaker": "Assistant"
},
{
"id": 2,
"speaker": "Customer",
"message": "What is your return policy?",
"timestamp": null,
"original_speaker": "Customer"
},
{
"id": 3,
"speaker": "Assistant",
"message": "You can return items within 30 days with a receipt.",
"timestamp": null,
"original_speaker": "Assistant"
}
],
"total_messages": 3,
"participants": [
"Assistant",
"Customer"
],
"summary": {
"assistant_messages": 2,
"customer_messages": 1
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature call_logs not enabled for the account"
},
"404": {
"description": "No call_id in scope"
}
}
}
},
"/api/squad-call-logs/list": {
"get": {
"operationId": "squad-call-history-squad-call-logs-list",
"summary": "List squad call logs (dashboard default; alias of index)",
"tags": [
"Squad Call History"
],
"parameters": [
{
"name": "squad_id",
"in": "query",
"required": false,
"description": "Filter by local squads.id. Accepted as a query filter only — the numeric squad_id is stripped from every response row.",
"schema": {
"type": "integer"
}
},
{
"name": "assistant_id",
"in": "query",
"required": false,
"description": "Filter by the member assistant that was active at end of call (local assistants.id).",
"schema": {
"type": "integer"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters status.",
"schema": {
"type": "string"
}
},
{
"name": "direction",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters direction.",
"schema": {
"type": "string"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"description": "Inclusive lower bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "end_date",
"in": "query",
"required": false,
"description": "Inclusive upper bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Substring match on call_id and summary (list/index). On /search it is required and also matches transcript.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Page size. Not clamped in this controller.",
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Laravel paginator page number.",
"schema": {
"type": "integer",
"default": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 902,
"call_id": "call_01hsquad9abcdeFGHIjklmnopq",
"assistant_id": 57,
"reseller_id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"phone_number": "+14155550100",
"caller_number": "+14155550199",
"duration": 210,
"status": "completed",
"direction": "inbound",
"start_time": "2026-07-30T15:10:00.000000Z",
"end_time": "2026-07-30T15:13:30.000000Z",
"summary": "Caller transferred from intake to billing specialist; confirmed invoice date.",
"call_record_file_name": "rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"created_at": "2026-07-30T14:04:40.000000Z",
"squad_name": "Frontline Team",
"squad_external_id": "sq_01habcdeFGHIjklmnopqrs",
"assistant_name": "Billing Specialist",
"assistant_phone": "+14155550100",
"has_recording": true,
"public_audio_url": "https://app.example.com/play/rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"public_audio_player_url": "https://app.example.com/p/rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"reseller": {
"id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"domain": "app.example.com"
}
}
],
"meta": {
"current_page": 1,
"last_page": 2,
"per_page": 20,
"total": 28,
"from": 1,
"to": 20
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature squad_call_logs not enabled for the account"
}
}
}
},
"/api/squad-call-logs/search": {
"get": {
"operationId": "squad-call-history-squad-call-logs-search",
"summary": "Full-text search squad call logs (call id, summary, transcript)",
"tags": [
"Squad Call History"
],
"parameters": [
{
"name": "search",
"in": "query",
"required": true,
"description": "Search term. Matched with LIKE against call_id, summary, and transcript. Rules: required; minimum length 3 (enforced in controller, not FormRequest)",
"schema": {
"type": "string"
}
},
{
"name": "squad_id",
"in": "query",
"required": false,
"description": "Filter by local squads.id. Accepted as a query filter only — the numeric squad_id is stripped from every response row.",
"schema": {
"type": "integer"
}
},
{
"name": "assistant_id",
"in": "query",
"required": false,
"description": "Filter by the member assistant that was active at end of call (local assistants.id).",
"schema": {
"type": "integer"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters status.",
"schema": {
"type": "string"
}
},
{
"name": "direction",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters direction.",
"schema": {
"type": "string"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"description": "Inclusive lower bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "end_date",
"in": "query",
"required": false,
"description": "Inclusive upper bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Page size. Not clamped in this controller.",
"schema": {
"type": "integer",
"default": 15
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Laravel paginator page number.",
"schema": {
"type": "integer",
"default": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 902,
"call_id": "call_01hsquad9abcdeFGHIjklmnopq",
"assistant_id": 57,
"reseller_id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"phone_number": "+14155550100",
"caller_number": "+14155550199",
"duration": 210,
"status": "completed",
"direction": "inbound",
"start_time": "2026-07-30T15:10:00.000000Z",
"end_time": "2026-07-30T15:13:30.000000Z",
"summary": "Caller transferred from intake to billing specialist; confirmed invoice date.",
"call_record_file_name": "rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"squad_name": "Frontline Team",
"squad_external_id": "sq_01habcdeFGHIjklmnopqrs",
"assistant_name": "Billing Specialist",
"assistant_phone": "+14155550100",
"has_recording": true,
"public_audio_url": "https://app.example.com/play/rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"public_audio_player_url": "https://app.example.com/p/rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"reseller": {
"id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"domain": "app.example.com"
}
}
],
"meta": {
"current_page": 1,
"last_page": 1,
"per_page": 15,
"total": 1,
"from": 1,
"to": 1
}
}
}
}
},
"400": {
"description": "Missing search or fewer than 3 characters"
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature squad_call_logs not enabled for the account"
}
}
}
},
"/api/squad-call-logs": {
"get": {
"operationId": "squad-call-history-squad-call-logs-index",
"summary": "List squad call logs (same implementation as /list)",
"tags": [
"Squad Call History"
],
"parameters": [
{
"name": "squad_id",
"in": "query",
"required": false,
"description": "Filter by local squads.id. Accepted as a query filter only — the numeric squad_id is stripped from every response row.",
"schema": {
"type": "integer"
}
},
{
"name": "assistant_id",
"in": "query",
"required": false,
"description": "Filter by the member assistant that was active at end of call (local assistants.id).",
"schema": {
"type": "integer"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters status.",
"schema": {
"type": "string"
}
},
{
"name": "direction",
"in": "query",
"required": false,
"description": "When present and not the literal string \"all\", filters direction.",
"schema": {
"type": "string"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"description": "Inclusive lower bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "end_date",
"in": "query",
"required": false,
"description": "Inclusive upper bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Substring match on call_id and summary (list/index). On /search it is required and also matches transcript.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Page size. Not clamped in this controller.",
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Laravel paginator page number.",
"schema": {
"type": "integer",
"default": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 902,
"call_id": "call_01hsquad9abcdeFGHIjklmnopq",
"assistant_id": 57,
"reseller_id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"phone_number": "+14155550100",
"caller_number": "+14155550199",
"duration": 210,
"status": "completed",
"direction": "inbound",
"start_time": "2026-07-30T15:10:00.000000Z",
"end_time": "2026-07-30T15:13:30.000000Z",
"summary": "Caller transferred from intake to billing specialist; confirmed invoice date.",
"call_record_file_name": "rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"created_at": "2026-07-30T14:04:40.000000Z",
"squad_name": "Frontline Team",
"squad_external_id": "sq_01habcdeFGHIjklmnopqrs",
"assistant_name": "Billing Specialist",
"assistant_phone": "+14155550100",
"has_recording": true,
"public_audio_url": "https://app.example.com/play/rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"public_audio_player_url": "https://app.example.com/p/rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"reseller": {
"id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"domain": "app.example.com"
}
}
],
"meta": {
"current_page": 1,
"last_page": 2,
"per_page": 20,
"total": 28,
"from": 1,
"to": 20
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature squad_call_logs not enabled for the account"
}
}
}
},
"/api/squad-call-logs/stats": {
"get": {
"operationId": "squad-call-history-squad-call-logs-stats",
"summary": "Aggregate squad call statistics for the scoped account",
"tags": [
"Squad Call History"
],
"parameters": [
{
"name": "start_date",
"in": "query",
"required": false,
"description": "Inclusive lower bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "end_date",
"in": "query",
"required": false,
"description": "Inclusive upper bound on start_time (date portion).",
"schema": {
"type": "string"
}
},
{
"name": "squad_id",
"in": "query",
"required": false,
"description": "Limit aggregates to one local squad id.",
"schema": {
"type": "integer"
}
},
{
"name": "assistant_id",
"in": "query",
"required": false,
"description": "Limit aggregates to one member assistant id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"totalCalls": 28,
"completedCalls": 22,
"totalDuration": 5040,
"inboundCalls": 24,
"outboundCalls": 4,
"totalCost": 0,
"averageDuration": 180,
"statusBreakdown": {
"completed": 22,
"no-answer": 4,
"failed": 2
},
"squadPerformance": [
{
"squad_id": 3,
"total_calls": 18,
"completed_calls": 15,
"avg_duration": 175.2
}
]
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature squad_call_logs not enabled for the account"
}
}
}
},
"/api/squad-call-logs/{callId}": {
"get": {
"operationId": "squad-call-history-squad-call-logs-show",
"summary": "Retrieve one squad call log and its structured conversation",
"tags": [
"Squad Call History"
],
"parameters": [
{
"name": "callId",
"in": "path",
"required": true,
"description": "Public call identifier (not the numeric primary key).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 902,
"call_id": "call_01hsquad9abcdeFGHIjklmnopq",
"assistant_id": 57,
"user_id": 12,
"reseller_id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"phone_number": "+14155550100",
"caller_number": "+14155550199",
"duration": 210,
"status": "completed",
"direction": "inbound",
"start_time": "2026-07-30T15:10:00.000000Z",
"end_time": "2026-07-30T15:13:30.000000Z",
"transcript": "Assistant: Thanks for calling the frontline team.\nCustomer: I need billing help.\nAssistant: Transferring you now.",
"summary": "Caller transferred from intake to billing specialist; confirmed invoice date.",
"call_record_file_name": "rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"created_at": "2026-07-30T15:13:40.000000Z",
"updated_at": "2026-07-30T15:13:40.000000Z",
"has_recording": true,
"public_audio_url": "https://app.example.com/play/rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"public_audio_player_url": "https://app.example.com/p/rec_01hsquad9abcdeFGHIjklmnopq.mp3",
"squad_name": "Frontline Team",
"squad_external_id": "sq_01habcdeFGHIjklmnopqrs",
"assistant_name": "Billing Specialist",
"assistant_phone": "+14155550100"
},
"conversation": {
"conversation": [
{
"id": 1,
"speaker": "Assistant",
"message": "Thanks for calling the frontline team.",
"timestamp": null,
"original_speaker": "Assistant"
},
{
"id": 2,
"speaker": "Customer",
"message": "I need billing help.",
"timestamp": null,
"original_speaker": "Customer"
},
{
"id": 3,
"speaker": "Assistant",
"message": "Transferring you now.",
"timestamp": null,
"original_speaker": "Assistant"
}
],
"total_messages": 3,
"participants": [
"Assistant",
"Customer"
],
"summary": {
"assistant_messages": 2,
"customer_messages": 1
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature squad_call_logs not enabled for the account"
},
"404": {
"description": "No call_id in scope"
}
}
}
},
"/api/dashboard/stats": {
"get": {
"operationId": "analytics-dashboard-stats",
"summary": "Get the Analytics dashboard overview bundle",
"tags": [
"Analytics"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"overview": {
"total_assistants": 4,
"total_calls": 128,
"calls_today": 3,
"calls_this_month": 41,
"total_minutes": 312.5,
"this_month_minutes": 98.2,
"avg_duration": 146.3
},
"recent_calls": [
{
"id": 1842,
"call_id": "call_01hxyz9abcdeFGHIjklmnopq",
"phone_number": "+14155550100",
"caller_number": "+14155550199",
"duration": 142,
"status": "completed",
"direction": "inbound",
"start_time": "2026-07-30T14:02:11.000000Z",
"end_time": "2026-07-30T14:04:33.000000Z",
"cost": "0.0420",
"assistant_name": "Front Desk",
"assistant_id": 57
}
],
"call_trends": [
{
"date": "2026-07-01",
"count": 5
},
{
"date": "2026-07-02",
"count": 8
},
{
"date": "2026-07-30",
"count": 3
}
],
"top_assistants": [
{
"id": 57,
"vapi_assistant_id": "asst_01habcXYZ123def456ghi789",
"name": "Front Desk",
"phone_number": "+14155550100",
"total_calls": 64,
"type": "inbound",
"status": "active"
}
],
"active_subscriptions": [
{
"id": 19,
"package_name": "Growth",
"package_id": 3,
"status": "active",
"amount": "99.00",
"current_period_start": "2026-07-01T00:00:00.000000Z",
"current_period_end": "2026-08-01T00:00:00.000000Z",
"trial_ends_at": null,
"created_at": "2026-06-15T10:00:00.000000Z"
}
]
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
}
}
}
},
"/api/dashboard/activity": {
"get": {
"operationId": "analytics-dashboard-activity",
"summary": "Get a merged recent-activity feed",
"tags": [
"Analytics"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": "call_1842",
"type": "call",
"title": "Call to +14155550100",
"description": "Call with Front Desk",
"time": "2026-07-30T14:02:11.000000Z",
"status": "completed",
"duration": 142,
"cost": "0.0420"
},
{
"id": "transaction_88",
"type": "transaction",
"title": "Payment Transaction",
"description": "succeeded transaction for 99.00",
"time": "2026-07-29T09:15:00.000000Z",
"status": "succeeded",
"amount": "99.00"
},
{
"id": "assistant_57",
"type": "assistant",
"title": "Assistant Created",
"description": "Created assistant: Front Desk",
"time": "2026-07-20T11:00:00.000000Z",
"assistant_name": "Front Desk"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
}
}
}
},
"/api/partner-end-user/status": {
"get": {
"operationId": "connect-gohighlevel-partner-end-user-status",
"summary": "Get compact connection status for the current user",
"tags": [
"Connect GoHighLevel"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"connected": true,
"ghl_location_id": "loc_abc123XYZ",
"ghl_company_id": "comp_def456",
"token_expires_at": "2026-08-30T14:00:00.000000Z"
}
}
}
}
},
"400": {
"description": "No reseller context on the request"
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ghl_connect not enabled for the account"
}
}
}
},
"/api/partner-end-user/oauth/authorize-url": {
"get": {
"operationId": "connect-gohighlevel-partner-end-user-oauth-url",
"summary": "Build the GoHighLevel OAuth / marketplace installation URL",
"tags": [
"Connect GoHighLevel"
],
"parameters": [
{
"name": "return_to",
"in": "query",
"required": false,
"description": "Path to return to after install (stored in encrypted OAuth state).",
"schema": {
"type": "string",
"default": "/"
}
},
{
"name": "return_origin",
"in": "query",
"required": false,
"description": "Origin override; otherwise derived from the reseller / request host.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"url": "https://marketplace.example.com/oauth/chooselocation?response_type=code&redirect_uri=https%3A%2F%2Fapp.sulus.ai%2Fapi%2Fadmin%2Fpartner-end-user%2Foauth%2Fcallback&state=eyJpdiI6Li4uIn0%3D"
}
}
}
}
},
"400": {
"description": "No reseller context on the request"
},
"403": {
"description": "Feature ghl_connect not enabled for the account"
},
"404": {
"description": "Reseller row missing"
},
"500": {
"description": "Unexpected failure building the URL"
}
}
}
},
"/api/partner-end-user/manual-connect": {
"post": {
"operationId": "connect-gohighlevel-partner-end-user-manual-connect",
"summary": "Manually link a location with an access token (legacy helper)",
"tags": [
"Connect GoHighLevel"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ghl_location_id": {
"type": "string",
"description": "GoHighLevel location id. Rules: required|string|max:64"
},
"ghl_company_id": {
"type": "string",
"nullable": true,
"description": "Optional company id. Rules: nullable|string|max:64"
},
"access_token": {
"type": "string",
"description": "Access token to verify and store. Never returned. Rules: required|string|min:10"
}
},
"required": [
"ghl_location_id",
"access_token"
]
},
"example": {
"ghl_location_id": "loc_abc123XYZ",
"ghl_company_id": "comp_def456",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.exampletokenvalue"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "GoHighLevel connected successfully.",
"data": {
"connected": true,
"ghl_location_id": "loc_abc123XYZ",
"ghl_company_id": "comp_def456",
"token_expires_at": null
}
}
}
}
},
"400": {
"description": "No reseller context on the request"
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ghl_connect not enabled for the account"
},
"404": {
"description": "Reseller row missing"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Persist failed"
}
}
}
},
"/api/partner-end-user/connections": {
"get": {
"operationId": "connect-gohighlevel-partner-end-user-connections-list",
"summary": "List all GoHighLevel connections for the current user",
"tags": [
"Connect GoHighLevel"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"connections": [
{
"id": 12,
"connected": true,
"ghl_location_id": "loc_abc123XYZ",
"location_name": "Downtown Office",
"ghl_company_id": "comp_def456",
"is_default": true,
"token_expires_at": "2026-08-30T14:00:00.000000Z",
"updated_at": "2026-07-30T14:05:00.000000Z"
}
]
}
}
}
}
},
"400": {
"description": "No reseller context on the request"
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ghl_connect not enabled for the account"
},
"404": {
"description": "Reseller row missing"
}
}
},
"post": {
"operationId": "connect-gohighlevel-partner-end-user-connections-create",
"summary": "Add a connection for a location",
"tags": [
"Connect GoHighLevel"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ghl_location_id": {
"type": "string",
"description": "GoHighLevel location id to link. Rules: required|string|max:64"
},
"ghl_company_id": {
"type": "string",
"nullable": true,
"description": "Optional company id for the location. Rules: nullable|string|max:64"
},
"access_token": {
"type": "string",
"description": "Private access token used to verify and store the connection. Never returned in responses. Rules: required|string|min:10"
},
"is_default": {
"type": "boolean",
"nullable": true,
"description": "When true, this location becomes the default for the user. Rules: nullable|boolean"
}
},
"required": [
"ghl_location_id",
"access_token"
]
},
"example": {
"ghl_location_id": "loc_abc123XYZ",
"ghl_company_id": "comp_def456",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.exampletokenvalue",
"is_default": true
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "GoHighLevel connection added.",
"data": {
"connections": [
{
"id": 12,
"connected": true,
"ghl_location_id": "loc_abc123XYZ",
"location_name": "Downtown Office",
"ghl_company_id": "comp_def456",
"is_default": true,
"token_expires_at": "2026-08-30T14:00:00.000000Z",
"updated_at": "2026-07-30T14:05:00.000000Z"
}
]
}
}
}
}
},
"400": {
"description": "No reseller context on the request"
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ghl_connect not enabled for the account"
},
"404": {
"description": "Reseller row missing"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Persist failed"
}
}
}
},
"/api/partner-end-user/connections/{connection}": {
"put": {
"operationId": "connect-gohighlevel-partner-end-user-connections-update",
"summary": "Update a connection you own",
"tags": [
"Connect GoHighLevel"
],
"parameters": [
{
"name": "connection",
"in": "path",
"required": true,
"description": "Connection row id.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ghl_location_id": {
"type": "string",
"description": "GoHighLevel location id to link. Rules: required|string|max:64"
},
"ghl_company_id": {
"type": "string",
"nullable": true,
"description": "Optional company id for the location. Rules: nullable|string|max:64"
},
"access_token": {
"type": "string",
"nullable": true,
"description": "Optional on update — omit or leave blank to keep the stored token. Never returned in responses. Rules: nullable|string|min:10"
},
"is_default": {
"type": "boolean",
"nullable": true,
"description": "When true, this location becomes the default for the user. Rules: nullable|boolean"
}
},
"required": [
"ghl_location_id"
]
},
"example": {
"ghl_location_id": "loc_abc123XYZ",
"ghl_company_id": "comp_def456",
"access_token": null,
"is_default": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "GoHighLevel connection updated.",
"data": {
"connections": [
{
"id": 12,
"connected": true,
"ghl_location_id": "loc_abc123XYZ",
"location_name": "Downtown Office",
"ghl_company_id": "comp_def456",
"is_default": true,
"token_expires_at": "2026-08-30T14:00:00.000000Z",
"updated_at": "2026-07-30T14:05:00.000000Z"
}
]
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ghl_connect not enabled for the account"
},
"404": {
"description": "Connection not owned by caller"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Persist failed"
}
}
},
"delete": {
"operationId": "connect-gohighlevel-partner-end-user-connections-delete",
"summary": "Remove a connection you own",
"tags": [
"Connect GoHighLevel"
],
"parameters": [
{
"name": "connection",
"in": "path",
"required": true,
"description": "Connection row id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "GoHighLevel connection removed.",
"data": {
"connections": []
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ghl_connect not enabled for the account"
},
"404": {
"description": "Connection not owned by caller"
},
"500": {
"description": "Delete failed"
}
}
}
},
"/api/partner-end-user/connections/{connection}/default": {
"post": {
"operationId": "connect-gohighlevel-partner-end-user-connections-default",
"summary": "Mark a connection as the default location",
"tags": [
"Connect GoHighLevel"
],
"parameters": [
{
"name": "connection",
"in": "path",
"required": true,
"description": "Connection row id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Default connection updated.",
"data": {
"connections": [
{
"id": 12,
"connected": true,
"ghl_location_id": "loc_abc123XYZ",
"location_name": "Downtown Office",
"ghl_company_id": "comp_def456",
"is_default": true,
"token_expires_at": "2026-08-30T14:00:00.000000Z",
"updated_at": "2026-07-30T14:05:00.000000Z"
}
]
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature ghl_connect not enabled for the account"
},
"404": {
"description": "Connection not owned by caller"
},
"500": {
"description": "Default update failed"
}
}
}
},
"/api/subscriptions/packages": {
"get": {
"operationId": "billing-subscriptions-packages",
"summary": "List active subscription packages for the reseller",
"tags": [
"Billing"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": [
{
"id": 3,
"reseller_id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"name": "Growth",
"description": "For growing teams",
"price": "99.00",
"yearly_price": "990.00",
"voice_agents_limit": 5,
"monthly_minutes_limit": 1000,
"extra_per_minute_charge": "0.1200",
"features": [
"priority_support",
"call_recordings"
],
"support_level": "priority",
"analytics_level": "advanced",
"is_popular": true,
"is_active": true,
"monthly_payment_link": null,
"yearly_payment_link": null,
"formatted_price": "$99.00",
"formatted_yearly_price": "$990.00",
"formatted_voice_agents_limit": "5",
"formatted_minutes_limit": "1,000",
"formatted_extra_per_minute_charge": "$0.1200"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
}
}
}
},
"/api/subscriptions/current": {
"get": {
"operationId": "billing-subscriptions-current",
"summary": "Get the billing owner's current (or latest) subscription",
"tags": [
"Billing"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 19,
"user_id": 12,
"reseller_id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"subscription_package_id": 3,
"status": "active",
"trial_ends_at": null,
"current_period_start": "2026-07-01T00:00:00.000000Z",
"current_period_end": "2026-08-01T00:00:00.000000Z",
"cancelled_at": null,
"ends_at": null,
"stripe_subscription_id": "sub_1PxExampleSubscriptionId",
"stripe_customer_id": "cus_1PxExampleCustomerId",
"stripe_checkout_session_id": null,
"custom_amount": null,
"billing_interval": "monthly",
"metadata": {
"billing_interval": "monthly"
},
"created_at": "2026-07-01T00:05:00.000000Z",
"updated_at": "2026-07-01T00:05:00.000000Z",
"package": {
"id": 3,
"name": "Growth",
"price": "99.00",
"yearly_price": "990.00",
"formatted_price": "$99.00"
}
},
"billing": {
"source": "self",
"workspace_id": null,
"workspace_name": null,
"can_manage_billing": true
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"404": {
"description": "No subscription rows for the billing owner"
}
}
}
},
"/api/subscriptions/usage": {
"get": {
"operationId": "billing-subscriptions-usage",
"summary": "Get assistant and minute usage for the current billing period",
"tags": [
"Billing"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"has_active_subscription": true,
"assistants": {
"used": 2,
"limit": "5",
"remaining": 3,
"is_unlimited": false
},
"minutes": {
"used": 412.5,
"limit": 1000,
"remaining": 587.5,
"overage_minutes": 0,
"overage_cost": 0,
"extra_per_minute_charge": "0.1200",
"is_unlimited": false,
"billing_period_start": "2026-07-01T00:00:00.000000Z",
"billing_period_end": "2026-08-01T00:00:00.000000Z",
"is_calendar_month_fallback": false,
"interval_type": "monthly",
"subscription_day": null
},
"subscription": {
"status": "active",
"current_period_end": "2026-08-01T00:00:00.000000Z",
"days_remaining": 12
},
"package": {
"name": "Growth",
"price": "$99.00",
"description": "For growing teams",
"extra_per_minute_charge": "$0.1200"
}
},
"billing": {
"source": "self",
"workspace_id": null,
"workspace_name": null,
"can_manage_billing": true
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"404": {
"description": "No active subscription (or reseller missing for reseller_admin path)"
}
}
}
},
"/api/subscriptions/{id}": {
"get": {
"operationId": "billing-subscriptions-show",
"summary": "Get a compact subscription summary by id",
"tags": [
"Billing"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Subscription row id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 19,
"package_name": "Growth",
"amount": "99.00",
"status": "active",
"valid_until": "2026-08-01T00:00:00.000000Z",
"created_at": "2026-07-01T00:05:00.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"404": {
"description": "Unknown or out-of-scope id"
}
}
}
},
"/api/subscriptions/upgrade": {
"post": {
"operationId": "billing-subscriptions-upgrade",
"summary": "Upgrade the active subscription to a higher-priced package",
"tags": [
"Billing"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"package_id": {
"type": "integer",
"description": "Target package; must cost more than the current package. Rules: required|exists:subscription_packages,id"
}
},
"required": [
"package_id"
]
},
"example": {
"package_id": 4
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 19,
"user_id": 12,
"reseller_id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"subscription_package_id": 3,
"status": "active",
"trial_ends_at": null,
"current_period_start": "2026-07-01T00:00:00.000000Z",
"current_period_end": "2026-08-01T00:00:00.000000Z",
"cancelled_at": null,
"ends_at": null,
"stripe_subscription_id": "sub_1PxExampleSubscriptionId",
"stripe_customer_id": "cus_1PxExampleCustomerId",
"stripe_checkout_session_id": null,
"custom_amount": null,
"billing_interval": "monthly",
"metadata": {
"billing_interval": "monthly"
},
"created_at": "2026-07-01T00:05:00.000000Z",
"updated_at": "2026-07-01T00:05:00.000000Z",
"package": {
"id": 3,
"name": "Growth",
"price": "99.00",
"yearly_price": "990.00",
"formatted_price": "$99.00"
}
},
"message": "Subscription upgraded successfully"
}
}
}
},
"400": {
"description": "Target package is not higher priced"
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Package belongs to another reseller"
},
"404": {
"description": "No active subscription"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/subscriptions/cancel": {
"post": {
"operationId": "billing-subscriptions-cancel",
"summary": "Cancel the active subscription locally",
"tags": [
"Billing"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Subscription cancelled successfully"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"404": {
"description": "No active subscription"
}
}
}
},
"/api/subscriptions/subscribe": {
"post": {
"operationId": "billing-subscriptions-subscribe",
"summary": "Create a local active subscription without card checkout",
"tags": [
"Billing"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"package_id": {
"type": "integer",
"description": "Package to activate locally. Rules: required|exists:subscription_packages,id"
}
},
"required": [
"package_id"
]
},
"example": {
"package_id": 3
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 19,
"user_id": 12,
"reseller_id": "9f3c2a10-5b6d-4e8f-9a1b-2c3d4e5f6789",
"subscription_package_id": 3,
"status": "active",
"trial_ends_at": null,
"current_period_start": "2026-07-01T00:00:00.000000Z",
"current_period_end": "2026-08-01T00:00:00.000000Z",
"cancelled_at": null,
"ends_at": null,
"stripe_subscription_id": "sub_1PxExampleSubscriptionId",
"stripe_customer_id": "cus_1PxExampleCustomerId",
"stripe_checkout_session_id": null,
"custom_amount": null,
"billing_interval": "monthly",
"metadata": {
"billing_interval": "monthly"
},
"created_at": "2026-07-01T00:05:00.000000Z",
"updated_at": "2026-07-01T00:05:00.000000Z",
"package": {
"id": 3,
"name": "Growth",
"price": "99.00",
"yearly_price": "990.00",
"formatted_price": "$99.00"
}
},
"message": "Subscription created successfully."
}
}
}
},
"400": {
"description": "User already has an active subscription"
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Package belongs to another reseller"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/stripe/config": {
"get": {
"operationId": "billing-stripe-config",
"summary": "Get the publishable payment key and currency for checkout",
"tags": [
"Billing"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"publishable_key": "pk_test_51ExamplePublishableKey",
"test_mode": true,
"currency": "usd"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
}
}
}
},
"/api/stripe/subscription": {
"post": {
"operationId": "billing-stripe-subscription-create",
"summary": "Create a paid subscription with a payment method",
"tags": [
"Billing"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"package_id": {
"type": "integer",
"description": "Package to subscribe to. Rules: required|exists:subscription_packages,id"
},
"payment_method_id": {
"type": "string",
"description": "Payment method id from the client-side card collection step. Rules: required|string"
},
"billing_interval": {
"type": "string",
"nullable": true,
"description": "Monthly uses package.price; yearly uses package.yearly_price. Rules: nullable|string|in:monthly,yearly"
}
},
"required": [
"package_id",
"payment_method_id"
]
},
"example": {
"package_id": 3,
"payment_method_id": "pm_1PxExamplePaymentMethod",
"billing_interval": "monthly"
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"subscription": {
"id": 19,
"status": "active",
"stripe_subscription_id": "sub_1PxExampleSubscriptionId",
"stripe_customer_id": "cus_1PxExampleCustomerId",
"subscription_package_id": 3,
"package": {
"id": 3,
"name": "Growth",
"price": "99.00"
}
},
"transaction": {
"id": 88,
"amount": "99.00",
"currency": "USD",
"status": "completed",
"payment_method": "stripe",
"type": "subscription",
"external_transaction_id": "sub_1PxExampleSubscriptionId"
},
"stripe_data": {
"subscription_id": "sub_1PxExampleSubscriptionId",
"customer_id": "cus_1PxExampleCustomerId",
"status": "active",
"current_period_start": "2026-07-01T00:00:00.000000Z",
"current_period_end": "2026-08-01T00:00:00.000000Z",
"trial_end": null
}
},
"message": "Subscription created successfully"
}
}
}
},
"400": {
"description": "Upstream payment provider rejected the create"
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Package belongs to another reseller"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/workspaces": {
"get": {
"operationId": "team-workspaces-list",
"summary": "List workspaces the current user belongs to",
"tags": [
"Team"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Jane's Workspace",
"is_personal": true,
"role": "owner",
"member_count": 3,
"owner_has_active_subscription": true,
"owner": {
"id": 12,
"name": "Jane Cooper",
"email": "jane@example.com"
}
}
]
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature workspaces not enabled"
}
}
}
},
"/api/workspaces/{workspace}": {
"get": {
"operationId": "team-workspaces-show",
"summary": "Get one workspace the caller can view",
"tags": [
"Team"
],
"parameters": [
{
"name": "workspace",
"in": "path",
"required": true,
"description": "Workspace id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Jane's Workspace",
"is_personal": true,
"role": "owner",
"member_count": 3,
"can_manage_team": true,
"owner_has_active_subscription": true,
"owner": {
"id": 12,
"name": "Jane Cooper",
"email": "jane@example.com"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature workspaces not enabled"
}
}
},
"patch": {
"operationId": "team-workspaces-update",
"summary": "Rename a workspace",
"tags": [
"Team"
],
"parameters": [
{
"name": "workspace",
"in": "path",
"required": true,
"description": "Workspace id.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "New workspace display name. Rules: required|string|max:255"
}
},
"required": [
"name"
]
},
"example": {
"name": "Acme Front Desk"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Workspace updated.",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Front Desk"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature workspaces not enabled"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/workspaces/{workspace}/members": {
"get": {
"operationId": "team-workspace-members-list",
"summary": "List members and pending invitations",
"tags": [
"Team"
],
"parameters": [
{
"name": "workspace",
"in": "path",
"required": true,
"description": "Workspace id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"members": [
{
"id": 12,
"name": "Jane Cooper",
"email": "jane@example.com",
"role": "owner",
"joined_at": "2026-06-01T10:00:00.000000Z",
"invited_by": null
},
{
"id": 44,
"name": "Sam Rivera",
"email": "sam@example.com",
"role": "member",
"joined_at": "2026-07-15T12:00:00.000000Z",
"invited_by": {
"id": 12,
"name": "Jane Cooper",
"email": "jane@example.com"
}
}
],
"pending_invitations": [
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"email": "newhire@example.com",
"role": "viewer",
"expires_at": "2026-08-06T12:00:00.000000Z",
"created_at": "2026-07-30T12:00:00.000000Z"
}
]
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature workspaces not enabled"
}
}
}
},
"/api/workspaces/{workspace}/members/{member}": {
"patch": {
"operationId": "team-workspace-members-update",
"summary": "Change a member's role",
"tags": [
"Team"
],
"parameters": [
{
"name": "workspace",
"in": "path",
"required": true,
"description": "Workspace id.",
"schema": {
"type": "string"
}
},
{
"name": "member",
"in": "path",
"required": true,
"description": "Member user id.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"role": {
"type": "string",
"description": "New invitable role. Rules: required|string|in:admin,member,viewer"
}
},
"required": [
"role"
]
},
"example": {
"role": "admin"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Member role updated.",
"data": {
"user_id": 44,
"role": "admin"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature workspaces not enabled"
},
"422": {
"description": "Validation failed"
}
}
},
"delete": {
"operationId": "team-workspace-members-remove",
"summary": "Remove a member from the workspace",
"tags": [
"Team"
],
"parameters": [
{
"name": "workspace",
"in": "path",
"required": true,
"description": "Workspace id.",
"schema": {
"type": "string"
}
},
{
"name": "member",
"in": "path",
"required": true,
"description": "Member user id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Member removed from the team."
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature workspaces not enabled"
},
"422": {
"description": "Target is the workspace owner"
}
}
}
},
"/api/workspaces/{workspace}/invitations": {
"post": {
"operationId": "team-workspace-invitations-create",
"summary": "Invite a teammate by email",
"tags": [
"Team"
],
"parameters": [
{
"name": "workspace",
"in": "path",
"required": true,
"description": "Workspace id.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Invitee email. Rules: required|email|max:255"
},
"role": {
"type": "string",
"description": "Role granted on accept. Rules: required|string|in:admin,member,viewer"
}
},
"required": [
"email",
"role"
]
},
"example": {
"email": "newhire@example.com",
"role": "member"
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Invitation sent.",
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"email": "newhire@example.com",
"role": "member",
"expires_at": "2026-08-06T12:00:00.000000Z"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature workspaces not enabled"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/workspaces/{workspace}/invitations/{invitation}": {
"delete": {
"operationId": "team-workspace-invitations-revoke",
"summary": "Revoke a pending invitation",
"tags": [
"Team"
],
"parameters": [
{
"name": "workspace",
"in": "path",
"required": true,
"description": "Workspace id.",
"schema": {
"type": "string"
}
},
{
"name": "invitation",
"in": "path",
"required": true,
"description": "Invitation id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Invitation revoked."
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
},
"403": {
"description": "Feature workspaces not enabled"
},
"422": {
"description": "Already accepted"
}
}
}
},
"/api/workspace-invitations/{token}": {
"get": {
"operationId": "team-workspace-invitations-preview",
"summary": "Preview an invitation link (public)",
"tags": [
"Team"
],
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"description": "Opaque token (hashed server-side for lookup).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"workspace_name": "Jane's Workspace",
"inviter_name": "Jane Cooper",
"role": "member",
"email": "newhire@example.com",
"expires_at": "2026-08-06T12:00:00.000000Z",
"requires_registration": true,
"requires_login": false
}
}
}
}
},
"403": {
"description": "Feature workspaces not enabled"
},
"422": {
"description": "Invalid, accepted, or expired token"
}
}
}
},
"/api/workspace-invitations/accept": {
"post": {
"operationId": "team-workspace-invitations-accept",
"summary": "Accept an invitation (login or register)",
"tags": [
"Team"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Plain invitation token. Rules: required|string"
},
"name": {
"type": "string",
"description": "Required only when registering a new account. Rules: required|string|max:255 when unauthenticated"
},
"password": {
"type": "string",
"description": "Required with password_confirmation when registering. Rules: required|confirmed|Password::defaults() when unauthenticated"
},
"password_confirmation": {
"type": "string",
"description": "Confirmation for password. Rules: required with password when registering"
}
},
"required": [
"token"
]
},
"example": {
"token": "plain-invite-token-from-email",
"name": "Sam Rivera",
"password": "a-secure-password",
"password_confirmation": "a-secure-password"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"message": "Invitation accepted.",
"data": {
"workspace": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Jane's Workspace"
},
"user": {
"id": 44,
"name": "Sam Rivera",
"email": "newhire@example.com"
}
},
"token": "1|sanctumPlainTextTokenForNewRegistrant"
}
}
}
},
"403": {
"description": "Feature workspaces not enabled"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/user": {
"get": {
"operationId": "account-user-show",
"summary": "Get the authenticated user profile",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 42,
"reseller_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reseller_current_ui_version": "v2",
"reseller_ui_intro_seen_at": "2026-06-01T12:00:00.000000Z",
"name": "Jordan Lee",
"email": "jordan@example.com",
"supabase_id": null,
"google_id": null,
"role": "user",
"phone": "+14155550123",
"company": "Acme Dental",
"bio": "Practice manager",
"profile_picture": "https://app.sulus.ai/storage/profile-pictures/abc123.jpg",
"status": "active",
"email_verified_at": "2026-05-01T10:00:00.000000Z",
"created_at": "2026-05-01T09:00:00.000000Z",
"updated_at": "2026-07-30T15:00:00.000000Z",
"deleted_at": null,
"is_reseller_admin": false,
"is_reseller": true,
"primary_workspace_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"active_workspace_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"workspace_role": "owner",
"can_manage_team": true
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
}
}
},
"put": {
"operationId": "account-user-update-put",
"summary": "Update profile fields (JSON)",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name. Rules: required|string|max:255"
},
"phone": {
"type": "string",
"nullable": true,
"description": "Phone number. Rules: nullable|string|max:20"
},
"company": {
"type": "string",
"nullable": true,
"description": "Company name. Rules: nullable|string|max:255"
},
"bio": {
"type": "string",
"nullable": true,
"description": "Short bio. Rules: nullable|string|max:1000"
},
"profile_picture": {
"type": "string",
"nullable": true,
"description": "Image file; stored on the public disk; response returns a public URL. Rules: nullable|image|mimes:jpeg,png,jpg,gif|max:2048"
}
},
"required": [
"name"
]
},
"example": {
"name": "Jordan Lee",
"phone": "+14155550123",
"company": "Acme Dental",
"bio": "Practice manager"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 42,
"reseller_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reseller_current_ui_version": "v2",
"reseller_ui_intro_seen_at": "2026-06-01T12:00:00.000000Z",
"name": "Jordan Lee",
"email": "jordan@example.com",
"supabase_id": null,
"google_id": null,
"role": "user",
"phone": "+14155550123",
"company": "Acme Dental",
"bio": "Practice manager",
"profile_picture": "https://app.sulus.ai/storage/profile-pictures/abc123.jpg",
"status": "active",
"email_verified_at": "2026-05-01T10:00:00.000000Z",
"created_at": "2026-05-01T09:00:00.000000Z",
"updated_at": "2026-07-30T16:00:00.000000Z",
"deleted_at": null,
"is_reseller_admin": false,
"is_reseller": true
},
"message": "Profile updated successfully"
}
}
}
},
"400": {
"description": "Uploaded file failed isValid()"
},
"401": {
"description": "Missing or invalid bearer token"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Unexpected save/storage failure"
}
}
},
"post": {
"operationId": "account-user-update-post",
"summary": "Update profile fields (multipart; used by the Profile UI)",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name. Rules: required|string|max:255"
},
"phone": {
"type": "string",
"nullable": true,
"description": "Phone number. Rules: nullable|string|max:20"
},
"company": {
"type": "string",
"nullable": true,
"description": "Company name. Rules: nullable|string|max:255"
},
"bio": {
"type": "string",
"nullable": true,
"description": "Short bio. Rules: nullable|string|max:1000"
},
"profile_picture": {
"type": "string",
"nullable": true,
"description": "Image file; stored on the public disk; response returns a public URL. Rules: nullable|image|mimes:jpeg,png,jpg,gif|max:2048"
}
},
"required": [
"name"
]
},
"example": "name=Jordan Lee\nphone=+14155550123\ncompany=Acme Dental\nbio=Practice manager\nprofile_picture=@portrait.jpg"
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"data": {
"id": 42,
"reseller_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reseller_current_ui_version": "v2",
"reseller_ui_intro_seen_at": "2026-06-01T12:00:00.000000Z",
"name": "Jordan Lee",
"email": "jordan@example.com",
"supabase_id": null,
"google_id": null,
"role": "user",
"phone": "+14155550123",
"company": "Acme Dental",
"bio": "Practice manager",
"profile_picture": "https://app.sulus.ai/storage/profile-pictures/abc123.jpg",
"status": "active",
"email_verified_at": "2026-05-01T10:00:00.000000Z",
"created_at": "2026-05-01T09:00:00.000000Z",
"updated_at": "2026-07-30T16:00:00.000000Z",
"deleted_at": null,
"is_reseller_admin": false,
"is_reseller": true
},
"message": "Profile updated successfully"
}
}
}
},
"400": {
"description": "Uploaded file failed isValid()"
},
"401": {
"description": "Missing or invalid bearer token"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Unexpected save/storage failure"
}
}
}
},
"/api/user/password": {
"put": {
"operationId": "account-user-change-password",
"summary": "Change the authenticated user password",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"current_password": {
"type": "string",
"description": "Existing password (checked with Hash::check). Rules: required|string"
},
"new_password": {
"type": "string",
"description": "New password; must match confirmation. Rules: required|string|min:8|confirmed"
},
"new_password_confirmation": {
"type": "string",
"description": "Must match new_password. Rules: required|string"
}
},
"required": [
"current_password",
"new_password",
"new_password_confirmation"
]
},
"example": {
"current_password": "old-secret-pass",
"new_password": "new-secret-pass",
"new_password_confirmation": "new-secret-pass"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"success": true,
"message": "Password changed successfully"
}
}
}
},
"400": {
"description": "Current password mismatch"
},
"401": {
"description": "Missing or invalid bearer token"
},
"422": {
"description": "Validation failed"
}
}
}
},
"/api/me/features": {
"get": {
"operationId": "account-me-features",
"summary": "Get the caller's feature-permission map",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"data": {
"features": {
"assistants": true,
"squads": true,
"tools": true,
"phone_numbers": true,
"knowledge_docs": true,
"ai_chat": true,
"call_logs": true,
"squad_call_logs": true,
"integrations": true,
"ghl_connect": true,
"workspaces": true
}
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Personal access token from /developer"
}
}
}
}