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.

Column ID

Get the ID of the column with the "Copy column ID" option in the column's right-click menu. If you require your Column ID for API connections or integrations, you can access this information quickly.

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.

In the public API, the column orders correspond to those in your Default view.

Data

This endpoint is for data related API operations.

Returns data of a specific Retable

Get selected or all rows

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.)

Path Parameters

Query Parameters

{
    "data": {
        "rows": [
            {
                "row_id": 1,
                "created_at": "2022-04-04 17:47:03",
                "updated_at": null,
                "created_by": {
                    "id": "PuNXWNo8nVWDSUrE",
                    "name": "Emre",
                    "surname": "ARI",
                    "email": "hemre@retable.io"
                },
                "updated_by": null,
                "columns": [
                    {
                        "column_id": "Wlks9I8iZy1wj2KV",
                        "title": "Name",
                        "cell_value": null
                    }
                ]
            }
        ]
    }
}
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": "gandalf@retable.io"
   },
   "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.

Insert Row

POST https://api.retable.io/v1/public/retable/{retable_id}/data

Path Parameters

Request Body

{
    "data": {
        "rows": [
            {
                "row_id": 1,
                "created_at": "2022-04-05 21:26:35",
                "updated_at": null,
                "created_by": {
                    "id": "PuNXWNo8nVWDSUrE",
                    "name": "Gandalf",
                    "surname": "The White",
                    "email": "gandalf@retable.io"
                },
                "updated_by": null,
                "columns": [
                    {
                        "column_id": "Wlks9I8iZy1wj2KV",
                        "title": "Name",
                        "cell_value": null
                    }
                ]
            },
            {
                "row_id": 2,
                "created_at": "2022-04-05 21:31:17",
                "updated_at": null,
                "created_by": {
                    "id": "PuNXWNo8nVWDSUrE",
                    "name": "Gandalf",
                    "surname": "The White",
                    "email": "gandalf@retable.io"
                },
                "updated_by": null,
                "columns": [
                    {
                        "column_id": "Wlks9I8iZy1wj2KV",
                        "title": "Name",
                        "cell_value": null
                    }
                ]
            }
        ]
    }
}

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

Null values can be entered and will be displayed as null in your data when using null.

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

Update row

PUT https://api.retable.io/v1/public/retable/{retable_id}/data

Path Parameters

Request Body

{
    "data": [
        2,
        3
    ]
}

Example body

Null values can be entered and will be displayed as null in your data when using null.

{
    "rows": [
        {
            "row_id": 2,
            "columns": [
                {
                    "column_id": "Bvt1FtQhTyAPjmDx",
                    "update_cell_value": "Mordor"
                }
            ]
        }
    ]
}
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 row

DELETE https://api.retable.io/v1/public/retable/{retable_id}/data

Path Parameters

Request Body

{
    "statusCode": 400,
    "message": "Bad Request"
}

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 --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 all workspaces

GET https://api.retable.io/v1/public/workspace

{
    "data": {
        "workspaces": [
            {
                "id": "Ouih48K5ZUeURf9K",
                "name": "asdf",
                "description": null,
                "created_by": {
                    "id": "PuNXWNo8nVWDSUrE",
                    "name": "Gandalf",
                    "surname": "The White",
                    "email": "gandalf@retable.io"
                },
                "updated_by": null,
                "deleted_by": null,
                "created_at": "2022-04-01T05:32:33.191Z",
                "updated_at": null,
                "deleted_at": null
            }
        ],
        "count": 1
    }
}
curl --location --request GET 'https://api.retable.io/v1/public/workspace' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'

Get a specific workspace and its projects

Get a workspace

GET https://api.retable.io/v1/public/workspace/{workspace_id}

Path Parameters

{
    "data": {
        "id": "Ouih48K5ZUeURf9K",
        "name": "Workspace 1",
        "description": null,
        "created_by": {
            "id": "PuNXWNo8nVWDSUrE",
            "name": "Gandalf",
            "surname": "The White",
            "email": "gandalf@retable.io"
        },
        "updated_by": null,
        "deleted_by": null,
        "created_at": "2022-04-01T05:32:33.191Z",
        "updated_at": null,
        "deleted_at": null,
        "projects": [
            {
                "id": "wAphXdpamG7Vmncg",
                "name": "Project 1",
                "description": null,
                "is_deleted": false,
                "created_by": {
                    "id": "kucnOLo3nxjpqUro",
                    "name": "Saruman",
                    "surname": "The Wise",
                    "email": "saruman@retable.io"
                },
                "updated_by": null,
                "deleted_by": null,
                "created_at": "2022-04-01T05:32:33.318Z",
                "updated_at": "2022-04-01T05:32:33.507Z",
                "deleted_at": null
            }
        ]
    }
}
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

