CrafterQ (Public) (1.0.0)

Download OpenAPI specification:

CrafterQ Public API Specification

Chats

Chat related operations

Start/continue a conversation with the AI

Invoke with ID missing in the request body to begin a conversation. Invoke with the conversation ID to continue an existing conversation.

Authorizations:
chatUserAuth
query Parameters
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.

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "prompt": "What is the capital of France?",
  • "chatId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
  • "context": {
    }
}

Response samples

Content type
No sample

Resume a streaming chat response after network interruption

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.

Authorizations:
chatUserAuth
query Parameters
agentId
required
string <uuid>
Example: agentId=a2e8cfa0-ff0b-11ee-8d11-0242ac120003

ID of the agent that was used for the original chat

Request Body schema: application/json
required
chatId
required
string <uuid>

ID of the chat session to resume

messageId
required
string <uuid>

ID of the message to resume

Responses

Request samples

Content type
application/json
{
  • "chatId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
  • "messageId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003"
}

Response samples

Content type
application/json
{
  • "error": "ValidationError",
  • "message": "The email is not a valid email address.",
  • "fields": [
    ],
  • "timestamp": "2019-08-24T14:15:22Z"
}

Add feedback to a message

Add thumbs up (1), thumbs down (-1), or no feedback (0) to a message in a chat conversation.

Authorizations:
chatUserAuth
path Parameters
chatId
required
string

Chat ID to add feedback to

messageId
required
string

Message ID to add feedback to

Request Body schema: application/json
required
feedback
required
integer
Enum: -1 0 1

Feedback value (-1 for thumbs down, 0 for none, 1 for thumbs up)

Responses

Request samples

Content type
application/json
{
  • "feedback": 1
}

Response samples

Content type
application/json
{
  • "id": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "userId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "feedback": 1
}

Get chat configuration

Get chat configuration. Omitting preview or setting it to anything other than true records a live/deployed signal for SuperAdmin (subject to hourly throttle).

path Parameters
id
required
string <uuid>
Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003

Agent ID

query Parameters
preview
string
Value: "true"

When true, treats the request as playground/preview traffic and does not update agent live timestamps. Missing or any other value counts as live.

Responses

Response samples

Content type
application/json
{
  • "config": {
    },
  • "status": "enabled",
  • "avatar": "public/019a13f9-9cd2-7537-8204-511e133a3cc8/019c45e8-629c-70ef-ae74-124c8503693a/artifacts/avatar-1778827377906.png",
  • "poweredBy": true,
  • "hasTrainingData": true,
  • "maxPromptLength": 4000
}

Actions

Agent action operations (lead capture, etc.)

Submit an action form

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.

Authorizations:
chatUserAuth
path Parameters
installedActionId
required
string <uuid>
Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003

Installed action instance id (from FormUiPart.props.installedActionId)

Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "data": {
    },
  • "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "message": "Thanks Jane! Your free guide is on its way.",
  • "uiParts": [
    ]
}

Dismiss an action form

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.

Authorizations:
chatUserAuth
path Parameters
installedActionId
required
string <uuid>
Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003

Installed action instance id (from FormUiPart.props.installedActionId)

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "error": "ValidationError",
  • "message": "The email is not a valid email address.",
  • "fields": [
    ],
  • "timestamp": "2019-08-24T14:15:22Z"
}

Refresh an expired or soon-to-expire action submission token

Refreshes a submission token for a form uiPart, validating signature and user identity claims.

Authorizations:
chatUserAuth
path Parameters
installedActionId
required
string <uuid>
Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003

Installed action instance id (from FormUiPart.props.installedActionId)

Request Body schema: application/json
required
chatId
required
string <uuid>

ID of the chat session

submissionToken
required
string [ 1 .. 2000 ] characters

Expired or soon-to-expire submission token

Responses

Request samples

Content type
application/json
{
  • "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Service:Database

Database service operations

Submit an action form

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.

Authorizations:
chatUserAuth
path Parameters
installedActionId
required
string <uuid>
Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003

Installed action instance id (from FormUiPart.props.installedActionId)

Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "data": {
    },
  • "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "message": "Thanks Jane! Your free guide is on its way.",
  • "uiParts": [
    ]
}

Dismiss an action form

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.

