Response Schemas

This document provides detailed schemas for all API responses.

ExternalTaskMessage

The main response object for task messages.

{
  "id": "string",
  "created_at": "string",
  "text": "string",
  "sender": {
    "id": "string",
    "type": "string",
    "email": "string"
  },
  "receiver": {
    "id": "string", 
    "type": "string",
    "email": "string"
  },
  "options": [
    {
      "is_recommended": "boolean",
      "widget_parameters": [
        {
          "title": "string",
          "value": "string|number|array",
          "type": "string"
        }
      ]
    }
  ],
  "variants_options": [
    {
      "is_recommended": "boolean",
      "widget_parameters": [
        {
          "title": "string",
          "value": "string|number|array",
          "type": "string"
        }
      ]
    }
  ],
  "followup_suggestions": ["string"]
}

Field Descriptions

Field	Type	Description
id	string	Unique message identifier
created_at	string	Message creation timestamp
text	string	Message content
sender	object	Message sender information
sender.id	string	Sender identifier
sender.type	string	Sender type (user or agent)
sender.email	string	Sender email (optional)
receiver	object	Message receiver information
receiver.id	string	Receiver identifier
receiver.type	string	Receiver type (user or agent)
receiver.email	string	Receiver email (optional)
options	array	Product options with parameters
variants_options	array	Product variant options
followup_suggestions	array	Suggested follow-up questions

ExternalTaskMessageOption

Product option with parameters.

{
  "is_recommended": "boolean",
  "widget_parameters": [
    {
      "title": "string",
      "value": "string|number|array",
      "type": "string"
    }
  ]
}

Field Descriptions

Field	Type	Description
is_recommended	boolean	Whether this option is recommended
widget_parameters	array	List of parameter objects

ExternalTaskMessageOptionParameter

Individual parameter within an option.

{
  "title": "string",
  "value": "string|number|array",
  "type": "string"
}

Field Descriptions

Field	Type	Description
title	string	Parameter name/title
value	string|number|array	Parameter value
type	string	Parameter type (see Parameter Types)

Parameter Types

The type field in parameter objects can have the following values:

Type	Description	Example Value
string	Text data	"Product name"
numeric	Numeric data (integer or float)	4.4, 11581.0
boolean	Boolean true/false values	true, false
datetime	Date and time values	"2023-10-09T10:25:31.180051"
date	Date values only	"2023-10-09"
time	Time values only	"10:25:31"

Common Parameter Examples

