Download OpenAPI specification:
CrafterQ Public API Specification
Invoke with ID missing in the request body to begin a conversation. Invoke with the conversation ID to continue an existing conversation.
| agentId required | string <uuid> Example: agentId=a2e8cfa0-ff0b-11ee-8d11-0242ac120003 ID of the agent to use for the chat |
| stream | boolean Default: true Omit or set to true to receive streaming responses using server-sent events. Set to false for traditional JSON response until the entire response is ready. |
| prompt required | string |
| chatId | string ID of the chat conversation to continue. |
object Optional flat key-value map of host/page situational metadata (for example currentUrl, pageTitle, userLocale, userTimezone, userLocalTime, or custom host keys). The server may enrich with approximate userLocation from GeoIP. Values must be strings. Invalid currentUrl values are ignored. |
{- "prompt": "What is the capital of France?",
- "chatId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "context": {
- "pageTitle": "Pricing Plans",
- "userLocale": "en-US",
- "userTimezone": "America/Chicago",
- "userLocalTime": "Wednesday, Nov 4, 2026, 3:45 PM"
}
}Resumes a previously interrupted streaming chat response. The server retrieves the original prompt and partial response for the specified chat and continues generating the response from where it left off.
Use this endpoint when a network interruption occurs during streaming and you want to continue from the partial response instead of starting a new request.
| agentId required | string <uuid> Example: agentId=a2e8cfa0-ff0b-11ee-8d11-0242ac120003 ID of the agent that was used for the original chat |
| chatId required | string <uuid> ID of the chat session to resume |
| messageId required | string <uuid> ID of the message to resume |
{- "chatId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "messageId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003"
}{- "error": "ValidationError",
- "message": "The email is not a valid email address.",
- "fields": [
- {
- "field": "string",
- "message": "string"
}
], - "timestamp": "2019-08-24T14:15:22Z"
}Add thumbs up (1), thumbs down (-1), or no feedback (0) to a message in a chat conversation.
| chatId required | string Chat ID to add feedback to |
| messageId required | string Message ID to add feedback to |
| feedback required | integer Enum: -1 0 1 Feedback value (-1 for thumbs down, 0 for none, 1 for thumbs up) |
{- "feedback": 1
}{- "id": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "userId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "feedback": 1
}Get chat configuration. Omitting preview or setting it to anything other than true records a live/deployed signal for SuperAdmin (subject to hourly throttle).
| id required | string <uuid> Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003 Agent ID |
| preview | string Value: "true" When |
{- "config": {
- "theme": "light",
- "primaryColor": "string",
- "displayName": "string",
- "collectFeedback": true,
- "promptFieldPlaceholder": "string",
- "userMessageBubbleColorLight": "string",
- "userMessageBubbleColorDark": "string",
- "chatBubblePositionX": "left",
- "chatBubblePositionY": "top",
- "chatBubbleOffsetX": 500,
- "chatBubbleOffsetY": 500,
- "welcomeMessage": "string",
- "outOfCreditsErrorMessage": "string",
- "followupMessages": true,
- "uiMode": "modal",
- "askOnTextSelection": false,
- "quickMessages": [
- "string"
], - "embedConfig": { }
}, - "status": "enabled",
- "avatar": "public/019a13f9-9cd2-7537-8204-511e133a3cc8/019c45e8-629c-70ef-ae74-124c8503693a/artifacts/avatar-1778827377906.png",
- "poweredBy": true,
- "hasTrainingData": true,
- "maxPromptLength": 4000
}Submit data collected by a rendered form uiPart.
The server resolves the installed action by {installedActionId} (instance UUID from
uiPart props.installedActionId) and dispatches to the registered Action for that row's catalog id.
| installedActionId required | string <uuid> Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003 Installed action instance id (from FormUiPart.props.installedActionId) |
| chatId required | string <uuid> ID of the chat conversation the form was shown in |
required | object <= 15 properties Key-value pair payload representing collected user input data. |
| submissionToken required | string [ 1 .. 2000 ] characters Cryptographically signed token associated with this form instance |
{- "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "data": {
- "email": "jane.smith@example.com",
- "firstName": "Jane",
- "lastName": "Smith",
- "message": "I'm interested in learning more about your product."
}, - "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}{- "message": "Thanks Jane! Your free guide is on its way.",
- "uiParts": [
- {
- "id": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "type": "form",
- "placement": "after_message",
- "props": {
- "installedActionId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "actionId": "lead_capture",
- "submissionToken": "string",
- "submitted": false,
- "dismissed": false,
- "dismissSupported": true,
- "fields": [
- {
- "name": "email",
- "label": "Work email",
- "required": true
}
], - "title": "Get your free guide",
- "description": "Leave your details and we'll send you the free buying guide.",
- "featuredMessage": "Free buying guide",
- "successMessage": "Thanks {firstName}! Your free guide is on its way.",
- "submitLabel": "Send me the guide",
- "dismissLabel": "No thanks",
- "dismissMessage": "Ok, we won't ask again."
}
}
]
}Records that the user dismissed a rendered form uiPart without submitting.
Only actions with dismissSupported: true accept dismiss.
For escalate_to_human, dismiss is soft: the form instance is recorded as dismissed
in Redis for history reconstruction (24 h), but a later classifier match may show a new form.
| installedActionId required | string <uuid> Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003 Installed action instance id (from FormUiPart.props.installedActionId) |
| chatId required | string <uuid> ID of the chat conversation the form was shown in |
| submissionToken required | string [ 1 .. 2000 ] characters .*\S.* Cryptographically signed token required to dismiss this form instance. Must not be blank or whitespace-only. |
{- "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}{- "error": "ValidationError",
- "message": "The email is not a valid email address.",
- "fields": [
- {
- "field": "string",
- "message": "string"
}
], - "timestamp": "2019-08-24T14:15:22Z"
}Refreshes a submission token for a form uiPart, validating signature and user identity claims.
| installedActionId required | string <uuid> Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003 Installed action instance id (from FormUiPart.props.installedActionId) |
| chatId required | string <uuid> ID of the chat session |
| submissionToken required | string [ 1 .. 2000 ] characters Expired or soon-to-expire submission token |
{- "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}{- "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Submit data collected by a rendered form uiPart.
The server resolves the installed action by {installedActionId} (instance UUID from
uiPart props.installedActionId) and dispatches to the registered Action for that row's catalog id.
| installedActionId required | string <uuid> Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003 Installed action instance id (from FormUiPart.props.installedActionId) |
| chatId required | string <uuid> ID of the chat conversation the form was shown in |
required | object <= 15 properties Key-value pair payload representing collected user input data. |
| submissionToken required | string [ 1 .. 2000 ] characters Cryptographically signed token associated with this form instance |
{- "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "data": {
- "email": "jane.smith@example.com",
- "firstName": "Jane",
- "lastName": "Smith",
- "message": "I'm interested in learning more about your product."
}, - "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}{- "message": "Thanks Jane! Your free guide is on its way.",
- "uiParts": [
- {
- "id": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "type": "form",
- "placement": "after_message",
- "props": {
- "installedActionId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "actionId": "lead_capture",
- "submissionToken": "string",
- "submitted": false,
- "dismissed": false,
- "dismissSupported": true,
- "fields": [
- {
- "name": "email",
- "label": "Work email",
- "required": true
}
], - "title": "Get your free guide",
- "description": "Leave your details and we'll send you the free buying guide.",
- "featuredMessage": "Free buying guide",
- "successMessage": "Thanks {firstName}! Your free guide is on its way.",
- "submitLabel": "Send me the guide",
- "dismissLabel": "No thanks",
- "dismissMessage": "Ok, we won't ask again."
}
}
]
}Records that the user dismissed a rendered form uiPart without submitting.
Only actions with dismissSupported: true accept dismiss.
For escalate_to_human, dismiss is soft: the form instance is recorded as dismissed
in Redis for history reconstruction (24 h), but a later classifier match may show a new form.
| installedActionId required | string <uuid> Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003 Installed action instance id (from FormUiPart.props.installedActionId) |
| chatId required | string <uuid> ID of the chat conversation the form was shown in |
| submissionToken required | string [ 1 .. 2000 ] characters .*\S.* Cryptographically signed token required to dismiss this form instance. Must not be blank or whitespace-only. |
{- "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}{- "error": "ValidationError",
- "message": "The email is not a valid email address.",
- "fields": [
- {
- "field": "string",
- "message": "string"
}
], - "timestamp": "2019-08-24T14:15:22Z"
}Refreshes a submission token for a form uiPart, validating signature and user identity claims.
| installedActionId required | string <uuid> Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003 Installed action instance id (from FormUiPart.props.installedActionId) |
| chatId required | string <uuid> ID of the chat session |
| submissionToken required | string [ 1 .. 2000 ] characters Expired or soon-to-expire submission token |
{- "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}{- "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Get chat configuration. Omitting preview or setting it to anything other than true records a live/deployed signal for SuperAdmin (subject to hourly throttle).
| id required | string <uuid> Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003 Agent ID |
| preview | string Value: "true" When |
{- "config": {
- "theme": "light",
- "primaryColor": "string",
- "displayName": "string",
- "collectFeedback": true,
- "promptFieldPlaceholder": "string",
- "userMessageBubbleColorLight": "string",
- "userMessageBubbleColorDark": "string",
- "chatBubblePositionX": "left",
- "chatBubblePositionY": "top",
- "chatBubbleOffsetX": 500,
- "chatBubbleOffsetY": 500,
- "welcomeMessage": "string",
- "outOfCreditsErrorMessage": "string",
- "followupMessages": true,
- "uiMode": "modal",
- "askOnTextSelection": false,
- "quickMessages": [
- "string"
], - "embedConfig": { }
}, - "status": "enabled",
- "avatar": "public/019a13f9-9cd2-7537-8204-511e133a3cc8/019c45e8-629c-70ef-ae74-124c8503693a/artifacts/avatar-1778827377906.png",
- "poweredBy": true,
- "hasTrainingData": true,
- "maxPromptLength": 4000
}Invoke with ID missing in the request body to begin a conversation. Invoke with the conversation ID to continue an existing conversation.
| agentId required | string <uuid> Example: agentId=a2e8cfa0-ff0b-11ee-8d11-0242ac120003 ID of the agent to use for the chat |
| stream | boolean Default: true Omit or set to true to receive streaming responses using server-sent events. Set to false for traditional JSON response until the entire response is ready. |
| prompt required | string |
| chatId | string ID of the chat conversation to continue. |
object Optional flat key-value map of host/page situational metadata (for example currentUrl, pageTitle, userLocale, userTimezone, userLocalTime, or custom host keys). The server may enrich with approximate userLocation from GeoIP. Values must be strings. Invalid currentUrl values are ignored. |
{- "prompt": "What is the capital of France?",
- "chatId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "context": {
- "pageTitle": "Pricing Plans",
- "userLocale": "en-US",
- "userTimezone": "America/Chicago",
- "userLocalTime": "Wednesday, Nov 4, 2026, 3:45 PM"
}
}Resumes a previously interrupted streaming chat response. The server retrieves the original prompt and partial response for the specified chat and continues generating the response from where it left off.
Use this endpoint when a network interruption occurs during streaming and you want to continue from the partial response instead of starting a new request.
| agentId required | string <uuid> Example: agentId=a2e8cfa0-ff0b-11ee-8d11-0242ac120003 ID of the agent that was used for the original chat |
| chatId required | string <uuid> ID of the chat session to resume |
| messageId required | string <uuid> ID of the message to resume |
{- "chatId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "messageId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003"
}{- "error": "ValidationError",
- "message": "The email is not a valid email address.",
- "fields": [
- {
- "field": "string",
- "message": "string"
}
], - "timestamp": "2019-08-24T14:15:22Z"
}Generate a set of follow-up questions based on the chat history to keep the conversation going.
| id required | string Chat ID to retrieve follow-up questions for |
[- "What is the capital of France?"
]| agentId required | string Example: agentId=a2e8cfa0-ff0b-11ee-8d11-0242ac120003 Agent ID to filter chats by |
| limit | integer [ 1 .. 100 ] Example: limit=10 Maximum number of chat to return |
| cursor | string Example: cursor=eyJwayI6ICJBR0VOVCMxMjMiLCAic2siOiAiVFMjMjAyNS0wMS0wMVQxMjozNDo1NloifQ== Base64 encoded cursor for pagination to get the next set of chat |
{- "chats": [
- {
- "id": "string",
- "summary": "string",
- "dateUpdated": "2019-08-24T14:15:22Z"
}
], - "pagination": {
- "nextCursor": "eyJwayI6ICJBR0VOVCMxMjMiLCAic2siOiAiVFMjMjAyNS0wMS0wMVQxMjozNDo1NloifQ=="
}
}Retrieve chat history by chat ID. Includes all messages and their metadata.
| id required | string Chat ID to retrieve chat details |
{- "messages": [
- {
- "message": "What is the capital of France?",
- "role": "user",
- "timestamp": "2025-01-15T12:00:00Z",
- "feedback": -1,
- "messageKind": "chat",
- "uiParts": [
- {
- "id": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "type": "form",
- "placement": "after_message",
- "props": {
- "installedActionId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
- "actionId": "lead_capture",
- "submissionToken": "string",
- "submitted": false,
- "dismissed": false,
- "dismissSupported": true,
- "fields": [
- {
- "name": "email",
- "label": "Work email",
- "required": true
}
], - "title": "Get your free guide",
- "description": "Leave your details and we'll send you the free buying guide.",
- "featuredMessage": "Free buying guide",
- "successMessage": "Thanks {firstName}! Your free guide is on its way.",
- "submitLabel": "Send me the guide",
- "dismissLabel": "No thanks",
- "dismissMessage": "Ok, we won't ask again."
}
}
], - "truncated": false
}
]
}Add thumbs up (1), thumbs down (-1), or no feedback (0) to a message in a chat conversation.
| chatId required | string Chat ID to add feedback to |
| messageId required | string Message ID to add feedback to |
| feedback required | integer Enum: -1 0 1 Feedback value (-1 for thumbs down, 0 for none, 1 for thumbs up) |
{- "feedback": 1
}{- "id": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "userId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
- "feedback": 1
}