Conversations

Conversation, category, and category element related APIs

List Conversations

get

/webapi/v2/conversations

This API allows you to list conversations sorted by last chat time in descending order.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Query Parameters

• userIds (array[string], optional): Filter by user IDs.

• llmAppId (string, optional): Filter by LLM app ID.

• categoryId (string, optional): Filter by category ID.

• searchTerm (string, optional): Search term to filter conversations.

• startedAt (number, optional): Filter by last chat time after this timestamp.

• endAt (number, optional): Filter by last chat time before this timestamp.

• firstChatStartedAt (number, optional): Filter by first chat time after this timestamp.

• firstChatEndAt (number, optional): Filter by first chat time before this timestamp.

• activeOnly (boolean, optional): If true, only active conversations. Defaults to false.

• backgroundRunning (boolean, optional): Filter by background running status.

• variables (array[string], optional): Variable names to include in the response.

• pageSize (integer, optional): Number of results per page. Defaults to 50.

• cursor (string, optional): Cursor for pagination.

• order (string, optional): Sort order. Defaults to LAST_CHAT_TIME_DESC.

Authorizations

API-KEYstringRequired

Your API key for authentication

Query parameters

llmAppIdstring · nullableOptional

Global ID of the LLM app to filter by.

categoryIdstring · nullableOptional

Global ID of the conversation category to filter by.

startedAtnumber · nullableOptional

Search for last chat time after this value

endAtnumber · nullableOptional

Search for last chat time before this value

firstChatStartedAtnumber · nullableOptional

Search for first chat time after this value

firstChatEndAtnumber · nullableOptional

Search for first chat time before this value

searchTermstring · nullableOptional

Text matched against chat messages of the conversation.

cursorstring · nullableOptional

Pagination cursor returned by the previous page. None requests the first page.

variablesstring[] · nullableOptional

Names of the project variables to include in each conversation.

pageSizeinteger · min: 1 · max: 50Optional

Number of conversations per page, from 1 to 50.

Default: 50

activeOnlybooleanOptional

True returns only conversations that are not in an end state.

Default: false

backgroundRunningboolean · nullableOptional

True returns only conversations that run in the background. False and None apply no filter.

orderstring · enumOptionalPossible values:

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Responses

200

OK

application/json

cursorstring · nullableRequired

Cursor for pagination

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

get/webapi/v2/conversations

