Conversations endpoint

The Conversations endpoint lets you create a Converse conversation. In a conversation, you can use prompts to get on-demand information from documents of nearly any type or format.

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.
For Python request examples, it’s assumed you installed the AI Hub SDK. All examples also include lines initializing the API client, with values you must define.
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.

Create conversation

Method	Syntax
POST	`API_ROOT/v2/conversations`

Description

Create a new conversation by making a POST request to API_ROOT/v2/conversations. You can upload files to the conversation in the same request.

There are some limitations when uploading files to a conversation:

Files can be up to 50 MB or 800 pages.
You can upload up to 100 MB per request.
You can have up to 100 documents per conversation.
There are specific supported file types.

Request body

Parameters are required unless marked as optional.

Parameter	Type	Description	Values
`name`	string	Name of the conversation.
`description`	string	Description of the conversation.
`files`	list	A list of files to process.	Local file paths.
`org`	string	Optional. Your organization.	For organization members, your organization is `<ORGANIZATION-ID>`. If not defined, the organization is inferred from the `IB-Context` header value. If you define an `org` value and include the `IB-Context` header, the organization values must match or the request can’t complete.
`workspace`	string	Optional. The name of your personal workspace, where the conversation is created.	For organization members, your personal workspace name is your user ID. If not defined, the workspace is inferred from the `IB-Context` header value.
`enable_object_detection`	boolean	Optional. Defines whether to enable object detection for the processed file. Object detection includes support for extracting tables and checkboxes.	`true`, `false`. Default `false`.

Response status

Status	Meaning
`201`	Created conversation.

Response schema

Key	Type	Description
`id`	string	A unique identifier for the conversation.
`name`	string	Name of the conversation.
`upload_status`	object	Contains a summary of the upload status for uploaded files.
`upload_status/success`	list	Lists all files successfully uploaded to the conversation.
`upload_status/failure`	list	Lists all files that failed to upload to the conversation, and the reason why.

Examples

Request (curl)

$ curl "${API_ROOT}/v2/conversations" \
>   -H "Authorization: Bearer ${API_TOKEN}" \
>   -H "IB-Context: ${IB_CONTEXT}"\
>   -F name="Sample Conversation Name" \
>   -F description="Sample Conversation Description" \
>   -F org="<ORGANIZATION-ID>" \ # Optional for community accounts
>   -F workspace="<WORKSPACE-NAME>" \ # Optional for community accounts
>   -F files="@/path/to/test.pdf" \
>   -F files="@/path/to/test2.pdf"

Request (Python SDK)

1 from aihub import AIHub
2 
3 client = AIHub(api_root="<API-ROOT>",
4                api_key="<API-TOKEN>",
5                ib_context="<IB-CONTEXT>")
6 
7 result = client.conversations.create(
8   name="Sample Conversation Name",
9   description="Sample Conversation Description",
10   org="<ORGANIZATION-ID>", # Optional for community accounts
11   workspace="<WORKSPACE-NAME>", # Optional for community accounts
12   files=['test.pdf', 'test2.pdf'])

Response

1 {
2     "id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
3     "name": "Conversation 2023-08-23 11:40:30.669832",
4     "upload_status": {
5         "success": [
6             {
7                 "name": "test.pdf"
8             },
9             {
10                 "name": "test2.pdf"
11             }
12         ],
13         "failure": []
14     }
15 }

List conversations

Method	Syntax
GET	`API_ROOT/v2/conversations`

Description

Return a list of conversations you’ve created by sending a GET request to API_ROOT/v2/conversations.

Organization admins can access a list of all conversations in the organization, not just conversations they created.

Query parameters

Query parameter	Description
`sort_key`	Optional. Sort the returned conversations by when they were created (`created_at`) or updated (`updated_at`).
`sort_is_ascending`	Optional. Set the sort order.
`search_string`	Optional. Filter for conversations with the specified string.

Request body

There is no request body. Use query parameters to filter your results, if needed.

Response status

Status	Meaning
`200`	Success.

Response schema

Key	Type	Description
`conversations`	list	List of conversations.
`conversations/id`	string	The conversation ID.
`conversations/name`	string	The conversation name.
`conversations/description`	string	The conversation description.

Examples

Request (curl)

