Using the API

Retable public API documentation
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
To use Retable Public API, you have to obtain an API key from Retable.io on the profile tab. 
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!
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
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} 
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. 
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. 
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 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 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 all 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
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 all Retables that belong to a specific project
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 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 specific information about a specific retable
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>'
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>"
    ]
}'
Managing Retable - Previous
Audit logs
Last modified 6d ago