GET /webapi/v2/conversations HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Accept: */*

{
  "conversations": [
    {
      "id": "text",
      "title": "text",
      "user": {
        "userId": "text",
        "firstName": "text",
        "lastName": "text"
      },
      "createdAt": 1,
      "lastChatTime": 1,
      "isEnd": true,
      "categories": [
        "text"
      ],
      "memo": "text",
      "chats": [
        {
          "id": "text",
          "type": "text",
          "sender": "USER",
          "message": "text",
          "source": {
            "knowledgeBaseIds": [
              "text"
            ],
            "folderIds": [
              "text"
            ],
            "webSites": [
              "text"
            ],
            "searchAllSharedDocument": false,
            "searchAllPersonalDocument": false,
            "includingHashtags": [
              "text"
            ],
            "excludingHashtags": [
              "text"
            ],
            "includingHashtagsOperator": "text",
            "excludingHashtagsOperator": "text",
            "sharedKnowledgeBases": [
              {
                "id": "text",
                "name": "text"
              }
            ],
            "sharedFolders": [
              {
                "id": "text",
                "name": "text"
              }
            ],
            "personalKnowledgeBases": [
              {
                "id": "text",
                "name": "text"
              }
            ],
            "personalFolders": [
              {
                "id": "text",
                "name": "text"
              }
            ]
          },
          "timestamp": 1,
          "completed": true,
          "citations": [
            {
              "clueId": "text",
              "source": "text",
              "title": "text",
              "url": "text",
              "text": "text"
            }
          ],
          "rating": true,
          "agentRating": true
        }
      ],
      "chatCount": 1,
      "llmApp": {
        "id": "text",
        "name": "text",
        "description": "text"
      },
      "variables": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "cursor": "text"
}

Bulk Update Conversations

post

/webapi/v2/conversations/bulk_update

This API allows you to update state, assignee, title, or categories for multiple conversations at once.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Request Body

• conversationIds (array[string], optional): Filter by conversation IDs.

• userIds (array[string], optional): Filter by user IDs.

• llmAppIds (array[string], optional): Filter by LLM app IDs.

• categoryIds (array[string], optional): Filter by category IDs.

• conversationInfo (object, required): Update payload with state, assignee, categoryIds, and title fields.

Authorizations

API-KEYstringRequired

Your API key for authentication

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Body

userIdsstring[] · nullableOptional

The ID of the user for filtering

llmAppIdsstring[] · nullableOptional

The ID of the llm app for filtering

categoryIdsstring[] · nullableOptional

The ID of the conversation category for filtering

conversationIdsstring[] · nullableOptional

The ID of the conversation for filtering

Responses

200

OK

No content

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

post/webapi/v2/conversations/bulk_update

POST /webapi/v2/conversations/bulk_update HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "userIds": [
    "text"
  ],
  "llmAppIds": [
    "text"
  ],
  "categoryIds": [
    "text"
  ],
  "conversationIds": [
    "text"
  ],
  "conversationInfo": {
    "state": "no",
    "assignee": "text",
    "categoryIds": [
      "text"
    ],
    "title": "text"
  }
}

No content

Get Conversation

get

/webapi/v2/conversations/{conversation_id}

This API allows you to retrieve a conversation. The chats provided are the most recent 20.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Query Parameters

• variables (array[string], optional): Comma-separated list of variable names to include in the response.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_idstringRequired

Query parameters

variablesstring[] · nullableOptional

Comma separated list of variables to include in the response

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Responses

200

OK

application/json

idstringRequired

Unique ID of the conversation

titlestringRequired

Title of the conversation

createdAtnumberRequired

Conversation created time

lastChatTimenumber · nullableRequired

Conversation last chat time

isEndbooleanRequired

Conversation is completed or not

categoriesstring[] · nullableRequired

Conversation categories

memostring · nullableRequired

Conversation memo

chatCountintegerRequired

Total chat count

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

get/webapi/v2/conversations/{conversation_id}

GET /webapi/v2/conversations/{conversation_id} HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "title": "text",
  "user": {
    "userId": "text",
    "firstName": "text",
    "lastName": "text"
  },
  "createdAt": 1,
  "lastChatTime": 1,
  "isEnd": true,
  "categories": [
    "text"
  ],
  "memo": "text",
  "chats": [
    {
      "id": "text",
      "type": "text",
      "sender": "USER",
      "message": "text",
      "source": {
        "knowledgeBaseIds": [
          "text"
        ],
        "folderIds": [
          "text"
        ],
        "webSites": [
          "text"
        ],
        "searchAllSharedDocument": false,
        "searchAllPersonalDocument": false,
        "includingHashtags": [
          "text"
        ],
        "excludingHashtags": [
          "text"
        ],
        "includingHashtagsOperator": "text",
        "excludingHashtagsOperator": "text",
        "sharedKnowledgeBases": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "sharedFolders": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "personalKnowledgeBases": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "personalFolders": [
          {
            "id": "text",
            "name": "text"
          }
        ]
      },
      "timestamp": 1,
      "completed": true,
      "citations": [
        {
          "clueId": "text",
          "source": "text",
          "title": "text",
          "url": "text",
          "text": "text"
        }
      ],
      "rating": true,
      "agentRating": true
    }
  ],
  "chatCount": 1,
  "llmApp": {
    "id": "text",
    "name": "text",
    "description": "text"
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Update Conversation

patch

/webapi/v2/conversations/{conversation_id}

This API allows you to partially update a conversation's state, assignee, title, or categories.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Request Body

• state (string, optional): The conversation state.

• assignee (string, optional): The assignee agent ID.

• categoryIds (array[string], optional): Category IDs to assign.

• title (string, optional): The conversation title.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_idstringRequired

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Body

statestring · enum · nullableOptional

The state of the conversation

Possible values:

assigneestring · nullableOptional

The assignee of the conversation

categoryIdsstring[] · nullableOptional

The ID of the category

titlestring · nullableOptional

The title of the conversation

Responses

200

OK

application/json

idstringRequired

Unique ID of the conversation

titlestringRequired

Title of the conversation

createdAtnumberRequired

Conversation created time

lastChatTimenumber · nullableRequired

Conversation last chat time

isEndbooleanRequired

Conversation is completed or not

categoriesstring[] · nullableRequired

Conversation categories

memostring · nullableRequired

Conversation memo

chatCountintegerRequired

Total chat count

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

patch/webapi/v2/conversations/{conversation_id}

PATCH /webapi/v2/conversations/{conversation_id} HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 70

{
  "state": "no",
  "assignee": "text",
  "categoryIds": [
    "text"
  ],
  "title": "text"
}

{
  "id": "text",
  "title": "text",
  "user": {
    "userId": "text",
    "firstName": "text",
    "lastName": "text"
  },
  "createdAt": 1,
  "lastChatTime": 1,
  "isEnd": true,
  "categories": [
    "text"
  ],
  "memo": "text",
  "chats": [
    {
      "id": "text",
      "type": "text",
      "sender": "USER",
      "message": "text",
      "source": {
        "knowledgeBaseIds": [
          "text"
        ],
        "folderIds": [
          "text"
        ],
        "webSites": [
          "text"
        ],
        "searchAllSharedDocument": false,
        "searchAllPersonalDocument": false,
        "includingHashtags": [
          "text"
        ],
        "excludingHashtags": [
          "text"
        ],
        "includingHashtagsOperator": "text",
        "excludingHashtagsOperator": "text",
        "sharedKnowledgeBases": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "sharedFolders": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "personalKnowledgeBases": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "personalFolders": [
          {
            "id": "text",
            "name": "text"
          }
        ]
      },
      "timestamp": 1,
      "completed": true,
      "citations": [
        {
          "clueId": "text",
          "source": "text",
          "title": "text",
          "url": "text",
          "text": "text"
        }
      ],
      "rating": true,
      "agentRating": true
    }
  ],
  "chatCount": 1,
  "llmApp": {
    "id": "text",
    "name": "text",
    "description": "text"
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

List Conversation Chats

get

/webapi/v2/conversations/{conversation_id}/chats

This API allows you to list chats in a conversation, sorted by timestamp in ascending order. Page size is 100.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Query Parameters

• pageNo (integer, optional): Page number for pagination. Defaults to 1.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_idstringRequired

Query parameters

pageNointeger · min: 1OptionalDefault: 1

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Responses

200

OK

application/json

pageNointegerRequired

1-based page number of this response. A page holds up to 100 chats.

totalCountintegerRequired

Total number of visible chats in the conversation.

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

get/webapi/v2/conversations/{conversation_id}/chats

GET /webapi/v2/conversations/{conversation_id}/chats HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Accept: */*

