Links

Using the API

Retable public API documentation

Welcome to 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
To use Retable Public API, you have to obtain an API key from Retable.io

How to find my Retable API key?

  • Login to your Retable account
  • Click on the name of the user which is on the right top of the screen.
  • Click API tab
  • Enable and copy your API Key
User limitations are directly applied to API endpoints.
Retable API is in public beta. Several functionalities work perfectly, 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!

Retable Make Integration

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.

Retable Web App URL Structure

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
  • The first part after "retable" prefix is Workspace Id
  • The second part after Workspace Id is Project Id
  • The third part after Project Id is Retable Id
Hence, the overall URL structure is like this:
https://app.retable.io/retable/{workspace_id}/{project_id}/{retable_id}
Within the project menu, there is an information field that displays all relevant IDs for the current table. This field is helpful if you want to establish an API connection to your table.
Through this menu, you can effortlessly access your workspace ID, project ID, table ID, and the total number of rows in the table.

I

API key

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. Team members can have 2 API keys.
Retable API has a rate limit of 12 API calls/second. It returns an error if you exceed this limit.
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 and if your API key is disabled, a "423 locked" response will be returned.
For the Beta version, we have not implemented any libraries. However, we are planning to add libraries in the coming versions.

General Objects

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.

Data

This endpoint is for data related API operations.

Returns data of a specific Retable

get
https://api.retable.io/v1/public
/retable/{retable_id}/data
Get selected or all rows
cURL
curl --request GET 'https://api.retable.io/v1/public/retable/<retable_id>/data' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'

Response objects

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

Insert row to a specific Retable

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

Example body

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"
}
]
}
]
}'

Update the row of a specific Retable

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

Example body

{
"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"
}
]
}
]
}'

Delete row from a specific Retable

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.

Example Body

{
"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
]
}'

Workspace

This includes workspace-related API operations.

Get user's workspaces

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 a specific workspace and its projects

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>'

Create a new workspace with a default project

post
https://api.retable.io/v1/public
/workspace
Create a Workspace

Example body

{
"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"
}'

How to find retable_id

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}

Project

This includes project-related API operations.

Get all projects that belong to a specific workspace

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 a specific project with retables

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>'

Create a project under the given workspace with a default retable

post
https://api.retable.io/v1/public
/workspace/{workspace_id}/project
Create Project

Example body

{
"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

In this section, you can see available Retable endpoints and Retable related API operations.
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>'

Upload file to project

post
https://api.retable.io/v1/public/data/file/upload/{project_id}
Upload file to project
cURL
curl --request POST 'https://api.retable.io/v1/public/data/file/upload/<project_id>' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--header 'Content-Type: multipart/form-data' \
--form "file=@/path/to/your/file" \

Get information about a specific Retable

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>'

Get information about a specific Retable with JSON, XML, YAML, HTML format

You can receive the Retable response in JSON, YAML, XML and HTML formats by using a public share id. After copying the sharing link, any supported format is added to the end of the URL.
https://go.retable.io/<retable_share_id>/<format>
https://go.retable.io/4dvhJpM6LVTtjBG7/json
https://go.retable.io/4dvhJpM6LVTtjBG7/yaml
https://go.retable.io/view4dvhJpM6LVTtjBG7/xml
https://go.retable.io/view4dvhJpM6LVTtjBG7/html

Get specific information about a specific retable

Response will be the row data which is the same as a term. Term parameter accepts input with space. An example request and response is 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}
Search for a string in Retable
cURL
curl --request GET 'https://api.retable.io/v1/public/retable/<retable_id>/search?columnID=<columnID>&term=<term>' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'

Create a new Retable under a specific project

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 ''

Creates a new column on the specific Retable

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.

Example body

{
"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"
}
]
}'

Deletes column from a specific Retable

delete
https://api.retable.io/v1/public
/retable/{retable_id}/column
Delete Column

Example body

{
"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>"
]
}'
© 2023 Retable Limited | All product and company names and logos are trademarks of their respective owners