Conversation runtime

Platform

Serves the conversation itself: holds the task set, runs the agent whose turn it is, calls the functions an answer triggers, and writes what was said to the loan record.

Used when: Behind every conversation above. Nothing in the fleet runs without it.
Collects: The message, the conversation it belongs to, and the task it advances.
Returns: The next message, the task state, and the record write the answer produced.
Hands off: Conversation management — the queue, the configuration and the work-tracking integration
Evidence: chatbot
chats
chat-configuration-template

Operations

Assistants

POST /assistants

Create a new assistant

createAssistant

Chat

This endpoint allows for the creation of a versatile assistant capable of interacting with different platforms such as OpenAI and Google. It enables the configuration of staircase service calls (functions). Users can define attributes like the assistant's name, functionality, and the tools it will use, ensuring the assistant is tailored to specific operational needs.

Request

application/json

{
  "name": "General Helper",
  "description": "An assistant designed to offer general help across various tasks, including scheduling, reminders, and basic inquiries.",
  "platforms": [
    {
      "platform_name": "OpenAI",
      "model": "gpt-4-1106-preview"
    }
  ],
  "tools": [
    {
      "tool_type": "retrival"
    },
    {
      "tool_type": "code_interpretor"
    },
    {
      "tool_type": "function",
      "function": {
        "http_method": "GET",
        "path": "/data/retrieve",
        "name": "retrieveData",
        "description": "Function to retrieve data from the database.",
        "parameters": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The identifier of the data to retrieve."
            },
            "fields": {
              "type": "array",
              "description": "The fields to retrieve.",
              "items": {
                "type": "string"
              }
            },
            "limit": {
              "type": "integer",
              "description": "The maximum number of records to retrieve."
            },
            "offset": {
              "type": "integer",
              "description": "The number of records to skip."
            },
            "order_by": {
              "type": "string",
              "description": "The field to order by."
            },
            "order_direction": {
              "type": "string",
              "description": "The direction to order by."
            },
            "filter": {
              "type": "object",
              "description": "The filter to apply."
            },
            "search": {
              "type": "string",
              "description": "The search to apply."
            }
          }
        }
      }
    }
  ]
}

application/json

{
  "name": "EduBot",
  "description": "An educational assistant designed to help students with learning, offering explanations, and quizzing capabilities.",
  "platforms": [
    {
      "platform_name": "OpenAI",
      "model": "gpt-4-1106-preview"
    }
  ],
  "tools": [
    {
      "tool_type": "function",
      "function": {
        "http_method": "POST",
        "path": "/education/evaluate",
        "name": "evaluateAnswer",
        "description": "Function to evaluate student responses in quizzes.",
        "parameters": {
          "type": "object",
          "properties": {
            "question": {
              "type": "string",
              "description": "The question to evaluate."
            },
            "answer": {
              "type": "string",
              "description": "The answer to evaluate."
            },
            "options": {
              "type": "array",
              "description": "The options to evaluate.",
              "items": {
                "type": "string"
              }
            },
            "correct_answer": {
              "type": "string",
              "description": "The correct answer."
            },
            "correct_options": {
              "type": "array",
              "description": "The correct options.",
              "items": {
                "type": "string"
              }
            },
            "incorrect_answer": {
              "type": "string",
              "description": "The incorrect answer."
            },
            "incorrect_options": {
              "type": "array",
              "description": "The incorrect options.",
              "items": {
                "type": "string"
              }
            },
            "explanation": {
              "type": "string",
              "description": "The explanation."
            },
            "metadata": {
              "type": "object",
              "description": "The metadata."
            }
          }
        }
      }
    }
  ]
}

Request body`application/json`

10 fields

Field	Type	Description
`assistant_id`	`string`	Unique identifier for the assistant
`created_at`	`integer (int64)`	Timestamp of creation
`name`	`string`	Name of the assistant
`description`	`string`	Description of the assistant's purpose
`instructions`	`string`	Instructions for using the assistant
`platforms`	`array`	List of platforms the assistant is available on
`tools`	`array`	Tools utilized by the assistant
`file_ids`	`string[]`	List of OpenAI file identifiers associated with the assistant
`blob_file_ids`	`string[]`	List of `Persistence Blob` identifiers associated with the assistant
`metadata`	`object`	Metadata related to the assistant

