​
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. 
curl --location --request POST 'https://cite.petal.org/api/ai/table/create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{   
    "organization_id": 1,
    "user_id": 1,
    "visibility": "private",
    "document_ids":[1,2,3]
}'
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. 
curl --location --request POST 'https://cite.petal.org/api/ai/table/<id>/column/create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"LLM relation","query":"Is this paper related to LLMs?","meta":{"language":"English (US)"}}'
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: 
curl --location --request POST 'https://cite.petal.org/api/ai/table/<id>/run' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{"doc_id_col_id":[[<document_id_1>,<column_id_1>],[<document_id_2>,<column_id_1>]]}'
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: 
curl --location --request GET 'https://cite.petal.org/api/ai/table/<id>/cell/list' \
--header 'Authorization: Bearer <token>'
When a cell’s task_status is success, the AI has completed generating the response to the column’s query.