# 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](https://app.retable.io) 

#### How to find my Retable API key?

<figure><img src="https://1709022688-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWwce7QQJjTB7U3RSKz%2Fuploads%2FueSia0DYIm6SNBKTmOiw%2Fimage.png?alt=media&#x26;token=2fbfed26-9dc3-482e-8f65-a1acf7e832af" alt=""><figcaption></figcaption></figure>

* Login to your Retable account
* Click on the name of the user which is on the right top of the screen. &#x20;
* Click API tab
* Enable and copy your API Key

User limitations are directly applied to API endpoints.

{% hint style="info" %}
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](https://discord.com/invite/3KtWYbgY7e)**.** Have fun!
{% endhint %}

#### 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](https://www.make.com/en/integrations/retable).

#### 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:&#x20;

\*\*<https://app.retable.io/retable/{workspace\\_id}/{project\\_id}/{retable\\_id}**&#x20>;

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.&#x20;

Through this menu, you can effortlessly access your workspace ID, project ID, table ID, and the total number of rows in the table.

<figure><img src="https://1709022688-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWwce7QQJjTB7U3RSKz%2Fuploads%2F36ez5QEPXSInPoWopkUR%2Fimage.png?alt=media&#x26;token=93986a56-d074-4ae6-87b8-bef83c145d09" alt=""><figcaption></figcaption></figure>

**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.&#x20;

<figure><img src="https://1709022688-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWwce7QQJjTB7U3RSKz%2Fuploads%2FFP9gXVaz0FUCTKPoXJEA%2Fimage.png?alt=media&#x26;token=25a7d872-833a-49e7-9aea-7c0eac761a2a" alt=""><figcaption></figcaption></figure>

You can use either the column ID or the column name in API connections.

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

{% hint style="info" %}
Retable API has a rate limit of 12 API calls/second. It returns an error if you exceed this limit.
{% endhint %}

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.

{% hint style="warning" %}
For the Beta version, we have not implemented any libraries. However, we are planning to add libraries in the coming versions.&#x20;
{% endhint %}

## General Objects

Requests expect a **JSON** body.

All responses come in a **JSON** object inside of a **data** field:&#x20;

```
{
    "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:&#x20;

* **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&#x20;

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 <a href="#returns-data-of-a-specific-retable" id="returns-data-of-a-specific-retable"></a>

## Get selected or all rows

<mark style="color:blue;">`GET`</mark> `https://api.retable.io/v1/public/retable/{retable_id}/data`

<mark style="color:blue;">`GET`</mark> `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.&#x20;

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

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| retable\_id<mark style="color:red;">\*</mark> | String | Id of the Retable |

#### Query Parameters

| Name    | Type   | Description   |
| ------- | ------ | ------------- |
| row\_id | String | Rows of table |

{% tabs %}
{% tab title="200: OK (v1) " %}

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

{% endtab %}

{% tab title="200: OK (v2)" %}

```
{
    "rows": [
        {
            "row_id": 1,
            "created_at": "2024-02-28 16:26:09",
            "updated_at": "2024-02-29 16:38:34",
            "created_by": "retable@retable.io",
            "updated_by": "retable@retable.io",
            "fields": {
                "Name": "Hello",
                "Text": "Retable",
                "Text (1)": "User"
            }
        },
        {
            "row_id": 2,
            "created_at": "2024-02-28 16:26:12",
            "updated_at": "2024-02-29 16:38:34",
            "created_by": "retable@retable.io",
            "updated_by": "retable@retable.io",
            "fields": {
                "Name": "V2",
                "Text": "Response",
                "Text (1)": "Here"
            }
        }
    ]
}
```

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}

{% tab title="404: Not Found Table not found with the given Id" %}

```javascript
{
    "statusCode": 404,
    "message": "Table not found",
    "error": "Not Found"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="cURL (v1)" %}

```bash
curl --request GET 'https://api.retable.io/v1/public/retable/<retable_id>/data' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
```

{% endtab %}

{% tab title="cURL (v2)" %}

```bash
curl --request GET 'https://api.retable.io/v2/public/retable/<retable_id>/data' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
```

{% endtab %}
{% endtabs %}

#### 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:

```json
{
    "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&#x20;
* **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

<mark style="color:green;">`POST`</mark> `https://api.retable.io/v1/public/retable/{retable_id}/data`

#### Path Parameters

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| retable\_id<mark style="color:red;">\*</mark> | String | Id of the Retable |

#### Request Body

| Name                                         | Type         | Description                                     |
| -------------------------------------------- | ------------ | ----------------------------------------------- |
| columns<mark style="color:red;">\*</mark>    | Object Array | An object with fields column\_*id & cell\_data* |
| column\_id<mark style="color:red;">\*</mark> | String       | Id of the column                                |
| cell\_data                                   | String       | Data that will be inserted into the new cell    |

{% tabs %}
{% tab title="201: Created Given Retable's all row data" %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "statusCode": 400,
    "message": "description",
    "error": "Bad Request"
}
```

{% endtab %}

{% tab title="404: Not Found Retable is not found" %}

```javascript
{
    "statusCode": 404,
    "message": "Table not found",
    "error": "Not Found"
}
```

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}

{% tab title="402: Payment Required User has exceeded the row limitation" %}

```javascript
{
    "statusCode": 402,
    "message": "row",
    "error": "Payment Required"
}
```

{% endtab %}
{% endtabs %}

#### 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'.&#x20;

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

The response will be the inserted values.

{% hint style="info" %}
If you do not provide the **cell\_value** field in the body, you will get a "Bad Request" error.
{% endhint %}

```json
{
    "data": [
        {
            "columns": [
                {
                    "column_id": "Bvt1FQhTyAPjmDx",
                    "cell_value": "Isengard"
                }
            ]
        },
        {
            "columns": [
                { 
                    "column_id": "Bvt1FQhTyAPjmDx",
                    "cell_value": "Rivendell"
                }
            ]
        }
    ]
}
```

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}
{% endtabs %}

#### Update the row of a specific Retable

{% hint style="info" %}
Only the owner or the editor roles can update a row. Otherwise, you will get a "Not Allowed" error.
{% endhint %}

## Update row

<mark style="color:orange;">`PUT`</mark> `https://api.retable.io/v1/public/retable/{retable_id}/data`

#### Path Parameters

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| retable\_id<mark style="color:red;">\*</mark> | String | Id of the Retable |

#### Request Body

| Name                                                  | Type         | Description                             |
| ----------------------------------------------------- | ------------ | --------------------------------------- |
| rows<mark style="color:red;">\*</mark>                | Object Array | An array of row objects                 |
| row\_id<mark style="color:red;">\*</mark>             | Integer      | Row Id of where the update will be done |
| columns<mark style="color:red;">\*</mark>             | Object Array | An array of column row data object      |
| column\_id<mark style="color:red;">\*</mark>          | String       | Id of the column                        |
| update\_cell\_value<mark style="color:red;">\*</mark> | String       | New cell value                          |

{% tabs %}
{% tab title="200: OK Array of updated row Ids" %}

```javascript
{
    "data": [
        2,
        3
    ]
}
```

{% endtab %}

{% tab title="404: Not Found Retable is not found" %}

```javascript
{
    "statusCode": 404,
    "message": "Table not found",
    "error": "Not Found"
}
```

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "statusCode": 400,
    "error": "Bad Request"
}
```

{% endtab %}
{% endtabs %}

#### Example body

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

```json
{
    "rows": [
        {
            "row_id": 2,
            "columns": [
                {
                    "column_id": "Bvt1FtQhTyAPjmDx",
                    "update_cell_value": "Mordor"
                }
            ]
        }
    ]
}
```

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}
{% endtabs %}

#### Delete row from a specific Retable

{% hint style="info" %}
Only the owner of the Retable can delete a row. Otherwise, you will get a "Not Allowed" error.
{% endhint %}

## Delete row

<mark style="color:red;">`DELETE`</mark> `https://api.retable.io/v1/public/retable/{retable_id}/data`