Response `201application/json`

10 fields

Assistant created

Field	Type	Description
`assistant_id`	`string`	Unique identifier for the assistant
`created_at`	`integer (int64)`	Timestamp of creation
`name`	`string`	Name of the assistant
`description`	`string`	Description of the assistant's purpose
`instructions`	`string`	Instructions for using the assistant
`platforms`	`array`	List of platforms the assistant is available on
`tools`	`array`	Tools utilized by the assistant
`file_ids`	`string[]`	List of OpenAI file identifiers associated with the assistant
`blob_file_ids`	`string[]`	List of `Persistence Blob` identifiers associated with the assistant
`metadata`	`object`	Metadata related to the assistant

Other responses

400403

GET /assistants

List all assistants

listAssistants

Retrieves a list of all created assistants. This endpoint is useful for obtaining an overview of all assistants available in the system.

Response `200application/json`

10 fields

A list of assistants

Field	Type	Description
`assistant_id`	`string`	Unique identifier for the assistant
`created_at`	`integer (int64)`	Timestamp of creation
`name`	`string`	Name of the assistant
`description`	`string`	Description of the assistant's purpose
`instructions`	`string`	Instructions for using the assistant
`platforms`	`array`	List of platforms the assistant is available on
`tools`	`array`	Tools utilized by the assistant
`file_ids`	`string[]`	List of OpenAI file identifiers associated with the assistant
`blob_file_ids`	`string[]`	List of `Persistence Blob` identifiers associated with the assistant
`metadata`	`object`	Metadata related to the assistant

Other responses

403404

Chats

POST /apps

Create chat app

createApp

Create Chat App

Create new chat App. All incoming messages will be forwared as POST request to the provided webhook URL with app id, chat id and message submitted by user on UI. Service expects webhook to respond with 200 OK status code. JSON Schema of the request body:

{
 "type": "object",
 "properties": {
 "app_id": {
 "type": "string"
 },
 "chat_id": {
 "type": "string"
 },
 "message": {
 "type": "string"
 }
 },
 "required": [
 "app_id",
 "chat_id",
 "message"
 ]
}

Example of the request body:

{
 "app_id": "app_id",
 "chat_id": "chat_id",
 "message": "message"
}

Request

application/json

{
  "webhook_url": "https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a",
  "app_name": "My App"
}

Response

application/json

App created

{
  "id": "01H9QPFE3CVK771YYD3MN9T4GQ",
  "webhook_url": "https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a",
  "app_name": "My App"
}

Request body`application/json`

2 fields

Field	Type	Description
`webhook_url`required	`string`	Webhook URLExample `https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a`
`app_name`required	`string`	App nameExample `My App`

Response `201application/json`

3 fields

App created

Field	Type	Description
`id`	`string`	App IDExample `01H9QPFE3CVK771YYD3MN9T4GQ`
`webhook_url`	`string`	Webhook URLExample `https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a`
`app_name`	`string`	App nameExample `My App`

Response `400application/json`

1 fields

Request data invalid

Field	Type	Description
`message`	`string`	Error message

Response `403application/json`

1 fields

Missing API key

Field	Type	Description
`message`	`string`	Message

POST /apps/{app_id}/chats/{chat_id}/messages

Send message

sendMessage

Send message to chat.

Request

application/json

{
  "message": "Hello World"
}

Response

application/json

Message sent

{
  "message": "Message sent successfully"
}

Parameters

Parameter	Type	Example	Description
`app_id` required	`string` path	`01H9QPFE3CVK771YYD3MN9T4GQ`	App ID
`chat_id` required	`string` path	`01H9QQ1AB6HQSB8DEESRW3Z0Z8`	Chat ID

Request body`application/json`

1 fields