{
  "chats": [
    {
      "id": "text",
      "type": "text",
      "sender": "USER",
      "message": "text",
      "source": {
        "knowledgeBaseIds": [
          "text"
        ],
        "folderIds": [
          "text"
        ],
        "webSites": [
          "text"
        ],
        "searchAllSharedDocument": false,
        "searchAllPersonalDocument": false,
        "includingHashtags": [
          "text"
        ],
        "excludingHashtags": [
          "text"
        ],
        "includingHashtagsOperator": "text",
        "excludingHashtagsOperator": "text",
        "sharedKnowledgeBases": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "sharedFolders": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "personalKnowledgeBases": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "personalFolders": [
          {
            "id": "text",
            "name": "text"
          }
        ]
      },
      "timestamp": 1,
      "completed": true,
      "citations": [
        {
          "clueId": "text",
          "source": "text",
          "title": "text",
          "url": "text",
          "text": "text"
        }
      ],
      "rating": true,
      "agentRating": true
    }
  ],
  "pageNo": 1,
  "totalCount": 1
}

Get Conversation Running Status

get

/webapi/v2/conversations/{conversation_id}/running

This API allows you to check whether a conversation is currently running in the background.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_idstringRequired

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Responses

200

OK

application/json

isRunningbooleanRequired

Backgound running status

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

