> For the complete documentation index, see [llms.txt](https://mind-expression-docs.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mind-expression-docs.gitbook.io/home/reference/api-docs.md).

# API Docs

## Send messages to Mind Expression API

Use the <mark style="color:blue;">`/api/v1/gateway/default/DEVEOPER_ID/SCOPE_ID`</mark> endpoint to send a message to the Mind Expression API, where the Mind Expression CAI will receive your message query and respond according to the configurations of your subjects. You can configure the responses with multiple types of templates and formats, presenting you with the flexibility to format messages on your platform.

| Endpoint                                                                        | Authentication                                                                                          |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">`/api/v1/gateway/default/DEVEOPER_ID/SCOPE_ID`</mark> | Developers can authenticate API calls to this endpoint with the Auth Key given on the integration page. |

## What you need

1. Engine URL - You can get this on the integration page. This is the main URL you will use to access the API’s endpoint.
2. Auth Key - This is the authorization token on the integration page. This token is used to authorize your access to the Mind Expression API.

## Request Headers

<table data-header-hidden><thead><tr><th width="194"></th><th width="118.33333333333331"></th><th></th></tr></thead><tbody><tr><td><strong>Content-Type</strong></td><td>Required</td><td><mark style="color:blue;"><code>application/json</code></mark></td></tr><tr><td><strong>Authorization</strong></td><td>Required</td><td>Bearer {Auth Key}</td></tr><tr><td><strong>X-Conversation-Id</strong></td><td></td><td>UUID (e.g. <mark style="color:blue;"><code>408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c</code></mark>)</td></tr></tbody></table>

All messages are contained with a conversation with a unique ID in the UUID format. On the first message that will start a new conversation, the Mind Expression API will return a 202 along with the conversation ID in which the user must return in the request header in order to continue the conversation. Messages without this header will be considered as a new conversation and might result in unintended behaviors.

## Request Body

| **query**     | Required | String of messages to send                                                                |
| ------------- | -------- | ----------------------------------------------------------------------------------------- |
| **query-id**  | Required | Unique UUID to identify the message                                                       |
| **timestamp** | Required | Time in UNIX Epoch on sending the message                                                 |
| **custom**    |          | <p><mark style="color:blue;"><code>Custom Object</code></mark><br>(See example below)</p> |

{% hint style="info" %}
Custom Object can be any JSON object.
{% endhint %}

#### Custom Object Example

{% code overflow="wrap" lineNumbers="true" %}

```json
{
    "user-name": "Jane Doe"
}
```

{% endcode %}

### How to get Header & Body using Mindscript in Mind Expression

#### **Request Example**

**HTTP Header**

```
Content-Type: application/json
Authorization: Bearer bWluZC1haTpyZWFsam9obmRvZQ
platform: ANDROID
```

**HTTP Body**

```json
{
    "query": "Hello",
    "query-id": "1c4339cd-d53a-489e-85f3-50a14d1da658",
    "timestamp": 1697768070001,
    "custom": {
        "user-name": "Jane Doe"
    }
}
```

**Mindscript code Example**

The following code can be added to the <mark style="color:blue;">`Program Logic(Before/After)`</mark> of the Mind Expression.

```smalltalk
"Get HTTPHeader"
platform := self httpHeaders at: 'platform' ifAbsent: 'IOS'.

"Get HTTPBody"
userName := self httpRequestBody at: 'user-name' ifAbsent: 'John Doe'.
```

<figure><img src="/files/0g3jgbJjkrHQIY5WHiNp" alt=""><figcaption></figcaption></figure>

## Response

The Mind Expression API will return the list of response messages and the status code for the response.

<table data-header-hidden><thead><tr><th width="250"></th><th></th></tr></thead><tbody><tr><td><strong>description</strong></td><td>String of short description messages for the action</td></tr><tr><td><strong>code</strong></td><td>Status Code</td></tr><tr><td><strong>data</strong></td><td><mark style="color:blue;"><code>Message Object</code></mark> See details below.</td></tr></tbody></table>

## Status Codes

<table data-header-hidden><thead><tr><th width="164"></th><th></th></tr></thead><tbody><tr><td><p><strong>200</strong></p><p><strong>Ok</strong></p></td><td>Typical response for a message</td></tr><tr><td><p><strong>202</strong></p><p><strong>Created</strong></p></td><td>No Conversation ID was given. Message starts a conversation.</td></tr><tr><td><p><strong>204</strong></p><p><strong>Not classified</strong></p></td><td>The Mind Expression engine does not understand the message within the conversation configurations. Returns a fallback response.</td></tr><tr><td><p><strong>210</strong></p><p><strong>Empty input message</strong></p></td><td>The API call contains an empty string as a query.</td></tr><tr><td><p><strong>220</strong></p><p><strong>Conversation</strong> <strong>terminated</strong></p></td><td>The message and response ends the current conversation.</td></tr></tbody></table>

## Message Object

| **execution-time**      | Time in milliseconds it takes to execute the query.                                     |
| ----------------------- | --------------------------------------------------------------------------------------- |
| **timestamp**           | Time in UNIX Epoch when the query is executed.                                          |
| **query-id**            | ID of the query if sent by the user.                                                    |
| **conversation-id**     | Conversation ID of the message                                                          |
| **result - deprecated** | A list of response messages.                                                            |
| **channel-result**      | A list of <mark style="color:blue;">`Channel Message Object`</mark>. See details below. |

## Channel Message Object

<table data-header-hidden><thead><tr><th width="235"></th><th width="103.33333333333331"></th><th></th></tr></thead><tbody><tr><td><strong>channel-instruction</strong></td><td>Optional</td><td><mark style="color:blue;"><code>Template Object</code></mark> of instruction message</td></tr><tr><td><strong>channel-instruction-alt</strong></td><td>Optional</td><td><mark style="color:blue;"><code>Template Object</code></mark> of alternative instruction message that is guaranteed as text type in case the other specified type of message is not implemented.</td></tr><tr><td><strong>channel-message</strong></td><td></td><td><mark style="color:blue;"><code>Template Object</code></mark> of prompt message to obtain input</td></tr><tr><td><strong>channel-message-alt</strong></td><td>Optional</td><td><mark style="color:blue;"><code>Template Object</code></mark> of prompt instruction message to obtain that is guaranteed as text type in case the other specified type of message is not implemented.</td></tr></tbody></table>

## Template Object

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>channel-name</strong></td><td>Name of the message channel. Configurations for Mind Expression API on the subject settings correlate to the channel <mark style="color:blue;"><code>default</code></mark>.</td></tr><tr><td><strong>template-type</strong></td><td>Type of template message. One of <mark style="color:blue;"><code>text</code></mark> | <mark style="color:blue;"><code>card</code></mark> | <mark style="color:blue;"><code>quick_reply</code></mark> | <mark style="color:blue;"><code>image</code></mark> | <mark style="color:blue;"><code>code</code></mark> | <mark style="color:blue;"><code>free</code></mark></td></tr><tr><td><strong>template</strong></td><td>Required in case of <mark style="color:blue;"><code>text</code></mark> or <mark style="color:blue;"><code>code</code></mark>. String of content. In case of <mark style="color:blue;"><code>quick_reply</code></mark>, represent the prompt message.</td></tr><tr><td><strong>image-url</strong></td><td>Required in case of <mark style="color:blue;"><code>image</code></mark>. The url for the media</td></tr><tr><td><strong>upload-type</strong></td><td>Required in case of <mark style="color:blue;"><code>image</code></mark>. The type of media upload.</td></tr><tr><td><strong>quick-replies</strong></td><td>Required in case of <mark style="color:blue;"><code>quick_reply</code></mark>. A list of <mark style="color:blue;"><code>Quick Reply Objects</code></mark> buttons. See details below.</td></tr><tr><td><strong>card-list</strong></td><td>Required in case of <mark style="color:blue;"><code>card</code></mark>. A list of <mark style="color:blue;"><code>Card Objects</code></mark> response message. See details below.</td></tr></tbody></table>

## Quick Reply Object

<table data-header-hidden><thead><tr><th width="185"></th><th></th></tr></thead><tbody><tr><td><strong>label</strong></td><td>Button label of the quick reply button.</td></tr><tr><td><strong>message</strong></td><td>Required if type is <mark style="color:blue;"><code>message</code></mark>. Message that will be sent as reply when the button is pressed.</td></tr><tr><td><strong>type</strong></td><td>Type of action taken when the button is pressed. One of <mark style="color:blue;"><code>link</code></mark> | <mark style="color:blue;"><code>message</code></mark></td></tr><tr><td><strong>image-url</strong></td><td>Image that will be added to the button.</td></tr><tr><td><strong>url</strong></td><td>Required if type is <mark style="color:blue;"><code>link</code></mark>. The link that the user will be directed when the button is pressed.</td></tr></tbody></table>

## Card Object

<table data-header-hidden><thead><tr><th width="133"></th><th></th></tr></thead><tbody><tr><td><strong>title</strong></td><td>Required. Title of the card object.</td></tr><tr><td><strong>sub-title</strong></td><td>Sub-title of the card object.</td></tr><tr><td><strong>image-url</strong></td><td>URL of the image to be shown in the card.</td></tr><tr><td><strong>buttons</strong></td><td>A list of <mark style="color:blue;"><code>Button Objects</code></mark>. See details below.</td></tr></tbody></table>

## Button Object

<table data-header-hidden><thead><tr><th width="173"></th><th></th></tr></thead><tbody><tr><td><strong>button-type</strong></td><td>Type of action taken when the button is pressed. One of <mark style="color:blue;"><code>link</code></mark> | <mark style="color:blue;"><code>message</code></mark></td></tr><tr><td><strong>label</strong></td><td>Button label.</td></tr><tr><td><strong>link</strong></td><td>Required if <strong>button-type</strong> is <mark style="color:blue;"><code>link</code></mark>. The URL user will be redirected on button press.</td></tr><tr><td><strong>message</strong></td><td>Required if <strong>button-type</strong> is <mark style="color:blue;"><code>message</code></mark>. The message that will be sent as reply when the button is pressed.</td></tr></tbody></table>

## Examples

### Handshaking Request Example

**Request Header**

{% code lineNumbers="true" %}

```
“Authorization”: “bWluZC1haTpyZWFsam9obmRvZQ==”
“X-Conversation-Id”: NULL
“UUID”: “cab64bcd-9e97-424e-b786-30b617615e02”
```

{% endcode %}

**Request Payload**

{% code lineNumbers="true" %}

```
{
    "query": null,
    "query-id": "1c4339cd-d53a-489e-85f3-50a14d1da658",
    "timestamp": 1676943114143
}
```

{% endcode %}

### Response Example

{% code lineNumbers="true" %}

```
{
    "description": "Created",
    "code": 202,
    "data": {
        "channel-result": null,
        "result": [
            "Hello, how may I help you?"
        ],
        "execution-time": 79,
        "timestamp": 1676940742565,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c"
    }
}
```

{% endcode %}

### Handshaking with Input Query Example

**Request Header**

{% code lineNumbers="true" %}

```
“Authorization”: “bWluZC1haTpyZWFsam9obmRvZQ==”
“X-Conversation-Id”: NULL
“UUID”: “cab64bcd-9e97-424e-b786-30b617615e02”
```

{% endcode %}

**Request Payload**

{% code lineNumbers="true" %}

```
{
    "query": "Hello",
    "query-id": "1c4339cd-d53a-489e-85f3-50a14d1da658",
    "timestamp": 1676943114143
}
```

{% endcode %}

### Response Example

{% code lineNumbers="true" %}

```
{
    "description": "Created",
    "code": 202,
    "data": {
        "channel-result": [
            {
                "channel-message": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hello from Mind Expression",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-message-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hi there",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            }
        ],
        "result": [
            ""
        ],
        "execution-time": 79,
        "timestamp": 1676940742565,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c"
    }
}
```

{% endcode %}

### Normal Conversation Example

**Request Header**

{% code lineNumbers="true" %}

```
“Authorization”: “bWluZC1haTpyZWFsam9obmRvZQ==”
“X-Conversation-Id”: “4355d048-2438-405d-aac5-c04ce7086dcf”
“UUID”: “cab64bcd-9e97-424e-b786-30b617615e02”
```

{% endcode %}

**Request Payload**

{% code lineNumbers="true" %}

```
{
    "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
    "query": "Can I upgrade my mobile package?",
    "timestamp": 1615862988000
}
```

{% endcode %}

### Response Example

{% code lineNumbers="true" %}

```
{
    "description": "Created",
    "code": 202,
    "data": {
        "channel-result": [
            {
                "channel-message": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hello from Mind Expression",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-message-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hi there",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            }
        ],
        "result": [
            ""
        ],
        "execution-time": 79,
        "timestamp": 1676940742565,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c"
    }
}
```

{% endcode %}

### Response Example (with Quick Reply)

{% code lineNumbers="true" %}

```
{
    "description": "Created",
    "code": 202,
    "data": {
        "channel-result": [
            {
                "channel-message": {
                    "channel-name": "default",
                    "template-type": "quick_reply",
                    "template": "How are you today?",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [
                        {
                            "label": "Good",
                            "message": "I'm good, thanks.",
                            "type": "message",
                            "image-url": null,
                            "url": null
                        },
                        {
                            "label": "Not good",
                            "message": "Not so good, I'm afraid.",
                            "type": "message",
                            "image-url": null,
                            "url": null
                        }
                    ],
                    "card-list": []
                },
                "channel-message-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hello from Mind Expression.",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            }
        ],
        "result": [
            ""
        ],
        "execution-time": 79,
        "timestamp": 1676945014202,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "527998fc-f03c-47fd-9b7a-0624d5f341f0"
    }
}
```

{% endcode %}

### Response Example (with Card)

{% code lineNumbers="true" %}

```
{
    "description": "Ok",
    "code": 200,
    "data": {
        "channel-result": [
            {
                "channel-message": {
                    "template-type": null,
                    "template": "",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": [],
                    "channels": []
                },
                "channel-message-alt": {
                    "channels": []
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "card",
                    "template": "",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": [
                        {
                            "title": "Welcome to Mind Expression",
                            "sub-title": "This is an example subtitle.",
                            "image-url": "https://mind-expression.s3.amazonaws.com/builder/dev/QlXUT7-1SpOQQH7IUavSOw_mind_intro_poster_20200101.jpg",
                            "buttons": [
                                {
                                    "button-type": "link",
                                    "label": "Go to Website",
                                    "link": "https://mindx.mind.ai",
                                    "message": null
                                }
                            ]
                        }
                    ]
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            },
            {
                "channel-message": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Would you like to buy some?",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-message-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": null,
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            }
        ],
        "result": [
            ""
        ],
        "execution-time": 38,
        "timestamp": 1676945335480,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "527998fc-f03c-47fd-9b7a-0624d5f341f0"
    }
}
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mind-expression-docs.gitbook.io/home/reference/api-docs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.