Endpoints

In this section we will go over all possible endpoints of murai API. Please note that desired flow for the API usage is:

Create chat. Create chat ID and hello message.
Query chat history. Obtain last created message.
Ask chatbot new questions. Ask chat bot a question.

If the chat already exists and the user has already exchanged some questions with the chatbot we advise that you save users chat sessions and continue them by querying chat history and asking new questions in the same chat context.

A good option would also be to connect your internal users with their chats and then obtain their chat sessions.

API is divided in two parts - Chatbot general API and Chatbot answers API.

Chatbot general API

Chatbot general API takes care of session creation (chat), obtaining chatbot's general information and message history querying. API is available on the following URL:

API URL
https://api.murai.ai

Get chatbot details

Returns chatbot's and workspace's details and settings.

GET /details

Response

Name	Type	Description
chatBotName	`string`	Chatbot's name.
chatBotDescription	`string`	Chatbot's description.
workspaceName	`string`	Workspace's name.

curl --location --request GET "https://api.murai.ai/details" \
--header "x-api-key: {API_KEY}" \
--header "Content-Type: application/json" \

{
  "status": 200,
  "data": {
    "chatBotName": "Chatbot #1",
    "chatBotDescription": "My first awesome chatbot!",
    "workspaceName": "My Workspace",
  }
}

Create chat

Creates new chat which can be used in further conversations with the chatbot.

POST /chats

Body fields

Name	Type	Description	Required
name	`string`	Name of the chat.	false
userRef	`string`	User reference - You can use this field to reference users using your services with their chats. Length of user reference can be up to `60` characters.	false

Response

Name	Type	Description
id	`integer`	ID of the created chat.
name	`string`	Name of the created chat.
userRef	`string`	User reference.
_createTime	`DateTime`	Time of chat creation.

Obtained chat id value can be used to obtain chat history and to ask chatbot new questions in the same chat context. If the hello message is enabled in chatbot's settings a chat history entry will be crated using the selected hello message. You can obtain the hello message by querying chat's history with the obtained id. You can set your desired hello message in the chatbot settings on the murai admin platformopen in new window.

curl --location --request POST "https://api.murai.ai/chats" \
--header "x-api-key: {API_KEY}" \
--header "Content-Type: application/json" \
--data-raw "{
    \"name\": "New chat",
    \"userRef\": "user-123-reference"
}"

{
  "status": 201,
  "data": {
    "id": 14,
    "name": "New chat",
    "userRef": "user-123-reference",
    "_createTime": "2023-03-23T17:59:29.000Z",
  }
}

Get chats

Returns created chats.

GET /chats

Query parameters

Name	Type	Description	Required
search	`string`	If this parameter is present it will be used to perform text search over the `name` properties of the chats.	false
userRef	`string`	If this parameter is present only chats with the given `userRef` will be returned.	false
limit	`integer`	Number of items that will be returned. Defaults to `25` with maximum value of `100`.	false
page	`integer`	Current page of returned items. Defaults to `1` and should be greater than `0`. Each page contains number of items specified by the `limit` parameter.	false
orderBy	`string` or `string[]`	Field to sort the response by. If multiple fields are given in an array the response will be sorted by those fields by their order (first the response is sorted by the first field, then the second, third, etc.). Default to `[id]` and can contain any of the returned fields in the response.	false
desc	`string` or `string[]`	Field that tells if the response should be ordered in the descending order - `true` or `false` string value. If `orderBy` parameter includes multiple fields this parameter should include their corresponding values.	false
id	`integer`	If this parameter is present only the entity with this `id` will be returned.	false

Response

Response is divided into two separate objects data and meta. Each object in the data array has the following properties:

Name	Type	Description
id	`integer`	ID of the chat.
name	`string`	Name of the chat.
userRef	`string`	Name of the chat.
_createTime	`DateTime`	Time of chat creation.

And the meta object has the following properties:

Name	Type	Description
total	`integer`	Number of total chats.

curl --location --request GET "https://api.murai.ai/chats" \
--header "x-api-key: {API_KEY}" \
--header "Content-Type: application/json" \

{
  "status": 200,
  "data": [
    {
      "id": 14,
      "name": "New chat",
      "userRef": "user-123-reference",
      "_createTime": "2023-03-23T17:59:29.000Z",
    },
    {
      "id": 13,
      "name": "Old chat",
      "userRef": "user-123-reference",
      "_createTime": "2023-03-22T13:51:49.000Z",
    },
    {
      "id": 12,
      "name": "Older chat",
      "userRef": "user-123-reference",
      "_createTime": "2023-03-21T13:34:22.000Z",
    }
  ],
  "meta": {
    "total": 3
  }
}

Get chat history

Returns chat history for the given chat.

GET /chats/:chat_id/history

Path parameters

Name	Type	Description	Required
chat_id	`integer`	Chat's ID for which we are querying history.	true

Query parameters