Create a Workspace

POST https://api.retable.io/v1/public/workspace

If the name is not given in the body, an auto-generated name will be assigned.

Request Body

{
    "data": {
        "id": "AzfsFrcu4ofIgsns",
        "name": "Workspace 1",
        "description": "Ws Description",
        "created_by": {
            "id": "PuNXWNo8nVWDSUrE",
            "name": "Gandalf",
            "surname": "The White",
            "email": "gandalf@retable.io"
        },
        "updated_by": null,
        "deleted_by": null,
        "created_at": "2022-04-04T09:29:37.198Z",
        "updated_at": null,
        "deleted_at": null,
        "projects": [
            {
                "id": "9yOtbIrDGUhxl8zT",
                "name": "To-Do List",
                "description": null,
                "is_deleted": false,
                "created_by": {
                    "id": "PuNXWNo8nVWDSUrE",
                    "name": "Gandalf",
                    "surname": "The White",
                    "email": "gandalf@retable.io"
                },
                "updated_by": null,
                "deleted_by": null,
                "created_at": "2022-04-04T09:29:37.287Z",
                "updated_at": "2022-04-04T09:29:37.287Z",
                "deleted_at": null
            }
        ]
    }
}

Example body

{
    "name": "Workspace 1",
    "description": "Workspace Description"
}
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 workspace's projects

GET https://api.retable.io/v1/public/workspace/{workspace_id}/project

Path Parameters

{
    "statusCode": 404,
    "message": "Not Found"
}
curl --request GET 'https://api.retable.io/v1/public/workspace/<workspace_id>/project' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'

Get a specific project with retables

Get a project

GET https://api.retable.io/v1/public/project/{project_id}

Path Parameters

Query Parameters

{
    "data": {
        "id": "FbytrkFrWUYf8OCP",
        "name": "Project 1",
        "description": null,
        "is_deleted": false,
        "created_by": {
            "id": "PuNXWNo8nVWDSUrE",
            "name": "Gandalf",
            "surname": "The White",
            "email": "gandalf@retable.io"
        },
        "updated_by": null,
        "deleted_by": null,
        "created_at": "2022-04-01T05:33:05.691Z",
        "updated_at": "2022-04-01T05:33:05.778Z",
        "deleted_at": null,
        "retables": [
            {
                "columns": [],
                "id": "EU9TfCkD4iXJuCcs",
                "title": "Retable 1",
                "description": null,
                "created_by": {
                    "id": "PuNXWNo8nVWDSUrE",
                    "name": "Gandalf",
                    "surname": "The White",
                    "email": "gandalf@retable.io"
                },
                "updated_by": null,
                "deleted_by": null,
                "created_at": "2022-04-01T05:33:05.742Z",
                "updated_at": "2022-04-01T05:33:05.802Z",
                "deleted_at": null
            }
        ]
    }
}
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

Create Project

POST https://api.retable.io/v1/public/workspace/{workspace_id}/project

Path Parameters

Request Body

{
    "data": {
        "id": "W6lu54gG1ucP96cA",
        "name": "Project 1",
        "description": null,
        "is_deleted": false,
        "created_by": {
            "id": "PuNXWNo8nVWDSUrE",
            "name": "Gandalf",
            "surname": "The White",
            "email": "gandalf@retable.io"
        },
        "updated_by": null,
        "deleted_by": null,
        "created_at": "2022-04-04T09:51:27.614Z",
        "updated_at": "2022-04-04T09:51:27.614Z",
        "deleted_at": null,
        "retables": [
            {
                "columns": [
                    {
                        "column_id": "3OcxjMTNM3jOv8cS",
                        "title": "Name",
                        "type": "text"
                    }
                ],
                "id": "bUzRNCYsbPPw2tb3",
                "title": "Retable 1",
                "description": null,
                "created_by": {
                    "id": "PuNXWNo8nVWDSUrE",
                    "name": "Gandalf",
                    "surname": "The White",
                    "email": "gandalf@retable.io"
                },
                "updated_by": null,
                "deleted_by": null,
                "created_at": "2022-04-04T09:51:27.671Z",
                "updated_at": "2022-04-04T09:51:27.671Z",
                "deleted_at": null
            }
        ]
    }
}