$ curl "${API_ROOT}/v2/conversations" \
>   -H "Authorization: Bearer ${API_TOKEN}"`
>   -H "IB-Context: ${IB_CONTEXT}"

Request (Python SDK)

1 from aihub import AIHub
2 
3 client = AIHub(api_root="<API-ROOT>",
4                api_key="<API-TOKEN>",
5                ib_context="<IB-CONTEXT>")
6 conversations = client.conversations.list()

Response

1 {
2     "conversations": [
3         {
4             "id": "66bd3eb8-36c7-4aaa-9f95-49c593add1e8",
5             "name": "Conversation 2023-08-28 12:07:23.932130",
6             "description": "Sample Conversation"
7         },
8         {
9             "id": "7196d351-0302-4d67-9ce8-b06c3bec8709",
10             "name": "Conversation 2023-08-28 12:09:50.449657",
11             "description": ""
12         }
13     ]
14 }

Conversation information

Method	Syntax
GET	`API_ROOT/v2/conversations/<CONVERSATION-ID>`

Description

Retrieve information about a conversation, such as its state and a list of documents in the conversation, by making a GET request to API_ROOT/v2/conversations/<CONVERSATION-ID>.

Request body

There is no request body. Use the request URL to provide the conversation ID.

Response status

Status	Meaning
`200`	Success.

Response schema

Key	Type	Description
`id`	string	Unique identifier for the conversation.
`name`	string	Name of the conversation.
`description`	string	Description of the conversation.
`state`	string	The state of the conversation: - `COMPLETE`: Ready to start a conversation. - `FAILED`: Not able process any of the uploaded files. - `RUNNING`: Still processing the uploaded files.
`documents`	list	A list of all uploaded and processed documents in the conversation.
`documents/id`	integer	The uploaded document’s ID. Use this value when sending conversation prompts to specify the document to query.
`documents/name`	string	Name of the document.

Examples

Request (curl)

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

Request (Python SDK)

1 from aihub import AIHub
2 
3 client = AIHub(api_root="<API-ROOT>",
4                api_key="<API-TOKEN>",
5                ib_context="<IB-CONTEXT>")
6 result = client.conversations.status(<CONVERSATION-ID>)

Response

1 {
2   "id": "<CONVERSATION-ID>",
3   "name": "Sample Conversation",
4   "description": "Sample Description",
5   "state": "COMPLETE",
6   "documents": [
7     {
8       "id": <DOCUMENT-ID>,
9       "name": "test.pdf"
10     }
11   ]
12 }

Converse with a document

Method	Syntax
POST	`API_ROOT/v2/conversations/<CONVERSATION-ID>/prompts`

Description

Query a document in your conversation by making a POST request to API_ROOT/v2/conversations/<CONVERSATION-ID>/prompts.

Request body

Parameters are required unless marked as optional.

Parameter	Type	Description	Values
`question`	string	An input prompt. This can include any question or request supported by Converse, except for plot graphs.
`document_ids`	list	A document ID for the document to converse with. You can converse with one document at a time. Document IDs are single integer values that you must pass as a list.	List of one valid document ID integer. You can get a list of document IDs in your conversation with a Conversation information request.
`mode`	string	The model to use to answer the question. Supports the standard (`default`) and advanced (`advanced`) models. If unspecified, the standard model is used. See Choosing a model for details about each model. The multistep model is not supported for queries made by API.	`default` (standard model), `advanced` (advanced model)

Response status

Status	Meaning
`200`	Success.

Response schema

Key	Type	Description
`prompt_id`	string	The ID of the prompt.
`answer`	string	The answer to the question asked.

Examples

Request (curl)

$ curl "${API_ROOT}/v2/conversations/<CONVERSATION-ID>/prompts" \
>   -H "Authorization: Bearer ${API_TOKEN}" \
>   -H "IB-Context: ${IB_CONTEXT}"
>   -H "Content-Type: application/json" \
>   -d '{
>         "question": "What is the main topic of the document?",
>         "document_ids": [<DOCUMENT-ID>],
>         "mode": "default"
>       }'

Request (Python SDK)

1 from aihub import AIHub
2 
3 client = AIHub(api_root="<API-ROOT>",
4                api_key="<API-TOKEN>",
5                ib_context="<IB-CONTEXT>")
6 answer = client.conversations.converse(conversation_id='<CONVERSATION-ID>',
7                                        question="What is the main topic of the document?",
8                                        document_ids=['<DOCUMENT-ID>'],
9                                        mode="default")

Response

1 {
2     "prompt_id": "5b7057f8e3a04cc3a68e092bef78927e",
3     "answer": "The document is a receipt for an Uber trip on March 3, 2024."
4 }

Add documents to conversation

Method	Syntax
POST	`API_ROOT/v2/conversations/<CONVERSATION-ID>/documents`

Description

Upload documents to a conversation by making a POST request to API_ROOT/v2/conversations/<CONVERSATION-ID>/documents.

There are some limitations when uploading files to a conversation:

Files can be up to 50 MB or 800 pages.
You can upload up to 100 MB per request.
You can have up to 100 documents per conversation.
There are specific supported file types

Request body

Parameters are required unless marked as optional.

Key	Type	Description	Values
`files`	list	A list of files to upload to the conversation.	Local file paths.
`process_files`	boolean	Optional. Set whether to process the files upon upload.	`true`, `false`. Default `true`.

Response status

Status	Meaning
`201`	Documents uploaded and processed successfully.
`400`	Documents failed to upload.

Response schema

Key	Type	Description
`upload_status`	object	Contains a summary of upload status for uploaded files.
`upload_status/success`	list	Lists all files successfully uploaded to the conversation.
`upload_status/failure`	list	Lists all files that failed to upload to the conversation, and the reason why.

Examples

Request (curl)

$ curl "${API_ROOT}/v2/conversations/<CONVERSATION-ID>/documents" \
>   -H "Authorization: Bearer ${API_TOKEN}" \
>   -H "IB-Context: ${IB_CONTEXT}"\
>   -F files="@/path/to/test.pdf" \
>   -F files="@/path/to/test2.pdf"

Request (Python SDK)

1 from aihub import AIHub
2 
3 client = AIHub(api_root="<API-ROOT>",
4                api_key="<API-TOKEN>",
5                ib_context="<IB-CONTEXT>")
6 status = client.conversations.add_documents('<CONVERSATION-ID>',
7                                             files=['test.pdf', 'test2.pdf'])

Response

1 {
2   "upload_status": {
3     "success": [
4       {
5         "name": "test2.pdf"
6       }
7     ],
8     "failure": [
9       {
10         "name": "test.pdf",
11         "reason": "File already exists."
12       }
13     ]
14   }
15 }

Delete documents from conversation

Method	Syntax
DELETE	`API_ROOT/v2/conversations/<CONVERSATION-ID>/documents`

Description

Delete documents from a conversation by making a DELETE request to API_ROOT/v2/conversations/<CONVERSATION-ID>/documents.

You can get a list of document IDs in your conversation with a Conversation information request.

Request body

Parameters are required unless marked as optional.

Key	Type	Description	Values
`ids`	list	A list of document IDs for the documents to delete from the conversation.	List of valid document ID integers.

Response status

Status	Meaning
`204`	Documents successfully deleted. No content returned.

Response schema

No content is returned for successful requests.

Examples

Request (curl)

$ curl -X "DELETE" "${API_ROOT}/v2/conversations/<CONVERSATION-ID>/documents" \
>   -H "Authorization: Bearer ${API_TOKEN}" \
>   -H "IB-Context: ${IB_CONTEXT}"\
>   -H "Content-Type: application/json" \
>   -d '{"ids": [<DOCUMENT-ID>]}'

Request (Python SDK)

1 from aihub import AIHub
2 
3 client = AIHub(api_root="<API-ROOT>",
4                api_key="<API-TOKEN>",
5                ib_context="<IB-CONTEXT>")
6 status = client.conversations.delete_documents('<CONVERSATION-ID>',
7                                                ids=[<DOCUMENT-ID>])

Get document metadata

Method	Syntax
GET	`API_ROOT/v2/conversations/<CONVERSATION-ID>/documents/<DOCUMENT-ID>`

Description

Retrieve metadata for a document in a conversation by making a GET request to API_ROOT/v2/conversations/<CONVERSATION-ID>/documents/<DOCUMENT-ID>.

Request body

There is no request body. Use the request URL to specify the conversation and document.

Response status

Status	Meaning
`200`	Success.

Response schema

Key	Type	Description
`id`	integer	The document ID.
`ibdoc_path`	string	Path to the document’s internal representation.
`name`	string	The name of the document.
`metadata`	list	A collection of additional, possibly dynamic, metadata properties associated with the document. The structure of this object can vary depending on the document’s content and type.

Examples

Request (curl)

$ curl "${API_ROOT}/v2/conversations/<CONVERSATION-ID>/documents/<DOCUMENT-ID>" \
>   -H "Authorization: Bearer ${API_TOKEN}"

Request (Python SDK)

1 from aihub import AIHub
2 
3 client = AIHub(api_root="<API-ROOT>",
4                api_key="<API-TOKEN>",
5                ib_context="<IB-CONTEXT>")
6 status = client.conversations.get_document_metadata('<CONVERSATION-ID>',
7                                                     document_id=<DOCUMENT-ID>)

Response

1 {
2   "id": <DOCUMENT-ID>,
3   "ibdoc_path": "username/my-repo/fs/Instabase Drive/aihub/9ff02b54-d7df-406d-a7ae-f17f9b90e6ec/documents/out/test_eJwrSS0u0StISQMADpcDKQ==.pdf.ibdoc",
4   "name": "test.pdf",
5   "metadata": [
6     {
7       "metadata_list": null,
8       "layout": {
9         "processed_image_path": "joe/my-repo/fs/Instabase Drive/aihub/9ff02b54-d7df-406d-a7ae-f17f9b90e6ec/documents/out/original/images/test_eJwrSS0u0StISQMADpcDKQ==.pdf_p0.JPEG.jpeg",
10         "thumbnail_image_path": "joe/my-repo/fs/Instabase Drive/aihub/9ff02b54-d7df-406d-a7ae-f17f9b90e6ec/documents/out/original/thumbnails/test_eJwrSS0u0StISQMADpcDKQ==.pdf_p0.JPEG.JPEG",
11         "model_training_image_path": "",
12         "page_input_path": "",
13         "width": 2550,
14         "height": 3301,
15         "corrected_rotation": 0,
16         "origin_pos": [
17           0,
18           0
19         ],
20         "is_blurry": false,
21         "blur_factor": 0,
22         "is_image_page": true,
23         "original_page_number": 0
24       },
25       "annotation_data": null,
26       "pdf_doc_metadata": null
27     }
28   ]
29 }

Update conversation information

Method	Syntax
PUT	`API_ROOT/v2/conversations/<CONVERSATION-ID>`

Description

Update a conversation name or description by making a PUT request to API_ROOT/v2/conversations/<CONVERSATION-ID>. The new values are passed using query parameters, such as API_ROOT/v2/conversations/<CONVERSATION-ID>?name=<CONVERSATION-NAME>&description=<CONVERSATION-DESCRIPTION>.

Query parameters

Query parameter	Description
`name`	The name of the conversation.
`description`	A description of the conversation.

Response status

Status	Meaning
`204`	Conversation details successfully updated. No content returned.
`500`	Internal server error. Failed to update conversation details.

Response schema

No content is returned for successful requests. In case of an internal server error, an error message is provided in the response body.

Examples

Request (curl)

$ curl -X "PUT" "${API_ROOT}/v2/conversations/<CONVERSATION-ID>?name=<CONVERSATION-NAME>&description=<CONVERSATION-DESCRIPTION>" \
>   -H "Authorization: Bearer ${API_TOKEN}" \
>   -H "IB-Context: ${IB_CONTEXT}"\
>   -H "Content-Type: application/json"

Request (Python SDK)

1 from aihub import AIHub
2 
3 client = AIHub(api_root="<API-ROOT>",
4                api_key="<API-TOKEN>",
5                ib_context="<IB-CONTEXT>")
6 status = client.conversations.update('<CONVERSATION-ID>',
7                                      name='<CONVERSATION-NAME>',
8                                      description='<CONVERSATION-DESCRIPTION>')

$	curl "${API_ROOT}/v2/conversations" \
>	-H "Authorization: Bearer ${API_TOKEN}" \
>	-H "IB-Context: ${IB_CONTEXT}"\
>	-F name="Sample Conversation Name" \
>	-F description="Sample Conversation Description" \
>	-F org="<ORGANIZATION-ID>" \ # Optional for community accounts
>	-F workspace="<WORKSPACE-NAME>" \ # Optional for community accounts
>	-F files="@/path/to/test.pdf" \
>	-F files="@/path/to/test2.pdf"

1	from aihub import AIHub
2
3	client = AIHub(api_root="<API-ROOT>",
4	api_key="<API-TOKEN>",
5	ib_context="<IB-CONTEXT>")
6
7	result = client.conversations.create(
8	name="Sample Conversation Name",
9	description="Sample Conversation Description",
10	org="<ORGANIZATION-ID>", # Optional for community accounts
11	workspace="<WORKSPACE-NAME>", # Optional for community accounts
12	files=['test.pdf', 'test2.pdf'])

1	{
2	"id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
3	"name": "Conversation 2023-08-23 11:40:30.669832",
4	"upload_status": {
5	"success": [
6	{
7	"name": "test.pdf"
8	},
9	{
10	"name": "test2.pdf"
11	}
12	],
13	"failure": []
14	}
15	}

$	curl "${API_ROOT}/v2/conversations" \
>	-H "Authorization: Bearer ${API_TOKEN}"`
>	-H "IB-Context: ${IB_CONTEXT}"