get/webapi/v2/conversations/{conversation_id}/running

GET /webapi/v2/conversations/{conversation_id}/running HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Accept: */*

{
  "isRunning": true
}

Stop Conversation

post

/webapi/v2/conversations/{conversation_id}/stop

This API allows you to stop a running conversation.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_idstringRequired

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Responses

200

OK

application/json

isRunningbooleanRequired

Backgound running status

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

post/webapi/v2/conversations/{conversation_id}/stop

POST /webapi/v2/conversations/{conversation_id}/stop HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Accept: */*

{
  "isRunning": true
}

Get Chat

get

/webapi/v2/conversations/{conversation_id}/chats/{chat_id}

This API allows you to retrieve a specific chat by ID from a conversation.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_idstringRequired

chat_idstringRequired

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Responses

200

OK

application/json

Detailed chat information compatible with LLMResponse for run_apps API response verification.

Extends Chat with additional fields for verifying streaming responses from run_apps API.

idstringRequired

Unique ID of the chat

typestring · nullableOptional

Node type of the chat

senderstringRequired

Sender Type

Example: USER

messagestringRequired

Chat message

timestampnumberRequired

Timestamp of the chat message creation time

completedbooleanRequired

Whether the chat generation is completed

ratingboolean · nullableRequired

Rating of the chat

agentRatingboolean · nullableRequired

Agent rating of the chat

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

get/webapi/v2/conversations/{conversation_id}/chats/{chat_id}

GET /webapi/v2/conversations/{conversation_id}/chats/{chat_id} HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "type": "text",
  "sender": "USER",
  "message": "text",
  "source": {
    "knowledgeBaseIds": [
      "text"
    ],
    "folderIds": [
      "text"
    ],
    "webSites": [
      "text"
    ],
    "searchAllSharedDocument": false,
    "searchAllPersonalDocument": false,
    "includingHashtags": [
      "text"
    ],
    "excludingHashtags": [
      "text"
    ],
    "includingHashtagsOperator": "text",
    "excludingHashtagsOperator": "text",
    "sharedKnowledgeBases": [
      {
        "id": "text",
        "name": "text"
      }
    ],
    "sharedFolders": [
      {
        "id": "text",
        "name": "text"
      }
    ],
    "personalKnowledgeBases": [
      {
        "id": "text",
        "name": "text"
      }
    ],
    "personalFolders": [
      {
        "id": "text",
        "name": "text"
      }
    ]
  },
  "timestamp": 1,
  "completed": true,
  "citations": [
    {
      "clueId": "text",
      "source": "text",
      "title": "text",
      "url": "text",
      "text": "text"
    }
  ],
  "rating": true,
  "agentRating": true,
  "intermediateSteps": [
    {
      "key": "text",
      "createdAt": 1,
      "completed": true,
      "statusMessage": "text",
      "markdownMessage": "text"
    }
  ]
}

Delete Chat

delete

/webapi/v2/conversations/{conversation_id}/chats/{chat_id}

This API allows you to delete a specific chat message from a conversation.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_idstringRequired

chat_idstringRequired

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Responses

200

OK

No content

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

delete/webapi/v2/conversations/{conversation_id}/chats/{chat_id}