#### Path Parameters

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| retable\_id<mark style="color:red;">\*</mark> | String | Id of the Retable |

#### Request Body

| Name                                       | Type          | Description                       |
| ------------------------------------------ | ------------- | --------------------------------- |
| row\_ids<mark style="color:red;">\*</mark> | Integer Array | Row Ids that will be deleted rows |

{% tabs %}
{% tab title="400: Bad Request " %}

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

{% endtab %}

{% tab title="200: OK Count of deleted rows" %}

```javascript
{
    "data": {
        "deleted_row_count": 1
    }
}
```

{% endtab %}

{% tab title="404: Not Found Retable is not found" %}

```javascript
{
    "statusCode": 404,
    "message": "Table not found",
    "error": "Not Found"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
If the given row Id does not exist in the Retable, delete row request returns Status Ok&#x20;

with deleted\_*row*\_count is 0.
{% endhint %}

#### Example Body

```json
{
    "row_ids": [
        1
    ]
}
```

{% tabs %}
{% tab title="cURL" %}

```bash
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
    ]
}'
```

{% endtab %}
{% endtabs %}

#### Workspace

This includes workspace-related API operations.

#### Get user's workspaces

## Get all workspaces

<mark style="color:blue;">`GET`</mark> `https://api.retable.io/v1/public/workspace`