1	{
2	"conversations": [
3	{
4	"id": "66bd3eb8-36c7-4aaa-9f95-49c593add1e8",
5	"name": "Conversation 2023-08-28 12:07:23.932130",
6	"description": "Sample Conversation"
7	},
8	{
9	"id": "7196d351-0302-4d67-9ce8-b06c3bec8709",
10	"name": "Conversation 2023-08-28 12:09:50.449657",
11	"description": ""
12	}
13	]
14	}

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

1	{
2	"id": "<CONVERSATION-ID>",
3	"name": "Sample Conversation",
4	"description": "Sample Description",
5	"state": "COMPLETE",
6	"documents": [
7	{
8	"id": <DOCUMENT-ID>,
9	"name": "test.pdf"
10	}
11	]
12	}

1	{
2	"prompt_id": "5b7057f8e3a04cc3a68e092bef78927e",
3	"answer": "The document is a receipt for an Uber trip on March 3, 2024."
4	}

$	curl -X "DELETE" "${API_ROOT}/v2/conversations/<CONVERSATION-ID>/documents" \
>	-H "Authorization: Bearer ${API_TOKEN}" \
>	-H "IB-Context: ${IB_CONTEXT}"\
>	-H "Content-Type: application/json" \
>	-d '{"ids": [<DOCUMENT-ID>]}'