Authorizations:
chatUserAuth
path Parameters
installedActionId
required
string <uuid>
Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003

Installed action instance id (from FormUiPart.props.installedActionId)

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "error": "ValidationError",
  • "message": "The email is not a valid email address.",
  • "fields": [
    ],
  • "timestamp": "2019-08-24T14:15:22Z"
}

Refresh an expired or soon-to-expire action submission token

Refreshes a submission token for a form uiPart, validating signature and user identity claims.

Authorizations:
chatUserAuth
path Parameters
installedActionId
required
string <uuid>
Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003

Installed action instance id (from FormUiPart.props.installedActionId)

Request Body schema: application/json
required
chatId
required
string <uuid>

ID of the chat session

submissionToken
required
string [ 1 .. 2000 ] characters

Expired or soon-to-expire submission token

Responses

Request samples

Content type
application/json
{
  • "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "submissionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Get chat configuration

Get chat configuration. Omitting preview or setting it to anything other than true records a live/deployed signal for SuperAdmin (subject to hourly throttle).

path Parameters
id
required
string <uuid>
Example: a2e8cfa0-ff0b-11ee-8d11-0242ac120003

Agent ID

query Parameters
preview
string
Value: "true"

When true, treats the request as playground/preview traffic and does not update agent live timestamps. Missing or any other value counts as live.

Responses

Response samples

Content type
application/json
{
  • "config": {
    },
  • "status": "enabled",
  • "avatar": "public/019a13f9-9cd2-7537-8204-511e133a3cc8/019c45e8-629c-70ef-ae74-124c8503693a/artifacts/avatar-1778827377906.png",
  • "poweredBy": true,
  • "hasTrainingData": true,
  • "maxPromptLength": 4000
}

Service:Inference

Inference service operations

Start/continue a conversation with the AI

Invoke with ID missing in the request body to begin a conversation. Invoke with the conversation ID to continue an existing conversation.

Authorizations:
chatUserAuth
query Parameters
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.

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "prompt": "What is the capital of France?",
  • "chatId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
  • "context": {
    }
}

Response samples

Content type
No sample

Resume a streaming chat response after network interruption

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.

Authorizations:
chatUserAuth
query Parameters
agentId
required
string <uuid>
Example: agentId=a2e8cfa0-ff0b-11ee-8d11-0242ac120003

ID of the agent that was used for the original chat

Request Body schema: application/json
required
chatId
required
string <uuid>

ID of the chat session to resume

messageId
required
string <uuid>

ID of the message to resume

Responses

Request samples

Content type
application/json
{
  • "chatId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003",
  • "messageId": "a2e8cfa0-ff0b-11ee-8d11-0242ac120003"
}

Response samples

Content type
application/json
{
  • "error": "ValidationError",
  • "message": "The email is not a valid email address.",
  • "fields": [
    ],
  • "timestamp": "2019-08-24T14:15:22Z"
}

Generate a set of follow-up questions based on the chat history

Generate a set of follow-up questions based on the chat history to keep the conversation going.

Authorizations:
chatUserAuth
path Parameters
id
required
string

Chat ID to retrieve follow-up questions for

Responses

Response samples

Content type
application/json
[
  • "What is the capital of France?"
]

Service:History

History service operations

Retrieve the paginated list of chats for a specific user

Authorizations:
chatUserAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "chats": [
    ],
  • "pagination": {
    }
}

Retrieve chat history by chat ID

Retrieve chat history by chat ID. Includes all messages and their metadata.

Authorizations:
chatUserAuth
path Parameters
id
required
string

Chat ID to retrieve chat details

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ]
}

Add feedback to a message

Add thumbs up (1), thumbs down (-1), or no feedback (0) to a message in a chat conversation.

Authorizations:
chatUserAuth
path Parameters
chatId
required
string

Chat ID to add feedback to

messageId
required
string

Message ID to add feedback to

Request Body schema: application/json
required
feedback
required
integer
Enum: -1 0 1

Feedback value (-1 for thumbs down, 0 for none, 1 for thumbs up)

Responses

Request samples

Content type
application/json
{
  • "feedback": 1
}

Response samples

Content type
application/json
{
  • "id": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "chatId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "userId": "b9f43f6c-483f-446b-9d3a-90893bbd07f8",
  • "feedback": 1
}