Before you can access our API, you will need at least two pieces of identifying information: your bearer token, and your Workspace (Organization) ID. For some APIs, you may also need your unique User ID. All of these can be accessed through the authorization endpoint, as described below. Before you can use the endpoint, you will need some software that can use APIs, such as cURL or Python.

​
Authorization endpoint

The API endpoint for authorization is https://cite.petal.org/api/auth. You will need to send a POST request to the endpoint, with the following parameters:
​
email
string
The email you use to sign in on Petal
​
password
string
Your password
The sample code below shows how to make this request. Remember to replace your_email@example.com and your_password with your actual login credentials. 
curl --location --request POST 'https://cite.petal.org/api/auth' \
--header 'Content-Type: application/json' \
--data-raw '{"email":"your_email@example.com","password":"your_password"}'
If successful, this request should return a JSON object with all the information you need. In particular, you are looking for these fields:
​
access_token
string
required
A cryptic bearer token that identifies you. It will be needed for all other API access.
​
id
integer
required
Your unique User ID.
​
organization_ids
integer[]
required
A list of the unique IDs of all Workspaces (also called Organizations) of which you are part.
Since every Petal user can create or join a number of Workspaces (also called Organizations in our API), you will need to find the ID of the particular Workspace you wish to work with, if you are in more than one Workspace. You might be able to do this by examining your role in each Workspace in the parameter
​
organization_roles
string[]
required
A list of your roles in all your Workspaces. Follows the same order as the organization_ids parameter.
However, if it’s still not clear which Workspace ID you need, you can follow the instructions in the next section to identify the correct Workspace.

​
Specifying your Workspace (Organization) ID

To do this, you should make a GET request to the https://cite.petal.org/api/user/<id>/organization/list endpoint. You will need to provide the bearer token you have just obtained from the previous step, as well as your user ID. Replace the sample values with your own in the code example below to get started. 
curl --location --request GET 'https://cite.petal.org/api/user/<id>/organization/list' \
--header 'Authorization: Bearer <token>'
If successful, this request should return a list of all Organizations (Workspaces) you are part of. It will provide the name and description for each Organization in the list. The is_personal field indicates whether the Organization is a personal one (created automatically upon user account creation). Using a combination of these fields, you should be able to identify the Organization you wish to work with. Once you have noted down the unique ID (in the id field), you are all set to begin to use our API for the correct Workspace.

​
What would you like to do next?

Upload documents

Upload your documents to Petal for cloud processing

Chat with documents

Converse with AI about the contents of your documents

Build AI tables

Extract information from your documents in this initutive format