$	curl "${API_ROOT}/v2/conversations/<CONVERSATION-ID>/documents/<DOCUMENT-ID>" \
>	-H "Authorization: Bearer ${API_TOKEN}"

1	{
2	"id": <DOCUMENT-ID>,
3	"ibdoc_path": "username/my-repo/fs/Instabase Drive/aihub/9ff02b54-d7df-406d-a7ae-f17f9b90e6ec/documents/out/test_eJwrSS0u0StISQMADpcDKQ==.pdf.ibdoc",
4	"name": "test.pdf",
5	"metadata": [
6	{
7	"metadata_list": null,
8	"layout": {
9	"processed_image_path": "joe/my-repo/fs/Instabase Drive/aihub/9ff02b54-d7df-406d-a7ae-f17f9b90e6ec/documents/out/original/images/test_eJwrSS0u0StISQMADpcDKQ==.pdf_p0.JPEG.jpeg",
10	"thumbnail_image_path": "joe/my-repo/fs/Instabase Drive/aihub/9ff02b54-d7df-406d-a7ae-f17f9b90e6ec/documents/out/original/thumbnails/test_eJwrSS0u0StISQMADpcDKQ==.pdf_p0.JPEG.JPEG",
11	"model_training_image_path": "",
12	"page_input_path": "",
13	"width": 2550,
14	"height": 3301,
15	"corrected_rotation": 0,
16	"origin_pos": [
17	0,
18	0
19	],
20	"is_blurry": false,
21	"blur_factor": 0,
22	"is_image_page": true,
23	"original_page_number": 0
24	},
25	"annotation_data": null,
26	"pdf_doc_metadata": null
27	}
28	]
29	}

$	curl -X "PUT" "${API_ROOT}/v2/conversations/<CONVERSATION-ID>?name=<CONVERSATION-NAME>&description=<CONVERSATION-DESCRIPTION>" \
>	-H "Authorization: Bearer ${API_TOKEN}" \
>	-H "IB-Context: ${IB_CONTEXT}"\
>	-H "Content-Type: application/json"