DELETE /webapi/v2/conversations/{conversation_id}/chats/{chat_id} HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Accept: */*

No content

Update Conversation Title

put

/webapi/v2/conversations/{conversation_id}/title

This API allows you to set a conversation title.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Request Body

• title (string, required): The new title for the conversation.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_idstringRequired

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Body

titlestringRequired

The title of the conversation

Responses

200

OK

application/json

idstringRequired

Unique ID of the conversation

titlestringRequired

Title of the conversation

createdAtnumberRequired

Conversation created time

lastChatTimenumber · nullableRequired

Conversation last chat time

isEndbooleanRequired

Conversation is completed or not

categoriesstring[] · nullableRequired

Conversation categories

memostring · nullableRequired

Conversation memo

chatCountintegerRequired

Total chat count

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

put/webapi/v2/conversations/{conversation_id}/title

PUT /webapi/v2/conversations/{conversation_id}/title HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "title": "text"
}

{
  "id": "text",
  "title": "text",
  "user": {
    "userId": "text",
    "firstName": "text",
    "lastName": "text"
  },
  "createdAt": 1,
  "lastChatTime": 1,
  "isEnd": true,
  "categories": [
    "text"
  ],
  "memo": "text",
  "chats": [
    {
      "id": "text",
      "type": "text",
      "sender": "USER",
      "message": "text",
      "source": {
        "knowledgeBaseIds": [
          "text"
        ],
        "folderIds": [
          "text"
        ],
        "webSites": [
          "text"
        ],
        "searchAllSharedDocument": false,
        "searchAllPersonalDocument": false,
        "includingHashtags": [
          "text"
        ],
        "excludingHashtags": [
          "text"
        ],
        "includingHashtagsOperator": "text",
        "excludingHashtagsOperator": "text",
        "sharedKnowledgeBases": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "sharedFolders": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "personalKnowledgeBases": [
          {
            "id": "text",
            "name": "text"
          }
        ],
        "personalFolders": [
          {
            "id": "text",
            "name": "text"
          }
        ]
      },
      "timestamp": 1,
      "completed": true,
      "citations": [
        {
          "clueId": "text",
          "source": "text",
          "title": "text",
          "url": "text",
          "text": "text"
        }
      ],
      "rating": true,
      "agentRating": true
    }
  ],
  "chatCount": 1,
  "llmApp": {
    "id": "text",
    "name": "text",
    "description": "text"
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Submit Chat Feedback

post

/webapi/v2/conversations/{conversation_id}/chats/{chat_id}/feedback

This API allows you to submit a thumbs-up or thumbs-down feedback on a generated chat response.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Request Body

• rating (boolean, optional): true for positive, false for negative feedback.

• feedbackSelection (array[string], optional): Predefined feedback selection options.

• suggestedAnswer (string, optional): A user-suggested better answer.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_idstringRequired

chat_idstringRequired

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Body

ratingboolean · nullableOptional

The rating of chat

suggestedAnswerstring · nullableOptional

The suggested answer

Responses

200

OK

application/json

conversationIdstringRequired

Global ID of the conversation, as sent in the request path.

chatIdstringRequired

Global ID of the chat, as sent in the request path.

ratingboolean · nullableOptional

Submitted rating: true is positive, false is negative. None when no rating is sent.

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

post/webapi/v2/conversations/{conversation_id}/chats/{chat_id}/feedback

POST /webapi/v2/conversations/{conversation_id}/chats/{chat_id}/feedback HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "rating": true,
  "feedbackSelection": [
    "not_relevant"
  ],
  "suggestedAnswer": "text"
}

{
  "conversationId": "text",
  "chatId": "text",
  "rating": true
}

List Conversation Categories

get

/webapi/v2/conversation_categories

This API allows you to list all conversation categories in the project.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Authorizations

API-KEYstringRequired

Your API key for authentication

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Responses

200

OK

application/json

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

get/webapi/v2/conversation_categories

GET /webapi/v2/conversation_categories HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Accept: */*