{% tabs %}
{% tab title="200: OK List of all workspaces" %}

```javascript
{
    "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
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl --location --request GET 'https://api.retable.io/v1/public/workspace' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
```

{% endtab %}
{% endtabs %}

#### Get a specific workspace and its projects

## Get a workspace

<mark style="color:blue;">`GET`</mark> `https://api.retable.io/v1/public/workspace/{workspace_id}`

#### Path Parameters

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| workspace\_id<mark style="color:red;">\*</mark> | String | Id of the workspace |

{% tabs %}
{% tab title="200: OK Given workspace's information" %}

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

{% endtab %}

{% tab title="404: Not Found There is not any workspace with the given Id" %}

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

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}
{% endtabs %}

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| workspace\_id<mark style="color:red;">\*</mark> | String | 4uKOsae419bI |

{% tabs %}
{% tab title="cURL" %}

```bash
curl --location --request GET 'https://api.retable.io/v1/public/workspace/<workspace_id>' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
```

{% endtab %}
{% endtabs %}

#### Create a new workspace with a default project

## Create a Workspace

<mark style="color:green;">`POST`</mark> `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

| Name        | Type   | Description                  |
| ----------- | ------ | ---------------------------- |
| name        | String | Name of the workspace        |
| description | String | Description of the workspace |

{% tabs %}
{% tab title="201: Created Information about created workspace" %}

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

{% endtab %}
{% endtabs %}

#### Example body

```json
{
    "name": "Workspace 1",
    "description": "Workspace Description"
}
```

{% tabs %}
{% tab title="cURL" %}

```bash
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"
}'
```

{% endtab %}
{% endtabs %}

#### How to find retable\_id <a href="#returns-data-of-a-specific-retable" id="returns-data-of-a-specific-retable"></a>

**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  <a href="#returns-data-of-a-specific-retable" id="returns-data-of-a-specific-retable"></a>

This includes project-related API operations.

#### Get all projects that belong to a specific workspace

## Get workspace's projects

<mark style="color:blue;">`GET`</mark> `https://api.retable.io/v1/public/workspace/{workspace_id}/project`

#### Path Parameters

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| workspace\_id<mark style="color:red;">\*</mark> | String | Id of the workspace |

{% tabs %}
{% tab title="404: Not Found Workspace is not found with the given Id." %}

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

{% endtab %}

{% tab title="200: OK Information about all projects that belongs to the given workspace." %}

```javascript
{
    "data": {
        "projects": [
            {
                "id": "FbytrkFrWUYf8OCP",
                "name": "Project 1",
                "description": null,
                "workspace_id": "Ouih48K5ZUeURf9K",
                "is_deleted": false,
                "created_by": {
                    "id": "PuNXWNo8nVWDSUrE",
                    "name": "Gandalf",
                    "surname": "The White",
                    "email": "gandalf@retable.io"
                },
                "created_at": "2022-04-01T05:33:05.691Z",
                "updated_at": "2022-04-01T05:33:05.778Z",
                "deleted_at": null
            }
        ],
        "count": 1
    }
}
```

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation." %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET 'https://api.retable.io/v1/public/workspace/<workspace_id>/project' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
```

{% endtab %}
{% endtabs %}

#### Get a specific project with retables <a href="#get-a-specific-project-with-retables" id="get-a-specific-project-with-retables"></a>

## Get a project

<mark style="color:blue;">`GET`</mark> `https://api.retable.io/v1/public/project/{project_id}`

#### Path Parameters

| Name                                          | Type   | Description        |
| --------------------------------------------- | ------ | ------------------ |
| project\_id<mark style="color:red;">\*</mark> | String | Id of the project. |

#### Query Parameters

| Name   | Type   | Description                                        |
| ------ | ------ | -------------------------------------------------- |
| limit  | Number | Number of records.                                 |
| offset | Number | Indicates of where to start within the result set. |

{% tabs %}
{% tab title="200: OK Information about given project" %}

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

{% endtab %}

{% tab title="404: Not Found Project is not found with the given Id." %}

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

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET 'https://api.retable.io/v1/public/project/<project_id>' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
```

{% endtab %}
{% endtabs %}

#### Create a project under the given workspace with a default retable

## Create Project

<mark style="color:green;">`POST`</mark> `https://api.retable.io/v1/public/workspace/{workspace_id}/project`

