Chatbots endpoint

The Chatbots endpoint lets you send an asynchronous query to an existing chatbot and retrieve the response.

curl examples reference the API_ROOT, API_TOKEN, and IB_CONTEXT values as variables. If you don’t set up these variables, define them in the request.
All endpoints support the IB-Context header. Organization members must set the IB-Context header as their organization ID to complete the request with their organization account. While optional, it’s a best practice to include the IB-Context header in all requests.
All endpoints use the standard HTTP response status codes. For each endpoint, some common status codes are listed.

The AI Hub Python SDK doesn’t yet support chatbot-related methods. However, the Making chatbot queries by API guide includes a complete Python script you can reference to integrate the ability to send chatbot queries into your workflow.

Create chatbot query (async)

Method	Syntax
POST	`API_ROOT/v2/queries`

Description

Send an asynchronous query to a chatbot by making a POST request to API_ROOT/v2/queries. Each request returns a query_id that can be used to check the query’s status and get the response.

Request body

Parameters are required unless marked as optional.

Parameter	Type	Description	Values
`query`	string	Your chatbot query. Chatbot queries made by API are also visible in your query history when accessing the chatbot from the AI Hub user interface.
`source_app/type`	string	The app type.	For chatbot queries, the app type is always `CHATBOT`.
`source_app/uuid`	string	The ID of the chatbot to query. You can query any AIHub chatbot to which you have access.	A valid chatbot ID. You can find a chatbot’s ID in its AI Hub URL, such as https://aihub.instabase.com/hub/ apps/788eba40-5a1f-45f4-ad56-57fb1abe62c7. A chatbot’s ID changes with every version update. For convenience, when making a request to a given version of a chatbot, the query is always automatically directed to the latest version of the chatbot.
`model_name`	string	Optional, defaults to `multistep-lite`. The model to use to answer the question. Supports the multistep model and research mode, a more powerful but slower variant of the multistep model that’s suited to complex reasoning queries. See Choosing a model for details.	`multistep-lite` (multistep model), `multistep` (research mode)
`include_source_info`	boolean	Optional, defaults to `false`. Set to `true` to return information about the source documents referenced when generating the query response. The multistep model (`model_name` set to `multistep-lite`) supports document-level source information. Research mode (`model_name` set to `multistep`) supports page-level source information.

Response status

Status	Meaning
`202`	Query request accepted. Check the query status to get completion status and query response.

Response schema

Key	Type	Description
`query_id`	string	The ID of the query.

Examples

Request (curl)

$ curl "${API_ROOT}/v2/queries" \
>   -H "Authorization: Bearer ${API_TOKEN}" \
>   -H "IB-Context: ${IB_CONTEXT}"\
>   -H "Content-Type: application/json" \
>   -d '{
>          "query": "What are the steps to write effective prompts?",
>          "model_name": "multistep-lite",
>          "include_source_info": true,
>          "source_app": [
>             {
>                "type": "CHATBOT",
>                "uuid": "788eba40-5a1f-45f4-ad56-57fb1abe62c7"
>             }
>          ]
>       }'

Response

1 {
2   "query_id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed"
3 }

Get query status and response

Method	Syntax
GET	`API_ROOT/v2/queries/<QUERY-ID>`

Description

Get the status of an asynchronous chatbot query by sending a GET request to API_ROOT/v2/queries/<QUERY-ID>. The query ID value is returned in the response of the create chatbot query request. If the query status is COMPLETE, this request also returns the query response.

Request body

There is no request body. Use the request URL to specify the query ID.

Response status

Status	Meaning
`200 OK`	Successful request.

Response schema

The response body is a JSON object containing the query ID and status. If the query status is COMPLETE, the query response is also returned. If the query status is FAILED an error message is returned instead.

Key	Type	Description
`query_id`	string	The ID of the query. This value is returned by a Create chatbot query (async) request.
`status`	string	Status of the query. Possible values are `RUNNING`, `COMPLETE`, or `FAILED`.
`results`	array	The query response. Returned only if the query status is `COMPLETE`.
`results/response`	string	The response message generated by the chatbot.
`results/source_documents`	array	Returned if `include_source_info` was set to true. Information about the source documents referenced when generating the query response.
`results/source_documents/name`	string	The name of the source document referenced.
`results/source_documents/pages`	array	An array of page objects with information about the specific pages referenced in the source document. Page-level source information is supported only when using research mode.
`results/source_documents/pages/page_number`	float	The number of the page referenced in the source document.
`results/source_documents/pages/bboxes`	string	Bounding boxes for the text referenced on the page, if applicable.
`error`	object	Present only if the `status` is `FAILED`. Contains a `message` with information about the source of the execution error, such as `"message": "Invalid query uuid passed"`.

Examples

Request (curl)

$ curl "${API_ROOT}/v2/queries/<QUERY-ID>" \
>   -H "Authorization: Bearer ${API_TOKEN}"\
>   -H "IB-Context: ${IB_CONTEXT}"

Response

1 {
2   "query_id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
3   "status": "COMPLETE",
4   "results": [
5     {
6       "response": "The email was sent on Monday, March 11, 2024",
7       "source_documents": [
8         {
9           "name": "testdoc.docx",
10           "pages": [
11             {
12               "page_number": 1.0,
13               "bboxes": []
14             }
15           ]
16         }
17       ]
18     }
19   ]
20 }

$	curl "${API_ROOT}/v2/queries" \
>	-H "Authorization: Bearer ${API_TOKEN}" \
>	-H "IB-Context: ${IB_CONTEXT}"\
>	-H "Content-Type: application/json" \
>	-d '{
>	"query": "What are the steps to write effective prompts?",
>	"model_name": "multistep-lite",
>	"include_source_info": true,
>	"source_app": [
>	{
>	"type": "CHATBOT",
>	"uuid": "788eba40-5a1f-45f4-ad56-57fb1abe62c7"
>	}
>	]
>	}'

$	curl "${API_ROOT}/v2/queries/<QUERY-ID>" \
>	-H "Authorization: Bearer ${API_TOKEN}"\
>	-H "IB-Context: ${IB_CONTEXT}"

1	{
2	"query_id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
3	"status": "COMPLETE",
4	"results": [
5	{
6	"response": "The email was sent on Monday, March 11, 2024",
7	"source_documents": [
8	{
9	"name": "testdoc.docx",
10	"pages": [
11	{
12	"page_number": 1.0,
13	"bboxes": []
14	}
15	]
16	}
17	]
18	}
19	]
20	}