<!-- https://staircase.co/agents/roster/conversation-runtime -->
# Conversation runtime

# Conversation runtime

Platform

<!--source:agent-kits-->
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.
<!--/source-->

- **Used when**
<!--source:agent-kits-->
— Behind every conversation above. Nothing in the fleet runs without it.
<!--/source-->

- **Collects**
<!--source:agent-kits-->
- The message, the conversation it belongs to, and the task it advances.
<!--/source-->

- **Returns**
<!--source:agent-kits-->
- The next message, the task state, and the record write the answer produced.
<!--/source-->

- **Hands off**
- Conversation management — the queue, the configuration and the work-tracking integration

- **Evidence**
- `chatbot`
- `chats`
- `chat-configuration-template`

## Operations

<!--source:api-specifications-->

### Assistants
<!--/source-->

`POST` `/assistants`

<!--source:api-specifications-->

#### Create a new assistant
<!--/source-->

`createAssistant`

<!--source:api-specifications-->
Chat
<!--/source-->

<!--source:api-specifications-->
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.

<!--/source-->

##### Request

<!--source:api-specifications-->
Example1Example2
<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "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."
 }
 }
 }
 }
 }
 ]
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "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."
 }
 }
 }
 }
 }
 ]
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
10 fields
<!--/source-->

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

##### Response `201``application/json`

<!--source:api-specifications-->
10 fields
<!--/source-->
<!--source:api-specifications-->
Assistant created
<!--/source-->

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

##### Other responses

`400``403`

`GET` `/assistants`

<!--source:api-specifications-->

#### List all assistants
<!--/source-->

`listAssistants`

<!--source:api-specifications-->
Retrieves a list of all created assistants. This endpoint is useful for obtaining an overview of all assistants available in the system.

<!--/source-->

##### Response `200``application/json`

<!--source:api-specifications-->
10 fields
<!--/source-->
<!--source:api-specifications-->
A list of assistants
<!--/source-->

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

##### Other responses

`403``404`

<!--source:api-specifications-->

### Chats
<!--/source-->

`POST` `/apps`

<!--source:api-specifications-->

#### Create chat app
<!--/source-->

`createApp`

<!--source:api-specifications-->
Create Chat App
<!--/source-->

