Using the API
Last updated
Last updated
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
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.
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.
Column ID
You can obtain the column ID by using the "Copy column ID" option in the column's right-click menu or by copying column IDs from the Customize Column screen.
You can use either the column ID or the column name in API connections.
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.
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.
Requests expect a JSON body.
All responses come in a JSON object inside of a data field:
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.
In the public API, the column orders correspond to those in your Default view.
This endpoint is for data related API operations.
GET
https://api.retable.io/v1/public/retable/{retable_id}/data
GET
https://api.retable.io/v2/public/retable/{retable_id}/data
Body
You can get the all the rows or specific rows that you want by adding row_id query param.
Even though v1 and v2 return same data, format is different. Could be choose to best suit for need.
All the rows must be separate with comma like ...data?row_id=1,2,3 when row_id query used. (Query limited with 50 rows.)
retable_id*
String
Id of the Retable
row_id
String
Rows of table
In this request's response, there is an object array called rows. This object contains information about a row.
An example row object:
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
retable_id*
String
Id of the Retable
columns*
Object Array
An object with fields column_id & cell_data
column_id*
String
Id of the column
cell_data
String
Data that will be inserted into the new cell
With the body example below, you will be inserting two rows with cell data 'Isengard' and 'Rivendell' to the column with Id 'Bvt1FQhTyAPjmDx'.
Null values can be entered and will be displayed as null in your data when using null.
The response will be the inserted values.
PUT
https://api.retable.io/v1/public/retable/{retable_id}/data
retable_id*
String
Id of the Retable
rows*
Object Array
An array of row objects
row_id*
Integer
Row Id of where the update will be done
columns*
Object Array
An array of column row data object
column_id*
String
Id of the column
update_cell_value*
String
New cell value
Null values can be entered and will be displayed as null in your data when using null.
DELETE
https://api.retable.io/v1/public/retable/{retable_id}/data
retable_id*
String
Id of the Retable
row_ids*
Integer Array
Row Ids that will be deleted rows
This includes workspace-related API operations.
GET
https://api.retable.io/v1/public/workspace
GET
https://api.retable.io/v1/public/workspace/{workspace_id}
workspace_id*
String
Id of the workspace
workspace_id*
String
4uKOsae419bI
POST
https://api.retable.io/v1/public/workspace
If the name is not given in the body, an auto-generated name will be assigned.
name
String
Name of the workspace
description
String
Description of the workspace
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
workspace_id*
String
Id of the workspace
GET
https://api.retable.io/v1/public/project/{project_id}
project_id*
String
Id of the project.
limit
Number
Number of records.
offset
Number
Indicates of where to start within the result set.
POST
https://api.retable.io/v1/public/workspace/{workspace_id}/project
workspace_id*
String
Id of the workspace
name*
String
Name of the project
description
String
Description of the project
color
String
Hex color code of the project
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:
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
project_id*
String
Id of the project
POST
https://api.retable.io/v1/public/data/file/upload/{project_id}
project_id*
String
id of project
title
String
title of uploaded file
file*
form-data
file with various extension and < 20mb size
GET
https://api.retable.io/v1/public/retable/{retable_id}
retable_id*
String
Id of the retable
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.
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.
GET
https://api.retable.io/v1/public/retable/{retable_id}/search?columnID={columnID}&term={term}
retable_id*
String
Id of the retable
columnID*
String
Id of the column
term*
String
Search term
limit
Number
Number of records
offset
Number
Indicates of where to start within the result set.
columnIDs
String
Search columns
POST
https://api.retable.io/v1/public/project/{project_id}/retable
This request does not need a body.
project_id*
String
Id of the Project
POST
https://api.retable.io/v1/public/retable/{retable_id}/column
As a response returns all existing columns and newly created columns.
Created columns are always appended to the end of the Retable's column array according to the given order in the body.
For this version, you can not change the order of the columns.
retable_id*
String
Id of the Retable
columns*
Array
Array of column object
title*
String
Title of the new column
type*
String
Type of the new column
DELETE
https://api.retable.io/v1/public/retable/{retable_id}/column
This endpoint expects a body that contains a string array called column_names. In this array, you have to insert column names that you want to delete. You can obtain column names by calling the GET Retable endpoint.
retable_id*
String
Id of the Retable
column_ids*
String Array
Ids of the columns which will be deleted
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 . 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 .