Field	Type	Description
`message`required	`string`	MessageExample `Hello World`

Response `200application/json`

1 fields

Message sent

Field	Type	Description
`message`	`string`	Response messageExample `Message sent successfully`

Response `400application/json`

1 fields

Request data invalid

Field	Type	Description
`message`	`string`	Error message

Response `403application/json`

1 fields

Missing API key

Field	Type	Description
`message`	`string`	Message

Response `404application/json`

1 fields

Requested resource not found

Field	Type	Description
`message`	`string`	Message

Runs

POST /runs

Create add message and run

createMessageAndRun

Submits a message and initiates a run process based on that message. This is typically used to trigger processing of a user's input by the assistant.

Request

application/json

{
  "thread_id": "thread_321",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "Can you also provide tomorrow's forecast?"
      }
    }
  ],
  "assistant_id": "assistant_654"
}

application/json

{
  "thread_id": "thread_321",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "I need assistance with organizing a team event."
      }
    }
  ],
  "orchestrator_assistant_id": "assistant_9012"
}

Request body`application/json`

11 fields

Field	Type	Description
`transaction_id`	`string`	The identifier, which can be referenced in API endpoints.
`message_id`	`string`	The identifier, which can be referenced in API endpoints.
`created_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the message was created.
`thread_id`required	`string`	The identifier of the thread that the message belongs to.
`role`required	`string`	The role of the message.`user`
`content`required	`string`	The content of the message.
`file_ids`	`string[]`	The file IDs associated with the message.
`assistant_id`	`string`	The identifier of the assistant that should process the message.
`orchestrator_assistant_id`	`string`	The identifier of the assistant that should orchestrate the message.
`run_id`	`string`	The identifier of the run that processed the message.
`metadata`	`object`	Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

Response `201application/json`

13 fields

Message added and run initiated

Field	Type	Description
`id`required	`string`	The identifier, which can be referenced in API endpoints.
`created_at`required	`integer (int64)`	The Unix timestamp (in seconds) for when the run was created.
`assistant_id`required	`string`	The identifier of the assistant that should process the message.
`thread_id`required	`string`	The identifier of the thread that the message belongs to.
`status`required	`string`	The status of the run.`completedin_progress`
`started_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run was started.
`expires_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run will expire.
`cancelled_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run was cancelled.
`failed_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run failed.
`completed_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run completed.
`last_error`	`string`	The last error that occurred during the run.
`platforms`	`array`	The platforms that the run was processed on.
`metadata`	`object`	Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

Other responses

403

GET /runs/{run_id}

Get a run by ID

getRun

Retrieves the details of a specific run by its unique identifier.

Parameters

Parameter	Type	Example	Description
`run_id` required	`string` path	`123`	Unique identifier of the run
`x-sc-trace-id` required	`string` header	`01GYYMHV78DVPV5TSHPQTJ31X9`	Trace ID

Response `200application/json`

13 fields

Run details

Field	Type	Description
`id`required	`string`	The identifier, which can be referenced in API endpoints.
`created_at`required	`integer (int64)`	The Unix timestamp (in seconds) for when the run was created.
`assistant_id`required	`string`	The identifier of the assistant that should process the message.
`thread_id`required	`string`	The identifier of the thread that the message belongs to.
`status`required	`string`	The status of the run.`completedin_progress`
`started_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run was started.
`expires_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run will expire.
`cancelled_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run was cancelled.
`failed_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run failed.
`completed_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the run completed.
`last_error`	`string`	The last error that occurred during the run.
`platforms`	`array`	The platforms that the run was processed on.
`metadata`	`object`	Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

Other responses

403404

Threads

POST /threads

Create a new thread

createThread

This endpoint allows for the creation of a new thread. Threads are used to group messages together, allowing for the tracking of conversations between users and assistants.

Request

application/json

{
  "transaction_id": "12345"
}

Request body`application/json`

1 fields

Field	Type	Description
`transaction_id`	`string`	The transaction ID associated with the thread

Response `201application/json`

3 fields

Thread created

Field	Type	Description
`id`	`string`	The identifier, which can be referenced in API endpoints.
`created_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the thread was created.
`metadata`	`object`	Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

