> ## Documentation Index
> Fetch the complete documentation index at: https://docs.petal.org/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Tables

> Create AI Tables based on your Documents

## 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](/intro/credentials).
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:

<ParamField path="organization_id" type="integer">
  The ID of your Workspace/Organization
</ParamField>

<ParamField path="user_id" type="integer">
  Your personal user ID
</ParamField>

<ParamField path="document_ids" type="array">
  The list of IDs for the Documents you wish to include in this Table
</ParamField>

<ParamField path="visibility" type="string">
  Can be `private` or `shared`. Determines whether other users in the Workspace can see this Table
</ParamField>

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.

<CodeGroup>
  ```bash cURL theme={null}
  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]
  }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://cite.petal.org/api/ai/table/create"

  payload = json.dumps({
    "organization_id": 1,
    "user_id": 1,
    "visibility": "private",
    "document_ids": [
      1,2,3
    ]
  })
  headers = {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  }

  response = requests.request("POST", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java JavaScript theme={null}
  var settings = {
    "url": "https://cite.petal.org/api/ai/table/create",
    "method": "POST",
    "timeout": 0,
    "headers": {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    "data": JSON.stringify({
      "organization_id": 1,
      "user_id": 1,
      "visibility": "private",
      "document_ids": [
        1,2,3
      ]
    }),
  };

  $.ajax(settings).done(function (response) {
    console.log(response);
  });
  ```
</CodeGroup>

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:

<ParamField path="name" type="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.
</ParamField>

<ParamField path="query" type="string">
  The message you want to send to the AI regarding each Document in this Table.
</ParamField>

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

<CodeGroup>
  ```bash cURL theme={null}
  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)"}}'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://cite.petal.org/api/ai/table/<id>/column/create"

  payload = json.dumps({
    "name": "LLM relation",
    "query": "Is this paper related to LLMs?",
    "meta": {
      "language": "English (US)"
    }
  })
  headers = {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  }

  response = requests.request("POST", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java JavaScript theme={null}
  var settings = {
    "url": "https://cite.petal.org/api/ai/table/<id>/column/create",
    "method": "POST",
    "timeout": 0,
    "headers": {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    "data": JSON.stringify({
      "name": "LLM relation",
      "query": "Is this paper related to LLMs?",
      "meta": {
        "language": "English (US)"
      }
    }),
  };

  $.ajax(settings).done(function (response) {
    console.log(response);
  });
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash cURL theme={null}
  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>]]}'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://cite.petal.org/api/ai/table/<id>/run"

  payload = json.dumps({
    "doc_id_col_id": [
      [
        <document_id_1>,
        <column_id_1>
      ],
      [
        <document_id_2>,
        <column_id_1>
      ]
    ]
  })
  headers = {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  }

  response = requests.request("POST", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java JavaScript theme={null}
  var settings = {
    "url": "https://cite.petal.org/api/ai/table/<id>/run",
    "method": "POST",
    "timeout": 0,
    "headers": {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    "data": JSON.stringify({
      "doc_id_col_id": [
        [
          <document_id_1>,
          <column_id_1>
        ],
        [
          <document_id_2>,
          <column_id_1>
        ]
      ]
    }),
  };

  $.ajax(settings).done(function (response) {
    console.log(response);
  });
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://cite.petal.org/api/ai/table/<id>/cell/list' \
  --header 'Authorization: Bearer <token>'
  ```

  ```python Python theme={null}
  import requests

  url = "https://cite.petal.org/api/ai/table/<id>/cell/list"

  payload={}
  headers = {
    'Authorization': 'Bearer <token>'
  }

  response = requests.request("GET", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java JavaScript theme={null}
  var settings = {
    "url": "https://cite.petal.org/api/ai/table/<id>/cell/list",
    "method": "GET",
    "timeout": 0,
    "headers": {
      "Authorization": "Bearer <token>"
    },
  };

  $.ajax(settings).done(function (response) {
    console.log(response);
  });
  ```
</CodeGroup>

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