Name	Type	Description	Required
limit	`integer`	Number of items that will be returned. Defaults to `25` with maximum value of `100`.	false
page	`integer`	Current page of returned items. Defaults to `1` and should be greater than `0`. Each page contains number of items specified by the `limit` parameter.	false
orderBy	`string` or `string[]`	Field to sort the response by. If multiple fields are given in an array the response will be sorted by those fields by their order (first the response is sorted by the first field, then the second, third, etc.). Default to `[id]` and can contain any of the returned fields in the response.	false
desc	`string` or `string[]`	Field that tells if the response should be ordered in the descending order - `true` or `false` string value. If `orderBy` parameter includes multiple fields this parameter should include their corresponding values.	false
id	`integer`	If this parameter is present only the entity with this `id` will be returned.	false

Response

Response is divided into two separate objects data and meta. Each object in the data array has the following properties:

Name	Type	Description
id	`integer`	ID of the chat history entry.
chat_id	`integer`	ID of the chat.
question	`string`	User's question.
answer	`string`	Chatbot's answer.
moderation	`string`	Moderation value. You can learn more about the moderation values in Moderation section.
flagged	`boolean`	If the user's question is marked as flagged (`true` value) it violates our usage policy and the general moderation error message will be returned. You can set your personal moderation error message in chatbot setting on the murai platformopen in new window.
_createTime	`DateTime`	Time of chat history creation.

And the meta object has the following properties:

Name	Type	Description
total	`integer`	Number of total items in chat history for the given chat.

curl --location --request GET "https://api.murai.ai/chats/14/history" \
--header "x-api-key: {API_KEY}" \
--header "Content-Type: application/json" \

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "chat_id": 14,
      "question": "Hello!",
      "answer": "Hello! How can I assist you today?",
      "moderation": "none",
      "flagged": false,
      "_createTime": "2023-03-23T18:00:41.000Z",
    },
    {
      "id": 2,
      "chat_id": 14,
      "question": "Who are you?",
      "answer": "I am an AI Assistant, a helpful assistant who can help you with your questions.",
      "moderation": "none",
      "flagged": false,
      "_createTime": "2023-03-23T18:01:32.000Z",
    },
    {
      "id": 3,
      "chat_id": 14,
      "question": "Hello!",
      "answer": "Hello! How can I assist you today?",
      "moderation": "none",
      "flagged": false,
      "_createTime": "2023-03-23T18:01:54.000Z",
    }
  ],
  "meta": {
    "total": 3
  }
}

Chatbot answers API

Chatbot answers API takes care of giving asking the questions to the chatbots and obtaining the answers from them. API is available on the following URL:

API URL
https://ask-api.murai.ai

Ask chatbot a question

Asks chatbot a new question. Returns new chat history entry with chatbot's response to the user's query.

POST /

Body parameters

Name	Type	Description	Required
chat_id	`number`	ID of the current chat.	false
query	`string`	Users question or instruction for the chatbot. Length of user's query can be up to `200` characters.	true

If chat_id parameter is not present, new chat will be created automatically and new chat_id will be returned in the response. We advise that you should first create a new chat using the create chat route to obtain the proper hello message from the chatbot settings.

Response

Response is a new chat history entry with chatbot's response to the user's query.

Name	Type	Description
id	`integer`	ID of the chat history entry.
chat_id	`integer`	ID of the chat.
question	`string`	User's question.
answer	`string`	chatbot's answer.
moderation	`string`	Moderation value. You can learn more about the moderation values in Moderation section.
flagged	`boolean`	If the user's question is marked as flagged (`true` value) it violates our usage policy and the general moderation error message will be returned. You can set your personal moderation error message in chatbot setting on the murai platformopen in new window.
_createTime	`DateTime`	Time of chat history creation.

curl --location --request POST "https://ask-api.murai.ai" \
--header "x-api-key: {API_KEY}" \
--header "Content-Type: application/json" \
--data-raw "{
    \"chat_id\": 14,
    \"query\": "Who is Elon Musk?"
}"

{
  "status": 201,
  "data": {
    "id": 4,
    "chat_id": 14,
    "question": "Who is Elon Musk?",
    "answer": "Elon Musk is a well-known entrepreneur and business magnate. He is the CEO of SpaceX and Tesla, Inc. and has also been involved in other successful ventures such as PayPal and SolarCity.",
    "moderation": "none",
    "flagged": false,
    "_createTime": "2023-03-23T18:02:21.000Z",
  }
}

# Endpoints

# Chatbot general API

# Get chatbot details

# GET /details

# Response

# Create chat

# POST /chats

# Body fields

# Response

# Get chats

# GET /chats

# Query parameters

# Response

# Get chat history

# GET /chats/:chat_id/history

# Path parameters

# Query parameters

# Response

# Chatbot answers API

# Ask chatbot a question

# POST /

# Body parameters

# Response

Endpoints

Chatbot general API

Get chatbot details

GET /details

Response

Create chat

POST /chats

Body fields

Response

Get chats

GET /chats

Query parameters

Response

Get chat history

GET /chats/:chat_id/history

Path parameters

Query parameters

Response

Chatbot answers API

Ask chatbot a question

POST /

Body parameters

Response