{
  "categories": [
    {
      "categoryId": "text",
      "name": "text"
    }
  ]
}

Create Conversation Category

post

/webapi/v2/conversation_categories

This API allows you to create a new conversation category.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Request Body

• name (string, required): The name of the conversation category.

Authorizations

API-KEYstringRequired

Your API key for authentication

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Body

namestringRequired

Name of the new conversation category.

Responses

200

OK

application/json

categoryIdstringRequired

Unique ID of the category

namestringRequired

Name of the category

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

post/webapi/v2/conversation_categories

POST /webapi/v2/conversation_categories HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

{
  "categoryId": "text",
  "name": "text"
}

Delete Conversation Category

delete

/webapi/v2/conversation_categories/{conversation_category_id}

This API allows you to delete a conversation category by ID.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Authorizations

API-KEYstringRequired

Your API key for authentication

Path parameters

conversation_category_idstringRequired

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Responses

200

OK

No content

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

delete/webapi/v2/conversation_categories/{conversation_category_id}

DELETE /webapi/v2/conversation_categories/{conversation_category_id} HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Accept: */*

No content

Chat Completions

post

/webapi/v2/chat/completions

This API allows you to make a direct LLM call without retrieval. Routes through Mally's LLM infrastructure for model routing and billing. Supports both sync and streaming modes.

Headers

• API-KEY (string, required): Your assigned API key. You can find it in the Settings menu of the dashboard.

• AGENT-EMAIL (string, optional): The email address of the agent performing the API call.

• USER-EMAIL (string, optional): The email address to associate with the user.

• OWN-USER-ID (string, optional): The user ID to identify or create a user.

Request Body

• messages (array[object], required): Conversation messages, each with role and content.

• model (string, optional): LLM model name. Defaults to gpt4_o.

• temperature (number, optional): Sampling temperature. Defaults to 0.3.

• mode (string, optional): Must be sync or stream. Defaults to sync.

• max_tokens (integer, optional): Maximum completion tokens. Defaults to 2048.

Authorizations

API-KEYstringRequired

Your API key for authentication

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Body

modelstringOptional

LLM model name (Mally internal name)

Default: gpt4_o

temperaturenumberOptional

Sampling temperature

Default: 0.3

modestring · enumOptional

sync or stream

Default: syncPossible values:

max_tokensintegerOptional

Max completion tokens

Default: 2048

Responses

200

OK

No content

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

post/webapi/v2/chat/completions

POST /webapi/v2/chat/completions HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "messages": [
    {
      "role": "system",
      "content": "text"
    }
  ],
  "model": "gpt4_o",
  "temperature": 0.3,
  "mode": "sync",
  "max_tokens": 2048
}

No content

Daily Conversation Count

get

/webapi/conversation_daily_count

The total number of conversations per day for a given range.

Authorizations

API-KEYstringRequired

Your API key for authentication

Header parameters

AGENT-EMAILstringOptional

Optional: Email of the agent to use for this request

USER-EMAILstringOptional

Optional: Email address to associate with the user

OWN-USER-IDstringOptional

Optional: User ID to identify or create a user

Body

startDatestringOptional

Start of range of dates to query in YYYY-MM-DD format.

endDatestringOptional

End of range of dates to query in YYYY-MM-DD format.

Responses

200

Successfully retrieved daily conversation count

application/json

errorsobject · nullableOptional

400

Invalid request parameters.

401

Authentication failed. The API-KEY header is missing or invalid.

403

Access denied. The project is inactive or the request IP is not allowed.

500

Internal server error.

get/webapi/conversation_daily_count

GET /webapi/conversation_daily_count HTTP/1.1
Host: backend.alli.ai
API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "startDate": "text",
  "endDate": "text"
}

{
  "result": {
    "dailyTotalCount": [
      {
        "date": "text",
        "activeCount": 1
      }
    ],
    "state": "text",
    "campaignCount": 1
  },
  "errors": {}
}