Other responses

400403

GET /threads

Fetches chat threads associated with a given transaction ID.

retrieveChatThreads

Retrieve Chat Threads by Transaction ID

Fetches chat threads associated with a given transaction ID.

Parameters

Parameter	Type	Example	Description
`transaction_id` required	`string` query	—	The transaction ID to fetch chat threads for.
`x-sc-trace-id` required	`string` header	`01GYYMHV78DVPV5TSHPQTJ31X9`	Trace ID

Response `200application/json`

1 fields

A list of chat threads.

Field	Type	Description
`chat_threads`	`array`	A list of chat threads.

Response `404application/json`

1 fields

Chat thread not found.

Field	Type	Description
`error`	`string`	Chat thread not found.Example `Chat thread not found`

Other responses

403

Messages

GET /threads/{thread_id}/messages

List all messages in a thread

listMessages

Retrieves a list of all messages in a specific thread. This endpoint is useful for obtaining an overview of all messages in a thread.

Parameters

Parameter	Type	Example	Description
`thread_id` required	`string` path	`123`	Unique identifier of the thread
`x-sc-trace-id` required	`string` header	`01GYYMHV78DVPV5TSHPQTJ31X9`	Trace ID

Response `200application/json`

11 fields

A list of messages

Field	Type	Description
`transaction_id`	`string`	The identifier, which can be referenced in API endpoints.
`message_id`	`string`	The identifier, which can be referenced in API endpoints.
`created_at`	`integer (int64)`	The Unix timestamp (in seconds) for when the message was created.
`thread_id`required	`string`	The identifier of the thread that the message belongs to.
`role`required	`string`	The role of the message.`user`
`content`required	`string`	The content of the message.
`file_ids`	`string[]`	The file IDs associated with the message.
`assistant_id`	`string`	The identifier of the assistant that should process the message.
`orchestrator_assistant_id`	`string`	The identifier of the assistant that should orchestrate the message.
`run_id`	`string`	The identifier of the run that processed the message.
`metadata`	`object`	Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

Other responses

403404

Credentials

POST /credentials

Create a new credential

createCredential

This endpoint allows for the creation of a new credential. Credentials are used to authenticate users and assistants, ensuring that only authorized users can access the system.

Request

application/json

{
  "partner": "12345",
  "value": "12345"
}

Request body`application/json`

2 fields

Field	Type	Description
`partner`	`string`	The partner associated with the credential`GoogleOpenAI`
`value`	`string`	The value of the credential

Response `201application/json`

2 fields

Credential created

Field	Type	Description
`partner`	`string`	The partner associated with the credential
`value`	`string`	The value of the credential

Other responses

400403

Operations

Assistants

Create a new assistant

Request

Request bodyapplication/json

Response 201application/json

Other responses

List all assistants

Response 200application/json

Other responses

Chats

Create chat app

Request

Response

Request bodyapplication/json

Response 201application/json

Response 400application/json

Response 403application/json

Send message

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Response 400application/json

Response 403application/json

Response 404application/json

Runs

Create add message and run

Request

Request bodyapplication/json

Response 201application/json

Other responses

Get a run by ID

Parameters

Response 200application/json

Other responses

Threads

Create a new thread

Request

Request bodyapplication/json

Response 201application/json

Other responses

Fetches chat threads associated with a given transaction ID.

Parameters

Response 200application/json

Response 404application/json

Other responses

Messages

List all messages in a thread

Parameters

Response 200application/json

Other responses

Credentials

Create a new credential

Request

Request bodyapplication/json

Response 201application/json

Other responses

Others in Platform

Request body`application/json`

Response `201application/json`

Response `200application/json`

Request body`application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Request body`application/json`

Response `201application/json`

Response `200application/json`

Request body`application/json`

Response `201application/json`

Response `200application/json`

Response `404application/json`

Response `200application/json`

Request body`application/json`

Response `201application/json`