​
Prerequisites

Before you can create an AI Table, 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 Table

The first step in using AI Tables is creating the Table itself. Afterwards, you can create the columns and cells of the Table.

To create the Table, send a POST request to the https://cite.petal.org/api/ai/table/create endpoint. In addition to the bearer token for authorization purposes, you will need to provide 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 Table

​
visibility
string

Can be private or shared. Determines whether other users in the Workspace can see this Table

You can use the code sample below to create your Table. Remember to replace the bearer token and Organization, user, and Document IDs with your own values.

If successful, the returned response should contain an id field, the unique ID of your newly-created Table. Please note this ID now, as it will be needed to create columns within your Table.

​
Create columns

The endpoint for creating a column within a Table is https://cite.petal.org/api/ai/table/<id>/column/create. You will need to fill in the <id> with the ID of the Table in which you wish to create the column. In addition, when you make the POST request to this API, you will need to provide the following:

​
name
string

The displayed name of your AI Column. It can be left blank, but you may want to set it to something recognizable for ease of use.

​
query
string

The message you want to send to the AI regarding each Document in this Table.

Sample code for creating the column is below. Remember to replace the bearer token and Table ID with your own values.

If this request is successful, you will receive a JSON response that contains information about the column you have just created. This includes the id field, which you will need to note down, as this is the unique ID of the column and will be needed to create cells.

​
Create cells

You can send a request to the https://cite.petal.org/api/ai/table/<id>/run endpoint to create cells and generate their contents using AI. In addition to the bearer token and the Table ID, you will need to provide the Document IDs and column IDs you want to generate cells and AI responses for. The IDs should be arranged in pairs, with the Document ID being the first item and the column ID the second.

See the sample code below. Remember to replace <token>, <id>, <document_id_#>, and <column_id_#> with your own values:

If successful, the server will return a list of the cells you have just created or updated. For each item in the list, the id field will refer to the unique ID of the cell.

Depending on the number of queries, the AI may several seconds or minutes to generate responses for Table cells, so you should regularly poll the API for updates. Use the https://cite.petal.org/api/ai/table/<id>/cell/list endpoint to fetch all cells within a given Table:

When a cell’s task_status is success, the AI has completed generating the response to the column’s query.

AI Chats