#### Path Parameters

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| workspace\_id<mark style="color:red;">\*</mark> | String | Id of the workspace |

#### Request Body

| Name                                   | Type   | Description                   |
| -------------------------------------- | ------ | ----------------------------- |
| name<mark style="color:red;">\*</mark> | String | Name of the project           |
| description                            | String | Description of the project    |
| color                                  | String | Hex color code of the project |

{% tabs %}
{% tab title="201: Created Information about created project" %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "statusCode": 400,
    "message": [
        "name should not be empty"
    ],
    "error": "Bad Request"
}
```

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```json
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}
{% endtabs %}

#### Example body

```json
{
    "name": "New Project 1",
    "description": "Project Description",
    "color": "#898cff"
}
```

{% tabs %}
{% tab title="cURL" %}

```bash
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"
}'
```

{% endtab %}
{% endtabs %}

#### 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**:

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

<mark style="color:blue;">`GET`</mark> `https://api.retable.io/v1/public/project/{project_id}/retable`

#### Path Parameters

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| project\_id<mark style="color:red;">\*</mark> | String | Id of the project |

{% tabs %}
{% tab title="404: Not Found Project not found with the given Id." %}

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

{% endtab %}

{% tab title="200: OK Given Project's Retable information" %}

```javascript
{
    "data": {
        "retables": [
            {
                "id": "EU9TfCkD4iXJuCcs",
                "title": "Retable 1",
                "description": null,
               "columns": [
                    {
                        "column_id": "Wlks9I8iZy1wj2KV",
                        "title": "Name",
                        "type": "text",
                        "created_at": "2023-03-23 11:48:13.886000"
                    },
                "project_id": "FbytrkFrWUYf8OCP",
                "workspace_id": "Ouih48K5ZUeURf9K",
                "created_by": {
                    "id": "PuNXWNo8nVWDSUrE",
                    "name": "Gandalf",
                    "surname": "The White",
                    "email": "gandalf@retable.io"
                },
                "deleted_by": null,
                "created_at": "2022-04-01T05:33:05.742Z",
                "updated_at": "2022-04-01T05:33:05.802Z",
                "deleted_at": null
            }
        ],
        "count": 1
    }
}
```

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET 'https://api.retable.io/v1/public/project/<project_id>/retable' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
```

{% endtab %}
{% endtabs %}

#### Upload file to project

## Upload file to project

<mark style="color:green;">`POST`</mark> `https://api.retable.io/v1/public/data/file/upload/{project_id}`

#### Path Parameters

| Name                                          | Type   | Description            |
| --------------------------------------------- | ------ | ---------------------- |
| project\_id<mark style="color:red;">\*</mark> | String | id of project          |
| title                                         | String | title of uploaded file |

#### Request Body

| Name                                   | Type      | Description                                 |
| -------------------------------------- | --------- | ------------------------------------------- |
| file<mark style="color:red;">\*</mark> | form-data | file with various extension and < 20mb size |

{% tabs %}
{% tab title="cURL" %}

```bash
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" \
```

{% endtab %}
{% endtabs %}

#### Get information about a specific Retable

## Get a Retable

<mark style="color:blue;">`GET`</mark> `https://api.retable.io/v1/public/retable/{retable_id}`

#### Path Parameters

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| retable\_id<mark style="color:red;">\*</mark> | String | Id of the retable |

{% tabs %}
{% tab title="200: OK Information about given Retable" %}

```javascript
{
    "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
    }
}
```

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}

{% tab title="404: Not Found There is not any Retable with the given retable Id." %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET 'https://api.retable.io/v1/public/retable/<retable_id>' \
--header 'ApiKey: <RTBLv1-YourAPIKey>'
```

{% endtab %}
{% endtabs %}

#### 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% 

```

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

<mark style="color:blue;">`GET`</mark> `https://api.retable.io/v1/public/retable/{retable_id}/search?columnID={columnID}&term={term}`

#### Path Parameters

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| retable\_id<mark style="color:red;">\*</mark> | String | Id of the retable |

#### Query Parameters

| Name                                       | Type   | Description                                        |
| ------------------------------------------ | ------ | -------------------------------------------------- |
| columnID<mark style="color:red;">\*</mark> | String | Id of the column                                   |
| term<mark style="color:red;">\*</mark>     | String | Search term                                        |
| limit                                      | Number | Number of records                                  |
| offset                                     | Number | Indicates of where to start within the result set. |
| columnIDs                                  | String | Search columns                                     |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="403: Forbidden " %}

```
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}

{% tab title="404: Not Found " %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="cURL" %}

<pre class="language-bash"><code class="lang-bash"><strong>curl --request GET 'https://api.retable.io/v1/public/retable/&#x3C;retable_id>/search?columnID=&#x3C;columnID>&#x26;term=&#x3C;term>' \
</strong>--header 'ApiKey: &#x3C;RTBLv1-YourAPIKey>'
</code></pre>

{% endtab %}
{% endtabs %}

#### Create a new Retable under a specific project

## Create new Retable

<mark style="color:green;">`POST`</mark> `https://api.retable.io/v1/public/project/{project_id}/retable`

This request does not need a body.

#### Path Parameters

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| project\_id<mark style="color:red;">\*</mark> | String | Id of the Project |

{% tabs %}
{% tab title="404: Not Found There is not any Retable with the given Id" %}

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

{% endtab %}

{% tab title="201: Created Information about created Retable" %}

```javascript
{
    "data": {
        "columns": [
            {
                "column_id": "V7RhuZTSN5Rqe3sp",
                "title": "Name",
                "type": "text"
            }
        ],
        "id": "K00aZ6F3W0ZhlOKC",
        "title": "Retable 3",
        "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-04T11:47:03.026Z",
        "updated_at": "2022-04-04T11:47:03.026Z",
        "deleted_at": null
    }
}
```

{% endtab %}

{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST 'https://api.retable.io/v1/public/project/<project_id>/retable' \
--header 'ApiKey: <RTBLv1-YourAPIKey>' \
--data-raw ''
```

{% endtab %}
{% endtabs %}

#### Creates a new column on the specific Retable

## Add column

<mark style="color:green;">`POST`</mark> `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.&#x20;

For this version, you can not change the order of the columns.

#### Path Parameters

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| retable\_id<mark style="color:red;">\*</mark> | String | Id of the Retable |

#### Request Body

| Name                                      | Type   | Description             |
| ----------------------------------------- | ------ | ----------------------- |
| columns<mark style="color:red;">\*</mark> | Array  | Array of column object  |
| title<mark style="color:red;">\*</mark>   | String | Title of the new column |
| type<mark style="color:red;">\*</mark>    | String | Type of the new column  |

{% tabs %}
{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "statusCode": 400,
    "message": "description",
    "error": "Bad Request"
}
```

{% endtab %}

{% tab title="201: Created Information about all columns in the given Retable" %}

```javascript
{
    "data": {
        "columns": [
            {
                "column_id": "Wlks9I8iZy1wj2KV",
                "title": "Name",
                "type": "text",
                "created_at": "2023-03-23 11:48:13.886000"
            },
            {
                "column_id": "cHm9UKL5zeaKAK9T",
                "title": "hello",
                "type": "text",
                "created_at": "2023-03-23 11:48:13.887000"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="404: Not Found There is not any Retable with the given Id" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

#### Example body

```json
{
    "columns": [
        {
            "title": "hello",
            "type": "text"
        }
    ]
}
```

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}
{% endtabs %}

#### Deletes column from a specific Retable

## Delete Column

<mark style="color:red;">`DELETE`</mark> `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.

#### Path Parameters

| Name                                          | Type   | Description       |
| --------------------------------------------- | ------ | ----------------- |
| retable\_id<mark style="color:red;">\*</mark> | String | Id of the Retable |

#### Request Body

| Name                                          | Type         | Description                              |
| --------------------------------------------- | ------------ | ---------------------------------------- |
| column\_ids<mark style="color:red;">\*</mark> | String Array | Ids of the columns which will be deleted |

{% tabs %}
{% tab title="403: Forbidden User does not have authorization to perform this operation" %}

```javascript
{
    "statusCode": 403,
    "message": "Not Allowed"
}
```

{% endtab %}

{% tab title="200: OK Remaining columns information in Retable after delete operation" %}

```javascript
{
    "data": {
        "columns": [
            {
                "column_id": "Wlks9I8iZy1wj2KV",
                "title": "Name",
                "type": "text",
                "created_at": "2023-03-23 11:48:13.886000"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "statusCode": 400,
    "message": "description",
    "error": "Bad Request"
}
```

{% endtab %}

{% tab title="404: Not Found There is not any Retable with the given Id" %}

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

{% endtab %}
{% endtabs %}

#### Example body

```json
{
    "column_ids": [
        "<column_id>",
        "<column_id>"
    ]
}
```

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}
{% endtabs %}