Title	Type	Description	Example Value
Product name	string	Full product title	"BLACK+DECKER EM044KB19 Over The Range Microwave Oven..."
Image link	string	Array of product images	["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
Price	numeric	Product price	"$342.99"
Shipping cost	numeric	Shipping information	"FREE delivery Oct 23 - Nov 7"
Rating	numeric	Customer rating	4.4
Number of reviews	numeric	Review count	11581.0
Description	string	Product description	"Pre-programmed auto menus for popcorn..."
Item number	string	Product SKU/ID	"B09SB8MK37"
Variants details	string	Product variants	[{"id":"B09SB8MK37","imageUrl":"...","diffs":{"Size":"OTR 1.9 Cu.Ft"}}]
Product specs	string	Technical specifications	"Brand:BLACK+DECKER\nProduct Dimensions:15.4\"D x 29.9\"W x 16.4\"H..."
Website URL	string	Direct product link	"https://www.amazon.com/BLACK-DECKER-EM044KB19..."

CreateExternalTaskResponse

Response for task creation.

{
  "id": "string",
  "user_id": "string",
  "title": "string",
  "welcome_message": "string",
  "followup_suggestions": ["string"]
}

Field Descriptions

Field	Type	Description
id	string	Unique task identifier
user_id	string	User identifier
title	string	Task title
welcome_message	string	Initial welcome message
followup_suggestions	array	Suggested follow-up questions

ListExternalTasksResponse

Response for task listing.

{
  "tasks": [
    {
      "id": "string",
      "user_id": "string",
      "title": "string",
      "welcome_message": "string",
      "followup_suggestions": ["string"]
    }
  ],
  "total": "number",
  "page": "number",
  "size": "number"
}

Field Descriptions

Field	Type	Description
tasks	array	List of task objects
total	number	Total number of tasks
page	number	Current page number
size	number	Number of tasks per page

WebSocket Streaming Response

Real-time text content update.

{
  "channel": {
    "type": "string",
    "channel_name": "string",
    "event_name": "string"
  },
  "scope": {
    "type": "string",
    "data": {
      "status": "string"
    },
    "context": {
      "message_id": "string",
      "task_id": "string",
      "interaction_id": "string",
      "pillar": "string"
    }
  },
  "data": {
    "text": "string"
  },
  "timestamp": "string"
}

Field Descriptions

Field	Type	Description
channel	object	Channel information
channel.type	string	Channel type (usually "WEBSOCKET")
channel.channel_name	string	Unique channel identifier
channel.event_name	string	Event type (e.g., "thread-message-text-content-updated")
scope	object	Execution scope information
scope.type	string	Scope type (e.g., "LLM_ACTIVATION_EXECUTION")
scope.data	object	Execution data
scope.data.status	string	Execution status (e.g., "SUCCESS")
scope.context	object	Context information
scope.context.message_id	string	Message identifier
scope.context.task_id	string	Task identifier
scope.context.interaction_id	string	Interaction identifier
scope.context.pillar	string	Processing pillar (e.g., "WORKFLOW")
data	object	Response data
data.text	string	Streaming text content
timestamp	string	Response timestamp

Error Response

Standard error response format.

{
  "status_code": "number",
  "errors": ["string"]
}

Field Descriptions

Field	Type	Description
status_code	number	HTTP status code
errors	array	Array of error messages

Validation Error Response

Validation error response format (422 status code).

{
  "status_code": 422,
  "errors": [
    {
      "loc": ["string", 0],
      "msg": "string",
      "type": "string"
    }
  ]
}

Field Descriptions

Field	Type	Description
status_code	number	HTTP status code (422)
errors	array	Array of validation error objects
errors[].loc	array	Location of the error (field path)
errors[].msg	string	Error message
errors[].type	string	Error type

Application Error Response

Application error response format - used for application-level errors (non-validation, non-auth) across all APIs (REST and WebSocket).

REST API Application Errors

{
  "status_code": 422,
  "description": "Unprocessable Entity",
  "message": "Task termination failed due to workflow constraints, please check extra_data for more context",
  "extra_data": {
    "method": "POST",
    "path": "/api/v1/external/message",
    "query": "",
    "task_id": "68e78d0dc5a4b19a030d03d6",
    "workflow_step": "generation"
  }
}

WebSocket Application Errors (Close Code 1008)

{
  "status_code": 422,
  "description": "Unprocessable Entity",
  "message": "WebSocket message processing failed due to workflow constraints, please check extra_data for more context",
  "extra_data": {
    "method": "WebSocket",
    "path": "/api/v1/external/session",
    "query": "",
    "task_id": "68e78d0dc5a4b19a030d03d6",
    "message_type": "user_message"
  }
}

WebSocket Internal Server Errors (Close Code 1011)

{
  "status_code": 500,
  "description": "Internal Server Error",
  "message": "Internal Server Error"
}

Dynamic Extra Data

The extra_data field is dynamic and its content will differ based on the specific error type and context. Always check this field for additional error details relevant to your specific situation.

Field Descriptions

Field	Type	Description
status_code	number	HTTP status code (varies - 4xx/5xx)
description	string	Error description
message	string	Detailed error message
extra_data	object	Additional error context (application errors only)
extra_data.method	string	HTTP method used
extra_data.path	string	API path that caused the error
extra_data.query	string	Query parameters (if any)