​
Prerequisites

Before you can create a chat Session, you will need:
  1. Your bearer token, user ID, and desired Workspace ID. They can be obtained as described here.
  2. Software that can use APIs, such as cURL or Python.
  3. At least one Document in your Workspace.

​
Create an AI chat Session

Before you can start creating chat messages, you must create an AI chat Session. The API endpoint for creating a Session is https://cite.petal.org/api/ai/session/create. You will need to send a POST request to the endpoint, with the following parameters:
​
organization_id
integer
The ID of your Workspace/Organization
​
user_id
integer
Your personal user ID
​
document_ids
array
The list of IDs for the Documents you wish to include in this chat
​
is_multidoc
boolean
Whether you want to use multi-doc chat (Available to users of Petal Advanced Plan and above). Multi-doc chat uses a higher context size compared to single-doc chat. It is possible to have a multi-doc Session with only one Document in document_ids, but it is not possible to have a single-doc Session with more than one Document
​
visibility
string
Can be private or shared. Determines whether other users in the Workspace can see this Session
Below is an example of such a request. 
curl --location --request POST 'https://cite.petal.org/api/ai/session/create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{   
    "organization_id": 1,
    "user_id": 1,
    "visibility": "private",
    "is_multidoc": true,
    "document_ids":[1,2,3]
}'
This request, if successful, should return a JSON object, indicating that your Session has been created. In particular, you will want to note down the id returned, as that is the unique Session ID that you will need to create messages within it. Once you have located it, we can move on to message creation.

​
Create chat messages in your Session

All chat messages are located within a given Session. This allows the AI (and you) to keep track of the flow of a conversation. Once you know the Session ID in which you wish to create a message, make a POST request to https://cite.petal.org/api/ai/session/<id>/qa/create. You need to enter the Session ID into the URI (at <id>), and the body of the request should contain your message to the AI:
​
query
string
Your message here.
Sample code is provided below. 
curl --location --request POST 'https://cite.petal.org/api/ai/session/<id>/qa/create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "What is a LLM?"
}'
If successful, the API should return a JSON object with information about the new chat message. In particular, you will want to pay attention to these two fields:
​
id
integer
required
A unique ID for this chat message.
​
task_status
string
required
The progress of getting the AI to respond to your message. It should change from pending to running to success over time.
In the beginning, all message task_status should be pending. This is because it takes some time to submit the user message to the AI and get a response. In order to fetch updates to the message, you should use the API https://cite.petal.org/api/ai/session/<id>/qa/list, which will return a list that contains all chat messages for the given Session. 
curl --location --request GET 'https://cite.petal.org/api/ai/session/<id>/qa/list' \
--header 'Authorization: Bearer <token>' \
--data-raw ''
For every chat message, the AI’s response is given by the response field in the JSON. While the task_status of that message is running, the response may be incomplete because the AI is still working. Once the task_status is success, the response will be complete.