Using the API
Welcome Retable's public API documentation. This documentation gives you broad information about how to use Retable API with your organization.
There are four different sections that you can use.
- Data
- Workspace
- Project
- Retable
User limitations are directly applied to API endpoints.
Retable API is in public beta. There are several functionalities that perfectly work, and there are a few that we are still working on. Hence, there might be some unstable conditions, and you'll see constant changes to the API. Feel free to send us any questions regarding our API, preferably to our Discord channel. Have fun!
You can design, build, and automate anything for your work by integrating Retable with any of your apps in just a few clicks with Retable Make(Integromat) Integration.
While you are on a table you will see a URL in the browser address bar, similar to this: https://app.retable.io/retable/2BIeQnYjn1EPOITr/s6zbj6a0sfqZMpkh/6C1z5kFwY7uR5D3O
- First part after "retable" prefix is Workspace Id
- Second part after Workspace Id is Project Id
- Third part after Project Id is Retable Id
Hence, overall URL structure is like this:
https://app.retable.io/retable/{workspace_id}/{project_id}/{retable_id}
Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.
You can generate and delete an API key from your user page at any time on Retable.io.
This generated API key is constant - when it is generated, it never changes. However, you can change its usable state or add a new one on the same page.
After obtaining your API Key (starts with RTBL-v1 prefix) you have to add an ApiKey header to every request. Otherwise, you will get an Unauthorized Error.
For the Beta version we have not implemented any libraries, however, we are planning to add libraries in the coming versions.
Requests expect a JSON body.
All responses come in a JSON object inside of a data field:
{
"data": {
...
}
}
Almost all responses contain created_by, updated_by and deleted_by objects called basic user objects. These objects contain information about the user who made the create, update and delete operations. They have four basic fields:
- id (string): Unique Id of the user
- name (string): Name of the user
- surname (string): Surname of the user
- email (string): Unique email address of the user
If the response contains a basic user object, the created_by user object always contains a non-null value. updated_by and deleted_by can return null values.
In Addition to basic user objects, responses return created_at, updated_at and deleted_at date fields. These fields indicate when the component is created, updated or deleted in UTC. created_at always contains a non-null date value. Other date fields (updated_at and deleted_at) can contain null values.
This endpoint is for data related API operations.
get
https://api.retable.io/v1/public
/retable/{retable_id}/data
Get rows
cURL
curl --request GET 'https://api.retable.io/v1/public/retable/<retable_id>/data' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
In this request's response, there is an object array called rows. This object contains information about a row.
An example row object:
{
"id": 1,
"created_at": "2022-04-04 17:47:03",
"updated_at": null,
"created_by": {
"id": "PuNXWNo8nVWDSUrE",
"name": "Gandalf",
"surname": "The White",
"email": "[email protected]"
},
"updated_by": null,
"columns": [
{
"kPpvPLIH66L2DecQ": ""
}
]
}
- id (integer): Id of the row
- created_at (string): UTC date-time when the row is created
- updated_at (string): UTC date-time when the row is updated
- created_by (basic user object): User info that created the row
- updated_by (basic user object): User info that updated the row
- columns (column cell data object): A simple object that contains the column names as key and cell data as value
Only the owner or the editor roles can insert a row. Otherwise, you will get a "Not Allowed" error.
post
https://api.retable.io/v1/public
/retable/{retable_id}/data
Insert Row
With the body example below, you will be inserting two rows with cell data 'Isengard' and 'Rivendell' to the column with Id 'Bvt1FQhTyAPjmDx'.
The response will be the inserted values.
If you do not provide the cell_value field in the body, you will get a "Bad Request" error.
{
"data": [
{
"columns": [
{
"column_id": "Bvt1FQhTyAPjmDx",
"cell_value": "Isengard"
}
]
},
{
"columns": [
{
"column_id": "Bvt1FQhTyAPjmDx",
"cell_value": "Rivendell"
}
]
}
]
}
cURL
curl --request POST 'https://api.retable.io/v1/public/retable/<retable_id>/data' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": [
{
"columns": [
{
"column_id": "Bvt1FQhTyAPjmDx",
"cell_value": "Isengard"
},
{
"column_id": "Bvt1FQhTyAPjmDx",
"cell_value": "Rivendell"
}
]
}
]
}'
Only the owner or the editor roles can update a row. Otherwise, you will get a "Not Allowed" error.
put
https://api.retable.io/v1/public
/retable/{retable_id}/data
Update row
{
"rows": [
{
"row_id": 2,
"columns": [
{
"column_id": "Bvt1FtQhTyAPjmDx",
"update_cell_value": "Mordor"
}
]
}
]
}
cURL
curl --request PUT 'https://api.retable.io/v1/public/retable/<retable_id>/data' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"rows": [
{
"row_id": 2,
"columns": [
{
"column_id": "Bvt1FtQhTyAPjmDx",
"update_cell_value": "Mordor"
}
]
}
]
}'
Only the owner of the Retable can delete a row. Otherwise, you will get a "Not Allowed" error.
delete
https://api.retable.io/v1/public/
retable/{retable_id}/data
Delete row
If the given row Id does not exist in the Retable, delete row request returns Status Ok
with deleted_row_count is 0.
{
"row_ids": [
1
]
}
cURL
curl --request DELETE 'https://api.retable.io/v1/public/retable/<retable_id>/data' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"row_ids": [
1
]
}'
This includes workspace related API operations.
get
https://api.retable.io/v1/public
/workspace
Get all workspaces
cURL
curl --location --request GET 'https://api.retable.io/v1/public/workspace' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
get
https://api.retable.io/v1/public
/workspace/{workspace_id}
Get a workspace
cURL
curl --location --request GET 'https://api.retable.io/v1/public/workspace/<workspace_id>' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
post
https://api.retable.io/v1/public
/workspace
Create a Workspace
{
"name": "Workspace 1",
"description": "Workspace Description"
}
cURL
curl --location --request POST 'https://api.retable.io/v1/public/workspace' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Workspace 1",
"description": "Workspace Description"
}'
retable_id is the last part of the table URL - the part after the last slash.
Example: app.retable.io/retable/{workspace_id}/{project_id}/{retable_id}
This includes project related API operations.
get
https://api.retable.io/v1/public
/workspace/{workspace_id}/project
Get workspace's projects
cURL
curl --request GET 'https://api.retable.io/v1/public/workspace/<workspace_id>/project' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
get
https://api.retable.io/v1/public
/project/{project_id}
Get a project
cURL
curl --request GET 'https://api.retable.io/v1/public/project/<project_id>' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
post
https://api.retable.io/v1/public
/workspace/{workspace_id}/project
Create Project
{
"name": "New Project 1",
"description": "Project Description",
"color": "#898cff"
}
cURL
curl --request POST 'https://api.retable.io/v1/public/workspace/<workspace_id>/project' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "New Project 1",
"description": "Project Description",
"color": "#898cff"
}'
Retable related API operations.
In this section, you can see available Retable endpoints.
Every endpoint returns a column array object which contains current column information.
An example column object:
{
"column_id": "vgcDsxT8NX5zFimQ",
"type": "text",
"title": "A",
"created_at": "2022-04-04 17:30:33.947000"
}
- name (string): A unique identifier, different for every column.
- type (string): Type of the column.
- title (string): Title of the column.
- created_at (string): UTC date when the column is created.
The column_id property is used for deleting column(s) from a Retable.
get
https://api.retable.io/v1/public
/project/{project_id}/retable
Get project's tables
cURL
curl --request GET 'https://api.retable.io/v1/public/project/<project_id>/retable' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
get
https://api.retable.io/v1/public
/retable/{retable_id}
Get a Retable
cURL
curl --request GET 'https://api.retable.io/v1/public/retable/<retable_id>' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
Response will be the row data which is exactly the same as term. Term parameter accepts input with space. Example request and response are given below.
https://api.retable.io/v1/public/retable/jKN7x47LLjHZcXAv/search?columnID=eLfL2NyPMPrviXbn&term=Red%Rose%
{
"data": {
"rows": [
{
"row_id": 4,
"created_at": "2023-08-03 10:08:01",
"updated_at": "2023-08-15 11:01:47",
"created_by": {
"id": "lQ2vhlFYlgrXkAGe",
"name": "John",
"surname": "Doe",
"email": "[email protected]"
},
"updated_by": {
"id": "lQ2vhlFYlgrXkAGe",
"name": "John",
"surname": "Doe",
"email": "[email protected]"
},
"columns": [
{
"column_id": "eLfL2NyPMPrviXbn",
"title": "Name",
"cell_value": "Red Rose"
}
]
},
{
"row_id": 5,
"created_at": "2023-08-03 16:08:01",
"updated_at": "2023-08-15 17:01:47",
"created_by": {
"id": "lQ2vhlFYlgrXkAGe",
"name": "John",
"surname": "Doe",
"email": "[email protected]"
},
"updated_by": {
"id": "lQ2vhlFYlgrXkAGe",
"name": "John",
"surname": "Doe",
"email": "[email protected]"
},
"columns": [
{
"column_id": "eLfL2NyPMPrviXbn",
"title": "Name",
"cell_value": "Red Rose"
}
]
}
]
}
}
get
https://api.retable.io/v1/public
/retable/{retable_id}/search?columnID={columnID}&term={term}
Get specific terms at Retable
cURL
curl --request GET 'https://api.retable.io/v1/public/retable/<retable_id>/search?columnID=<columnID>&term=<term>' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
post
https://api.retable.io/v1/public
/project/{project_id}/retable
Create new Retable
cURL
curl --request POST 'https://api.retable.io/v1/public/project/<project_id>/retable' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--data-raw ''
post
https://api.retable.io/v1/public/
retable/{retable_id}/column
Add column
You can create basic column types, as follows:
- text
- number
- checkbox
- image
- calendar
- color
- email
- phonenumber
- percent
Use one of these types in the request's body for the column object type field. Otherwise, you will get a "Bad Request" error.
{
"columns": [
{
"title": "hello",
"type": "text"
}
]
}
cURL
curl --request POST 'https://api.retable.io/v1/public/retable/<retable_id>/column' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"columns": [
{
"title": "hello",
"type": "text"
}
]
}'
delete
https://api.retable.io/v1/public
/retable/{retable_id}/column
Delete Column
{
"column_ids": [
"<column_id>",
"<column_id>"
]
}
cURL
curl --request DELETE 'https://api.retable.io/v1/public/retable/<retable_id>/column/' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"column_ids": [
"<column_id>",
"<column_id>"
]
}'
Last modified 6d ago