Example body

{
    "name": "New Project 1",
    "description": "Project Description",
    "color": "#898cff"
}
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 project's tables

GET https://api.retable.io/v1/public/project/{project_id}/retable

Path Parameters

{
    "statusCode": 404,
    "message": "Not Found"
}
curl --request GET 'https://api.retable.io/v1/public/project/<project_id>/retable' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'

Upload file to project

Upload file to project

POST https://api.retable.io/v1/public/data/file/upload/{project_id}

Path Parameters

Request Body

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 a Retable

GET https://api.retable.io/v1/public/retable/{retable_id}

Path Parameters

{
    "data": {
    "columns": [
            {
                "column_id": "Wlks9I8iZy1wj2KV",
                "title": "Name",
                "type": "text",
                "created_at": "2023-03-23 11:48:13.886000"
            },
        ],
        "id": "6EgxjV2PsLu2a41b",
        "title": "Retable 1",
        "description": null,
        "created_by": {
            "id": "PuNXWNo8nVWDSUrE",
            "name": "Gandalf",
            "surname": "The White",
            "email": "hemre@retable.io"
        },
        "updated_by": null,
        "deleted_by": null,
        "created_at": "2022-04-01T05:33:05.742Z",
        "updated_at": "2022-04-01T05:33:05.802Z",
        "deleted_at": null
    }
}
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": "johndoe@retable.io"
                },
                "updated_by": {
                    "id": "lQ2vhlFYlgrXkAGe",
                    "name": "John",
                    "surname": "Doe",
                    "email": "johndoe@retable.io"
                },
                "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": "johndoe@retable.io"
                },
                "updated_by": {
                    "id": "lQ2vhlFYlgrXkAGe",
                    "name": "John",
                    "surname": "Doe",
                    "email": "johndoe@retable.io"
                },
                "columns": [
                    {
                        "column_id": "eLfL2NyPMPrviXbn",
                        "title": "Name",
                        "cell_value": "Red Rose"
                    }
                ]
            }
        ]
    }
}

Search for a string in Retable

GET https://api.retable.io/v1/public/retable/{retable_id}/search?columnID={columnID}&term={term}

Path Parameters

Query Parameters

{
    "data": {
        "rows": [
            {
                "row_id": 3,
                "created_at": "2024-03-29 12:18:32",
                "updated_at": "2024-03-31 18:43:19",
                "created_by": {
                    "id": "rAX2bsbNbxMi28sD",
                    "name": "John",
                    "surname": "Doe",
                    "email": "johndoe@retable.io"
                },
                "updated_by": {
                    "id": "rAX2bsbNbxMi28sD",
                    "name": "John",
                    "surname": "Doe",
                    "email": "johndoe@retable.io"
                },
                "columns": [
                    {
                        "column_id": "coZzjlzdf0SK8LIi",
                        "title": "EMPLOYEE ID",
                        "cell_value": "102362"
                    },
                    {
                        "column_id": "82zVQDihAc34z47S",
                        "title": "NAME",
                        "cell_value": "Harry"
                    },
                    {
                        "column_id": "7pTINVlnlURTJhyF",
                        "title": "SURNAME",
                        "cell_value": "Sanders"
                    },
                    {
                        "column_id": "WN4Yk7IXw5hhqc3p",
                        "title": "DEPARTMENT NAME",
                        "cell_value": "Manager"
                    },
                    {
                        "column_id": "5VKe1xpSIGxbjTgx",
                        "title": "BIRTHDAY",
                        "cell_value": "6/30/1958"
                    },
                    {
                        "column_id": "zI2iOMOxiliHuanm",
                        "title": "SALARY",
                        "cell_value": "50155"
                    },
                    {
                        "column_id": "FIbB1gyoIPqYHhKz",
                        "title": "Text",
                        "cell_value": null
                    },
                    {
                        "column_id": "ZOImbJjcNY1xl2eC",
                        "title": "Age in Company (Years)",
                        "cell_value": "0.98"
                    }
                ]
            }
        ]
    }
}
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

Create new Retable

POST https://api.retable.io/v1/public/project/{project_id}/retable

This request does not need a body.

Path Parameters

{
    "statusCode": 404,
    "message": "Not Found"
}