<!--source:api-specifications-->
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"
}
```

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "webhook_url": "https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a",
 "app_name": "My App"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
201400
<!--/source-->

<!--source:api-specifications-->
application/json Copy App created

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

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `webhook_url`required | `string` | <!--source:api-specifications-->Webhook URL<!--/source-->Example `https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a` |
| `app_name`required | `string` | <!--source:api-specifications-->App name<!--/source-->Example `My App` |

##### Response `201``application/json`

<!--source:api-specifications-->
3 fields
<!--/source-->
<!--source:api-specifications-->
App created
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | <!--source:api-specifications-->App ID<!--/source-->Example `01H9QPFE3CVK771YYD3MN9T4GQ` |
| `webhook_url` | `string` | <!--source:api-specifications-->Webhook URL<!--/source-->Example `https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a` |
| `app_name` | `string` | <!--source:api-specifications-->App name<!--/source-->Example `My App` |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Missing API key
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

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

<!--source:api-specifications-->

#### Send message
<!--/source-->

`sendMessage`

<!--source:api-specifications-->
Send message to chat.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "message": "Hello World"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Message sent

```
{
 "message": "Message sent successfully"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Container not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
2
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `app_id` required | `string` path | `01H9QPFE3CVK771YYD3MN9T4GQ` | <!--source:api-specifications-->App ID<!--/source--> |
| `chat_id` required | `string` path | `01H9QQ1AB6HQSB8DEESRW3Z0Z8` | <!--source:api-specifications-->Chat ID<!--/source--> |

##### Request body`application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | <!--source:api-specifications-->Message<!--/source-->Example `Hello World` |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Message sent
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Response message<!--/source-->Example `Message sent successfully` |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Missing API key
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

<!--source:api-specifications-->

### Runs
<!--/source-->

`POST` `/runs`

<!--source:api-specifications-->

#### Create add message and run
<!--/source-->

`createMessageAndRun`

<!--source:api-specifications-->
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.

<!--/source-->

##### Request

<!--source:api-specifications-->
example1example2
<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "thread_id": "thread_321",
 "role": "user",
 "content": [
 {
 "type": "text",
 "text": {
 "value": "Can you also provide tomorrow's forecast?"
 }
 }
 ],
 "assistant_id": "assistant_654"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "thread_id": "thread_321",
 "role": "user",
 "content": [
 {
 "type": "text",
 "text": {
 "value": "I need assistance with organizing a team event."
 }
 }
 ],
 "orchestrator_assistant_id": "assistant_9012"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
11 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | <!--source:api-specifications-->The identifier, which can be referenced in API endpoints.<!--/source--> |
| `message_id` | `string` | <!--source:api-specifications-->The identifier, which can be referenced in API endpoints.<!--/source--> |
| `created_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the message was created.<!--/source--> |
| `thread_id`required | `string` | <!--source:api-specifications-->The identifier of the thread that the message belongs to.<!--/source--> |
| `role`required | `string` | <!--source:api-specifications-->The role of the message.<!--/source-->`user` |
| `content`required | `string` | <!--source:api-specifications-->The content of the message.<!--/source--> |
| `file_ids` | `string[]` | <!--source:api-specifications-->The file IDs associated with the message.<!--/source--> |
| `assistant_id` | `string` | <!--source:api-specifications-->The identifier of the assistant that should process the message.<!--/source--> |
| `orchestrator_assistant_id` | `string` | <!--source:api-specifications-->The identifier of the assistant that should orchestrate the message.<!--/source--> |
| `run_id` | `string` | <!--source:api-specifications-->The identifier of the run that processed the message.<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->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.<!--/source--> |

##### Response `201``application/json`

<!--source:api-specifications-->
13 fields
<!--/source-->
<!--source:api-specifications-->
Message added and run initiated
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | <!--source:api-specifications-->The identifier, which can be referenced in API endpoints.<!--/source--> |
| `created_at`required | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run was created.<!--/source--> |
| `assistant_id`required | `string` | <!--source:api-specifications-->The identifier of the assistant that should process the message.<!--/source--> |
| `thread_id`required | `string` | <!--source:api-specifications-->The identifier of the thread that the message belongs to.<!--/source--> |
| `status`required | `string` | <!--source:api-specifications-->The status of the run.<!--/source-->`completed``in_progress` |
| `started_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run was started.<!--/source--> |
| `expires_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run will expire.<!--/source--> |
| `cancelled_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run was cancelled.<!--/source--> |
| `failed_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run failed.<!--/source--> |
| `completed_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run completed.<!--/source--> |
| `last_error` | `string` | <!--source:api-specifications-->The last error that occurred during the run.<!--/source--> |
| `platforms` | `array` | <!--source:api-specifications-->The platforms that the run was processed on.<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->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.<!--/source--> |

##### Other responses

`403`

`GET` `/runs/{run_id}`

<!--source:api-specifications-->

#### Get a run by ID
<!--/source-->

`getRun`

<!--source:api-specifications-->
Retrieves the details of a specific run by its unique identifier.

<!--/source-->

##### Parameters

<!--source:api-specifications-->
2
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `run_id` required | `string` path | `123` | <!--source:api-specifications-->Unique identifier of the run<!--/source--> |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | <!--source:api-specifications-->Trace ID<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
13 fields
<!--/source-->
<!--source:api-specifications-->
Run details
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | <!--source:api-specifications-->The identifier, which can be referenced in API endpoints.<!--/source--> |
| `created_at`required | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run was created.<!--/source--> |
| `assistant_id`required | `string` | <!--source:api-specifications-->The identifier of the assistant that should process the message.<!--/source--> |
| `thread_id`required | `string` | <!--source:api-specifications-->The identifier of the thread that the message belongs to.<!--/source--> |
| `status`required | `string` | <!--source:api-specifications-->The status of the run.<!--/source-->`completed``in_progress` |
| `started_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run was started.<!--/source--> |
| `expires_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run will expire.<!--/source--> |
| `cancelled_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run was cancelled.<!--/source--> |
| `failed_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run failed.<!--/source--> |
| `completed_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the run completed.<!--/source--> |
| `last_error` | `string` | <!--source:api-specifications-->The last error that occurred during the run.<!--/source--> |
| `platforms` | `array` | <!--source:api-specifications-->The platforms that the run was processed on.<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->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.<!--/source--> |

##### Other responses

`403``404`

<!--source:api-specifications-->

### Threads
<!--/source-->

`POST` `/threads`

<!--source:api-specifications-->

#### Create a new thread
<!--/source-->

`createThread`

<!--source:api-specifications-->
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.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "transaction_id": "12345"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | <!--source:api-specifications-->The transaction ID associated with the thread<!--/source--> |

##### Response `201``application/json`

<!--source:api-specifications-->
3 fields
<!--/source-->
<!--source:api-specifications-->
Thread created
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | <!--source:api-specifications-->The identifier, which can be referenced in API endpoints.<!--/source--> |
| `created_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the thread was created.<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->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.<!--/source--> |

##### Other responses

`400``403`

`GET` `/threads`

<!--source:api-specifications-->

#### Fetches chat threads associated with a given transaction ID.
<!--/source-->

`retrieveChatThreads`

<!--source:api-specifications-->
Retrieve Chat Threads by Transaction ID
<!--/source-->

<!--source:api-specifications-->
Fetches chat threads associated with a given transaction ID.

<!--/source-->

##### Parameters

<!--source:api-specifications-->
2
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string` query | — | <!--source:api-specifications-->The transaction ID to fetch chat threads for.<!--/source--> |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | <!--source:api-specifications-->Trace ID<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
A list of chat threads.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `chat_threads` | `array` | <!--source:api-specifications-->A list of chat threads.<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Chat thread not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | <!--source:api-specifications-->Chat thread not found.<!--/source-->Example `Chat thread not found` |

##### Other responses

`403`

<!--source:api-specifications-->

### Messages
<!--/source-->

`GET` `/threads/{thread_id}/messages`

<!--source:api-specifications-->

#### List all messages in a thread
<!--/source-->

`listMessages`

<!--source:api-specifications-->
Retrieves a list of all messages in a specific thread. This endpoint is useful for obtaining an overview of all messages in a thread.

<!--/source-->

##### Parameters

<!--source:api-specifications-->
2
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `thread_id` required | `string` path | `123` | <!--source:api-specifications-->Unique identifier of the thread<!--/source--> |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | <!--source:api-specifications-->Trace ID<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
11 fields
<!--/source-->
<!--source:api-specifications-->
A list of messages
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | <!--source:api-specifications-->The identifier, which can be referenced in API endpoints.<!--/source--> |
| `message_id` | `string` | <!--source:api-specifications-->The identifier, which can be referenced in API endpoints.<!--/source--> |
| `created_at` | `integer (int64)` | <!--source:api-specifications-->The Unix timestamp (in seconds) for when the message was created.<!--/source--> |
| `thread_id`required | `string` | <!--source:api-specifications-->The identifier of the thread that the message belongs to.<!--/source--> |
| `role`required | `string` | <!--source:api-specifications-->The role of the message.<!--/source-->`user` |
| `content`required | `string` | <!--source:api-specifications-->The content of the message.<!--/source--> |
| `file_ids` | `string[]` | <!--source:api-specifications-->The file IDs associated with the message.<!--/source--> |
| `assistant_id` | `string` | <!--source:api-specifications-->The identifier of the assistant that should process the message.<!--/source--> |
| `orchestrator_assistant_id` | `string` | <!--source:api-specifications-->The identifier of the assistant that should orchestrate the message.<!--/source--> |
| `run_id` | `string` | <!--source:api-specifications-->The identifier of the run that processed the message.<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->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.<!--/source--> |

##### Other responses

`403``404`

<!--source:api-specifications-->

### Credentials
<!--/source-->

`POST` `/credentials`

<!--source:api-specifications-->

#### Create a new credential
<!--/source-->

`createCredential`

<!--source:api-specifications-->
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.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "partner": "12345",
 "value": "12345"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `partner` | `string` | <!--source:api-specifications-->The partner associated with the credential<!--/source-->`Google``OpenAI` |
| `value` | `string` | <!--source:api-specifications-->The value of the credential<!--/source--> |

##### Response `201``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Credential created
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `partner` | `string` | <!--source:api-specifications-->The partner associated with the credential<!--/source--> |
| `value` | `string` | <!--source:api-specifications-->The value of the credential<!--/source--> |

##### Other responses

`400``403`

## Others in Platform

- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory