From cd55f664baa730c894ef0d528459a5278ecebf4a Mon Sep 17 00:00:00 2001 From: Christoph Dyllick-Brenzinger Date: Mon, 18 Aug 2025 14:11:15 +0200 Subject: [PATCH 1/3] updated changelog --- .github/workflows/rdme-openapi.yml | 6 ------ intro/changelog.md | 4 ++-- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/.github/workflows/rdme-openapi.yml b/.github/workflows/rdme-openapi.yml index 9edf78d..cc6ec32 100644 --- a/.github/workflows/rdme-openapi.yml +++ b/.github/workflows/rdme-openapi.yml @@ -43,12 +43,6 @@ on: # replace in all other yaml files the version # local: git add . && git commit && git push --set-upstream origin v4.1 -## old description -# 0. create new branch at github. Fork the openapi-definition at seatable.readme.io -# 1. Switch the `branch` in this file at the top of this file -# 2. Get the new IDs for all API reference categories from seatable.readme.io (available at https://dash.readme.com/project/seatable/v4.0/reference and update the `--id` values in this workflow file. -# in the Markdown-files, the `category` has to be updated. # > you will need the `_id` of title: SeaTable API - jobs: rdme-openapi: runs-on: ubuntu-latest diff --git a/intro/changelog.md b/intro/changelog.md index 9088fe3..dfd6029 100644 --- a/intro/changelog.md +++ b/intro/changelog.md @@ -48,7 +48,7 @@ No further changes were made to the API documentation with v5.3. ## Version 5.1 (08.11.2024) -[View API Documentation for v5.1](https://api.seatable.com/v5.1) +The SeaTable API Reference for version 5.1 is no longer accessible here. However, you can find it on [Github](https://github.com/seatable/openapi/tree/v5.1). > 📘 New requests > @@ -65,7 +65,7 @@ No further changes were made to the API documentation with v5.3. ## Version 5.0 (15.07.2024) -[View API Documentation for v5.0](https://api.seatable.com/v5.0) +The SeaTable API Reference for version 5.0 is no longer accessible here. However, you can find it on [Github](https://github.com/seatable/openapi/tree/v5.0). We recommend using the new `/api-gateway/` endpoints. These endpoints are faster because they check if the base has remained unchanged since the last request, allowing for quicker responses. From 30b6a39a23e853b60cea305f83470a9d802319ed Mon Sep 17 00:00:00 2001 From: Christoph Dyllick-Brenzinger Date: Mon, 18 Aug 2025 14:15:19 +0200 Subject: [PATCH 2/3] headline structure of examples --- intro/introduction.md | 56 ++++++++++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 22 deletions(-) diff --git a/intro/introduction.md b/intro/introduction.md index 9b294fe..1c87c3b 100644 --- a/intro/introduction.md +++ b/intro/introduction.md @@ -51,13 +51,15 @@ So don't let us waste time and let's start right away. The first step with every
Write data to a base and read it out again
-### Step 1: Create an API-Token +### Write data to a base and read it out again + +#### Step 1: Create an API-Token The first step is to create an `API-Token` with write permission for one of your bases at SeaTable Cloud. If you don't know how to do this, check this [help article](https://seatable.com/help/erzeugen-eines-api-tokens/). You only have to do this once! The `API-Token` keeps valid forever for this specific base. Of course you can generate as many `API-Tokens` as you want. You can even use the API to [generate additional API-Tokens](https://api.seatable.com/reference/createapitoken). An API-Token might look like this: `1de50f1a57143bfe72873cbbd28ecb4de9eb3c61` -### Step 2: Generate Base-Token +#### Step 2: Generate Base-Token Next you need the API-Token to [generate a Base-Token](https://api.seatable.com/reference/getbasetokenwithapitoken). The `Base-Token` is only valid for three days and exactly for the one base for which you created the API-Token. If you want to interact with your base more frequently via API, you need to repeat this step. You need the `Base-Token` to authenticate all the following API requests. @@ -76,7 +78,7 @@ The result of the [Get Base-Token with API-Token](https://api.seatable.com/refer } ``` -### Step 3: Get to know the structure of your base +#### Step 3: Get to know the structure of your base Equipped with the `Base-Token` we can start to display the current structure of the base. Use the [Get Metadata](https://api.seatable.com/reference/getmetadata) request and pass the `Base-Token` and the `base_uuid` as parameters. The result will be a very long _metadata_ object which contains all _tables_ with all their _columns_ and _views_. The _metadata_ does not contain any data, it contains only the structure of your base. @@ -109,7 +111,7 @@ Use the small arrows in the response box to fold the elements to get an overview Note down the name of the tables and the name of the columns. You will need these values to write a new row to this table. -### Step 4: Write some data to your base +#### Step 4: Write some data to your base The request to [Append Rows](https://api.seatable.io/reference/appendrows) to a base, requires the following information. You have to know ... @@ -129,7 +131,7 @@ At first it looks difficult to define the row objects, but in fact it is quite e Easy, right? This documentation helps you to create the API request just by filling out all the input fields. The code that is generated in the right black box, is the API request that you can execute either via this page or with any programming language. -### Step 5: Get all rows of your base +#### Step 5: Get all rows of your base Also this last step is quite easy. Use the [List rows](https://api.seatable.com/reference/listrows) request and fill all mandatory input fields. Leave all optional fields blank and hit the **Try It!** button. You should see your previously created line with John Doe now in the result list. @@ -140,7 +142,9 @@ Congratulations! You wrote your first row to a table in a base in SeaTable via t
Create a new base, a new table and add two new columns
-### Step 1: Generate an Account-Token +### Create a new base, a new table and add two new columns + +#### Step 1: Generate an Account-Token SeaTable requires a different authentication depending on whether you want to do something inside a base or outside. To create a Base, we need an account token, which we can generate with our credentials. Therefore you have to use the [Get Account-Token with Username and Password](https://api.seatable.com/reference/getaccounttokenfromusername). Fill in your username and password and hit **Try It!**. The result will be your `Account-Token` which might look like this: @@ -150,16 +154,16 @@ SeaTable requires a different authentication depending on whether you want to do } ``` -### Step 2: Find out the workspace id +#### Step 2: Find out the workspace id To generate a base inside SeaTable you have to tell SeaTable where the base should be created. It could be in the area of `My bases` or it could be in one of your groups. To define the target where you want to create a base you have to provide the `workspace_id`. The easiest way to determine the workspace id of a group or `My bases` is to open a base of that area in the browser and look at the URL. This [help article](https://seatable.com/help/workspace-id-einer-gruppe-ermitteln/) explains this in more details. Open the base and write down the workspace id. -### Step 3: Create the base +#### Step 3: Create the base Equiped with all these information it should be easy for you to create a new base. Use the request [Create base](https://api.seatable.com/reference/createbase) and fill out all the required values and hit **Try It!**. Every new base will automatically contain a first empty table with the name `Table1`. -### Step 4: Create a table and two columns (you will need a Base-Token) +#### Step 4: Create a table and two columns (you will need a Base-Token) The following requests have to be executed inside the base. There the necessary API calls can be found in the area **Base operations** and you will need a [Base-Token](https://api.seatable.com/reference/getbasetokenwithapitoken) instead of an account-token. Check example no. 1 if you don't know how to create a Base-Token. @@ -173,11 +177,13 @@ Congratulations! You created your first base with a seconds table and some extra
Update the content of a specific row
-### Step 0: Generate a Base-Token +### Update the content of a specific row + +#### Step 0: Generate a Base-Token Generate a Base-Token like in example no. 1. This will also give you the `base_uuid`. -### Step 1: Determine the row you would like to update +#### Step 1: Determine the row you would like to update To [update a row](https://api.seatable.com/reference/updaterow) you need to know the row_id you want to update. You can either get the `row_id` just by [opening the row details in the browser](https://seatable.com/help/was-ist-die-zeilen-id/) or you could use one of the various API requests to get the content of a base: @@ -185,7 +191,7 @@ To [update a row](https://api.seatable.com/reference/updaterow) you need to know - [List Rows](https://api.seatable.com/reference/listrows) - [Base Info](https://api.seatable.com/reference/getbaseinfo) -### Step 2: Update the row +#### Step 2: Update the row Next you have all the information to [update a row](https://api.seatable.com/reference/updaterow). You can easily update multiple values in the row specified by the `row_id`. The `row` object contains `key:value` pairs with the column name as key and the desired values. @@ -194,11 +200,13 @@ Next you have all the information to [update a row](https://api.seatable.com/ref
Upload a file to a file column
-### Step 0: Prerequisites +### Upload a file to a file column + +#### Step 0: Prerequisites I assume that you already have a base with a table in which a file column exists. In addition I assume that you know how to generate a [Base-Token](https://api.seatable.com/reference/getbasetokenwithapitoken) from an API-Token. If not, check out the first example. -### Step 1: Generate an upload link for this base +#### Step 1: Generate an upload link for this base First we have to [generate an upload link](https://api.seatable.com/reference/getuploadlink). Be aware that this requests needs the API-Token for authentification, because technically speaking it does not happen inside a base. @@ -215,7 +223,7 @@ The result will be look like this: This is a temporary path, where SeaTable accepts new files that can be uploaded either to an images or a files directory. -### Step 2: Upload the file +#### Step 2: Upload the file Next you have to really upload the file to the base. The right API request is [Upload a file](https://api.seatable.com/reference/uploadfile). You have to provide the information you received from the last call. Don't get confused about `parent_path` and `parent_dir`. These are just the same values. @@ -230,7 +238,7 @@ Here is the input you should use: (example data) As soon as you uploaded the file, it can be found via the [file management of the base](https://seatable.com/help/das-dateimanagement-einer-base/). To append the file an image or file column, you still need another API request. -### Step 3: Update an existing file/image column +#### Step 3: Update an existing file/image column Now you have to [update a row](https://api.seatable.com/reference/updaterow) and write the required information of the previously uploaded file to the right file/image column. Do not be confused by the fact that the upload of a file and an image is different. The `row` element has to be different. In case of an image you just have to provide the internal URL of the image as an array item. In cas of a file you have to provide more informations as an object. @@ -261,11 +269,13 @@ Do not be confused by the fact that the upload of a file and an image is differe
Get more information about your team (as team admin)
-### Step 0: Prerequisites +### Get more information about your team (as team admin) + +#### Step 0: Prerequisites The following example can only be executed as team admin. All requests require an `account-token` that you can generate with your username and password. An API-Token or a Base-Token is useless in this case because we will only execute requests from the area **Account Operations - Team Admin**. -### Step 1: Get an Account-Token +#### Step 1: Get an Account-Token Start with the call [Get Account Token](https://api.seatable.com/reference/getaccounttokenfromusername). It requires your username and password and will return your `account-token`. Threat this token like your password, because it can be used to execute all types of account operations. @@ -275,7 +285,7 @@ Start with the call [Get Account Token](https://api.seatable.com/reference/getac } ``` -### Step 2: Get info about your team and your team members +#### Step 2: Get info about your team and your team members As soon as you have your `account-token` it is easy to get more information about your team and your team members. Use one of the following calls: @@ -290,15 +300,17 @@ Great. Now you can get all the information of your team via API.
Create a new user and enforce 2FA for this user
-### Step 1: Get an Account-Token +### Create a new user and enforce 2FA for this user + +#### Step 1: Get an Account-Token Like as in the last example, start with the call [Get Account Token](https://api.seatable.com/reference/getaccounttokenfromusername). -### Step 2: Get the user id of the user +#### Step 2: Get the user id of the user To enforce 2-Factor-Authentification (2FA) for one of your team members, you need the `email` (sometimes also call `user_id`). Every user has a unique email adress like `123456789f1e4c8d8e1c31415867317c@auth.local`. Use [List Team Members](https://api.seatable.com/reference/listteamusers-1) to get this unique value of the user you want to update. -### Step 3: Enforce 2FA +#### Step 3: Enforce 2FA Equipped with this `email` of the user, you can [Enforce 2FA](https://api.seatable.com/reference/enforcetwofactor-1) for this user. The next time the user opens SeaTable in his browser, he has to register for 2FA. From 34738c6d2dbcb84a6ccbdb574ba7875d1f64cbb4 Mon Sep 17 00:00:00 2001 From: Christoph Dyllick-Brenzinger Date: Mon, 18 Aug 2025 14:22:09 +0200 Subject: [PATCH 3/3] format limits and remove glossary --- intro/glossary.md | 26 -------------------------- intro/limits.md | 8 ++++++-- 2 files changed, 6 insertions(+), 28 deletions(-) delete mode 100644 intro/glossary.md diff --git a/intro/glossary.md b/intro/glossary.md deleted file mode 100644 index bb018ce..0000000 --- a/intro/glossary.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Glossary -excerpt: -category: 67bd4bf716397e0037c123d0 -isReference: true -slug: glossary ---- - -In this table, you will find all used and SeaTable specific terms of this API-documentation. - -| a | b | | -| :-- | :-- | :-- | -| | | | -| | | | - - > 📘 The asdf - > - > An Account-Token replaces the combination of username & password in a SeaTable API request. - - > 🚧 - > - > asdfadfaf - - > 👍 adfafaf - > - > asdafaf `dfaf` adfadfaf diff --git a/intro/limits.md b/intro/limits.md index 1146ef7..d9a3434 100644 --- a/intro/limits.md +++ b/intro/limits.md @@ -31,7 +31,11 @@ x-ratelimit-reset: 1720710405 > ❗ SeaTable Cloud: Monthly API limits > -> Due to excessive use of SeaTable Cloud's API by some users, SeaTable Cloud introduced monthly API limits in the summer 2025. (In this [blog post](https://seatable.com/api-gateway-version-5-3/), you find background information.) The monthly API limits are a function of the subscription and the number of users in the team. The limit is automatically reset at the end of each month. If you have exhausted your API limit for the month, you can upgrade your subscription to SeaTable Cloud and/or add more users to your paid subscription. The extra API calls are available momentarily after the upgrade. For more information on the specific limits, see the [pricing page](https://seatable.com/de/preise/). +> Due to excessive use of SeaTable Cloud's API by some users, SeaTable Cloud introduced monthly API limits in the summer 2025. (In this [blog post](https://seatable.com/api-gateway-version-5-3/), you find background information.) > +> +> The monthly API limits are a function of the subscription and the number of users in the team. The limit is automatically reset at the end of each month. +> +> If you have exhausted your API limit for the month, you can upgrade your subscription to SeaTable Cloud and/or add more users to your paid subscription. The extra API calls are available momentarily after the upgrade. For more information on the specific limits, see the [pricing page](https://seatable.com/de/preise/). ### General rate limits @@ -63,7 +67,7 @@ If this is the case, you should start thinking about how to reduce the number of If you are a SeaTable Dedicated customer or you run your own SeaTable Server instance (Enterprise and Developer Edition), you can modify the default limits. The limits are set in configuration files. Beginning with SeaTable Server v5.3, the limits are defined in one single configuration file. In prior versions, updating rate limits involved modifying multiple configuration files: -- [dtable-api-gateway.conf](https://admin.seatable.com/configuration/dtable-api-gateway-conf) (from version 5.3) +- [dtable-api-gateway.conf](https://admin.seatable.com/configuration/dtable-api-gateway-conf) (**from** version 5.3) - [dtable_server_config.json](https://admin.seatable.com/configuration/dtable-server-config/) - (before version 5.3) - [dtable-db.conf](https://admin.seatable.com/configuration/dtable-db-conf/) (before version 5.3) - [dtable_web_settings.py](https://admin.seatable.com/configuration/dtable-web-settings/) (before version 5.3)