diff --git a/base_operations.yaml b/base_operations.yaml index cc8ef5e..6cbbe01 100644 --- a/base_operations.yaml +++ b/base_operations.yaml @@ -2422,7 +2422,7 @@ paths: avatar_url: https://cloud.seatable.io/media/avatars/default.png # Rows - /api-gateway/api/v2/dtables/{base_uuid}/sql: + /api-gateway/api/v2/dtables/{base_uuid}/sql/: post: tags: - Rows diff --git a/file_operations.yaml b/file_operations.yaml index d5d5bfd..fc5646e 100644 --- a/file_operations.yaml +++ b/file_operations.yaml @@ -348,7 +348,7 @@ paths: upload_link: "https://cloud.seatable.io/seafhttp/upload-api/e943a56a-c5b3-441a-ac1d-9199819dec71" parent_path: "/asset/1338f224-8482-4d71-b8be-63c8f37b896a/custom" relative_path": "/" - /api/v2.1/dtable/custom/app-download-link: + /api/v2.1/dtable/custom/app-download-link/: get: tags: [Files & Images (Custom Folder)] summary: Get Download Link diff --git a/intro/authentication.md b/intro/authentication.md index 74d3124..30ffba6 100644 --- a/intro/authentication.md +++ b/intro/authentication.md @@ -18,10 +18,6 @@ All other API-requests require an authorization header that looks like this, whe `Authorization: Bearer {{Account-Token, API-Token or Base-Token}}` -> 🚧 Self-hosted SeaTable need configuration change -> -> The **Try It!** function of this page works out of the box with SeaTable Cloud. But if you host your own SeaTable Server you have to [change your nginx configuration](/reference/requirement-self-hosted) to use this great feature. - > πŸ“˜ Bearer or Token? > > Before version 4.0, the authentication header in SeaTable was not like `Authorization: Bearer` but `Authorization: Token`. Starting with version 4.0 both authentication headers are supported. We recommend the use of `Authorization: Bearer`, according to the official [OpenAPI 3.0 Specifiation](https://swagger.io/docs/specification/authentication/bearer-authentication/). @@ -32,17 +28,17 @@ Initially, authentication in SeaTable can seem a bit complicated, but the follow ![Authentication Flow in SeaTable](https://seatable.com/openapi/authentication-flow-in-seatable2.png) -- Every **account operation** (Uuser, Team Admin or System Admin) requires an **Account-Token**. +- Every **account operation** (user, team admin or system admin) requires an **Account-Token**. - Every **base operation** requires a **Base-Token**. - Every **file operation** requires an **API-Token**. --- -## The three tokens +## SeaTable's three tokens > πŸ“˜ Account-Token > -> An **Account-Token** authenticates an _account API request_ (=Account Operations) like add a new base, add a group member or list all collaborators of a base. The Account-Token can be generated with the account-credentials. +> An **Account-Token** authenticates an _account API request_ (=account operations) like add a new base, add a group member or list all collaborators of a base. The Account-Token can be generated with the account-credentials. > πŸ“˜ API-Token > @@ -51,8 +47,8 @@ Initially, authentication in SeaTable can seem a bit complicated, but the follow > πŸ“˜ Base-Token > -> A **Base-Token** authenticates a _base API request_ (=Base Operations) like add a new row, append a row or delete a row. The Base-Token can be generated in many ways. The most common way is to use an API-Token. -> The read/write permission of an Base-Token depends on the read/write permission of the API-Token or the Account-Token it's generated from. Base-Token are valid for 3 days, therefore these must be generated regularly. +> A **Base-Token** authenticates a _base API request_ (=base operations) like add a new row, append a row or delete a row. The Base-Token can be generated in many ways. The most common way is to use an API-Token. +> The read/write permission of an Base-Token depends on the read/write permission of the API-Token or the Account-Token it's generated from. Base-Tokens are JWT tokens and are valid for 3 days, therefore these must be generated regularly. Here are the differences between these three tokens: @@ -60,21 +56,22 @@ Here are the differences between these three tokens: | :------------ | :-------- | :--------- | :----------------------------------------------------------------------------------- | | Account-Token | 40 chars | never | account privileges (user, team-admin, system admin) | | API-Token | 40 chars | never | allows generating a Base-Token for a specific base with either read or write access | -| Base-Token | >400 chars | 3 days | allow executing a Base-Operation with either read or write access to a specific base | +| Base-Token | >400 chars | 3 days | allows executing a Base-Operation with either read or write access to a specific base | + -> ❗ Keep your Tokens secure! +> ❗ Keep your tokens secure! > -> An Account-Token or an API-Token replaces the combination of username & password in a SeaTable API request. Once generated, such a Token is valid permanently. -> Therefore your Tokens have the same sensibility as your username and password, so make sure keep them in a safe place! +> An Account-Token or an API-Token replaces the combination of username & password in a SeaTable API request. Once generated, such a token is valid permanently. +> Therefore your tokens have the same sensibility as your username and password, so make sure keep them in a safe place! ### Token Hierarchy If you are working with the SeaTable API for the first time, the three different API-Tokens can be confusing. With a few exceptions, the following rule should help you: -- For all account operations, you need an account token. You create this token with your credentials. -- For practically all base operations, you require a base token. You generate this from an API token. +- For all account operations, you need an Account-Token. You create this token with your credentials. +- For practically all base operations, you require a Base-Token. You generate this from an API-Token. -Otherwise, it can be said that the Account-Token is the most powerful token because you can generate the other two tokens with it. With the API token, on the other hand, you can only generate a base token, and the base token can only be used to execute base operations. We call this the Token-Hierarchy of SeaTable. +Otherwise, it can be said that the Account-Token is the most powerful token because you can generate the other two tokens with it. With the API-Token, on the other hand, you can only generate a Base-Token, and the Base-Boken can only be used to execute base operations. We call this SeaTable's token hierarchy. ### Security @@ -82,6 +79,6 @@ Treat your tokens like passwords, so be sure to keep them secure! Do not share y ### Team Admin vs. System Admin -Account-Operations differentiate between User, Team Admin and System Admin. These are the three possible roles a user can have within SeaTable. Each user always has the User permission. The Team Admin or System Admin role must also be assigned to a user, and Team Admins only exist if teams/organizations are enabled in SeaTable. This is the case with , but is typically not the case with self-hosted SeaTable instances. +Account operations differentiate between user, team admin and system admin. These are the three possible user types a user can have within SeaTable. Each user always has the user permission. The team admin or system admin type must also be assigned to a user, and team admins only exist if teams/organizations are enabled in SeaTable. This is the case with , but is typically not the case with self-hosted SeaTable Server instances. More details on SeaTable's team/organization structure and admin management can be found at . diff --git a/intro/introduction.md b/intro/introduction.md index 3f57d2d..9b294fe 100644 --- a/intro/introduction.md +++ b/intro/introduction.md @@ -1,6 +1,6 @@ --- title: Introduction -excerpt: This is the reference for the SeaTable API. On this page you will find everything you need to use the SeaTable API. +excerpt: This is the reference for the SeaTable API. On this page you will find everything you need to know to use SeaTable's API. category: 67bd4bf716397e0037c123d0 isReference: true slug: introduction @@ -18,13 +18,13 @@ summary { } -The SeaTable API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. +The SeaTable API is organized around REST. This means: SeaTable's API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Take a look at our [development quick start guide](https://developer.seatable.com) for concrete examples or guided first steps. Or if you are not a developer, use [SeaTable’s no-code Integrations](https://seatable.com/integrations) like Zapier, Make.com or N8n to get started with SeaTable without any coding required. Almost all resources can be found in our [Help Area](https://help.seatable.com). -> πŸ‘ New Online Course Now Available: Level One (Beginner)! +> πŸ‘ New Online Courses Available: Level 1 (Beginner) and Level 2 (Intermediate)! > -> We are excited to announce the launch of our brand-new online course, designed especially for those who want to build a solid foundation in SeaTable. At the end of the course, you’ll have the opportunity to test your knowledge with a quiz. Successfully passing the quiz will earn you a new badge on SeaTable community forum, proudly displaying your proficiency level for everyone to see! +> We are excited to announce the launch of our brand-new online courses, designed especially for those who want to build a solid foundation in SeaTable. At the end of each course, you’ll have the opportunity to test your knowledge with a quiz. Successfully passing the quiz will earn you a new badge on [SeaTable Forum](https://forum.seatable.com), proudly displaying your proficiency level for everyone to see! > > Ready to get started? **[Let's go](https://seatable.com/help/first-steps/online-course/)** diff --git a/intro/limits.md b/intro/limits.md index 5d25583..1146ef7 100644 --- a/intro/limits.md +++ b/intro/limits.md @@ -12,21 +12,16 @@ slug: limits } -To ensure a consistent developer experience for all API users, the SeaTable-API is rate limited and denies further API requests as soon as the rate limit is reached. Furthermore, the amount of data dealing with one request is limited, too. +To ensure a consistently good user experience and protect the server, SeaTable limits the frequency of API calls (rate limit). Additionally, SeaTable limits the number of rows that can be modified with a single request (size limit). -## Rate limits -All SeaTable API endpoints, except `/ping` and `/server-info` have a rate limit. The concrete limits can be found in the following tables. The accesses are counted either per base, or if not available, per IP address. +## Rate Limits -Meaning that if you reach the rate limit for one base, you still could make requests for other bases. If you hit the rate limit, the request will return the HTTP response status **429** without any further output. +All SeaTable API endpoints, except `/ping` and `/server-info`, are subject to rate limits. The concrete limits can be found in the following tables. The calls are counted either per base, or if not available, per IP address. -> 🚧 Rate limits may change -> -> Currently, the same limits apply to all SeaTable Cloud customers. In the future, SeaTable might adjust the rate limits to balance for demand and reliability. SeaTable may also introduce distinct rate limits for teams with different pricing plans. - -### Retrieve current rate limit usage +Once the limit is reached, further requests are declined and SeaTable returns the HTTP response status **429** without any further output. -The `/api-gateway` endpoints return the current API rate limit usage through `x-ratelimit` headers. These headers provide the minute limit, the current usage, and the next reset time as a Unix timestamp in seconds. Below is an example of the returned headers: +The `/api-gateway` endpoints return the current API usage through `x-ratelimit` headers. These headers provide the minute limit, the current usage, and the next reset time as a Unix timestamp in seconds. Below is an example of the returned headers: ``` x-ratelimit-limit: 500 @@ -34,6 +29,10 @@ x-ratelimit-remaining: 493 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/). + ### General rate limits | Endpoints | SeaTable Cloud | SeaTable Dedicated and Server | @@ -47,7 +46,8 @@ x-ratelimit-reset: 1720710405 | :--------------------------------------- | :------------- | :---------------------------- | | Get Account-Token
`/api2/auth-token` | 60/min | unlimited | -## How to avoid the rate limits + +### How to avoid the rate limits To find out if you are rate-limited, look for the response status code `HTTP 429 Too Many Requests`. This response status code indicates that you sent too many requests in a given amount of time and need to make adjustments. @@ -59,21 +59,23 @@ If this is the case, you should start thinking about how to reduce the number of - Only request new data, if something changed. - Use SeaTable Webhooks to be informed about changes in your base instead of asking continuously for changes via the API. -## Customization of limits +### Customization of rate limits + +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: -SeaTable Dedicated customers and operators of their own SeaTable Server (Enterprise or Developer Edition) can adjust SeaTable's default limits according to their needs. These are the corresponding configuration files in the [SeaTable Admin Manual](https://admin.seatable.com): +- [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) -- [dtable-api-gateway.conf](https://admin.seatable.com/configuration/dtable-api-gateway-conf) -- [dtable_server_config.json](https://admin.seatable.com/configuration/dtable-server-config/) - deprecated -- [dtable-db.conf](https://admin.seatable.com/configuration/dtable-db-conf/) - deprecated -- [dtable_web_settings.py](https://admin.seatable.com/configuration/dtable-web-settings/) - deprecated +For more information about the configuration files, see the [SeaTable Admin Manual](https://admin.seatable.com). -## Size limits +## Size Limits -Besides the rate limits, there are size limits for how many rows you can manipulate with a **single call**. Of course, it is possible to execute multiple calls in a row as long as you stay below the rate limits. +Besides the rate limits, there are size limits for how many rows a **single call** can manipulate. Of course, it is possible to execute multiple calls in a row as long as you stay below the rate limits. -| Action and Endpoints | Max. number of rows | -| :--------------------------------------------------------------------------------------------------------------------------------------- | :------------------ | +| Action and Endpoints | Max. number of rows | +| :---------------------------------------------------------------------------------------------------------------------------------------- | :------------------ | | [List rows (with SQL)](https://api.seatable.com/reference/querysql)
`POST /api-gateway/api/v2/dtables/{...}/sql/` | 10.000 | | [Insert, Update or Delete Rows (with SQL)](https://api.seatable.com/reference/querysql)
`POST /api-gateway/api/v2/dtables/{...}/sql/` | unlimited | | [List rows](https://api.seatable.com/reference/listrows)
`GET /api-gateway/api/v2/dtables/{...}/rows/` | 1.000 | diff --git a/ping_and_info.yaml b/ping_and_info.yaml index db34e29..ac08ec2 100644 --- a/ping_and_info.yaml +++ b/ping_and_info.yaml @@ -113,7 +113,7 @@ paths: schema: $ref: "#/components/schemas/ping_response" - /dtable-db/ping: + /dtable-db/ping/: get: tags: - Ping @@ -128,7 +128,7 @@ paths: schema: $ref: "#/components/schemas/ping_response" - /api-gateway/api/v2/ping: + /api-gateway/api/v2/ping/: get: tags: - Ping diff --git a/team_admin_account_operations.yaml b/team_admin_account_operations.yaml index ae8ccce..f3c5cf2 100644 --- a/team_admin_account_operations.yaml +++ b/team_admin_account_operations.yaml @@ -1058,6 +1058,36 @@ paths: is_admin: false role: Member /api/v2.1/org/{org_id}/admin/groups/{group_id}/members/{user_id}/: + put: + tags: + - Groups + summary: Update Group Member Role + operationId: updateGroupMemberRole + description: Update a member's role. + security: + - AccountTokenAuth: [] + parameters: + - $ref: "#/components/parameters/org_id" + - $ref: "#/components/parameters/group_id" + - $ref: "#/components/parameters/user_id" + requestBody: + content: + application/json: + schema: + type: object + required: [is_admin] + properties: + is_admin: + # FIXME: The API should accept a boolean... + type: string + example: "true" + responses: + "200": + description: OK + content: + application/json: + schema: + type: object delete: tags: - Groups @@ -1079,7 +1109,7 @@ paths: type: object example: success: true - /api/v2.1/org/{org_id}/admin/dtables/{base_uuid}/shares: + /api/v2.1/org/{org_id}/admin/dtables/{base_uuid}/shares/: get: tags: - Bases @@ -1094,10 +1124,12 @@ paths: - $ref: "#/components/parameters/org_id" - $ref: "#/components/parameters/base_uuid" responses: - "401": - description: Successful response + "200": + description: OK content: - application/json: {} + application/json: + schema: + type: object # Sharing Links /api/v2.1/org/{org_id}/admin/external-links/: @@ -1509,6 +1541,8 @@ paths: description: OK content: application/json: + schema: + type: object example: { "logs": @@ -1570,6 +1604,8 @@ paths: description: OK content: application/json: + schema: + type: object example: { "login_list": @@ -1601,7 +1637,7 @@ paths: ], "total_count": 70, } - /api/v2.1/org/{org_id}/admin/login-logs/{user_id}: + /api/v2.1/org/{org_id}/admin/login-logs/{user_id}/: get: tags: - Activities & Logs @@ -1620,6 +1656,8 @@ paths: description: OK content: application/json: + schema: + type: object example: { "data": @@ -1661,6 +1699,8 @@ paths: description: OK content: application/json: + schema: + type: object example: { "file_access_log_list": [ @@ -1776,6 +1816,8 @@ paths: description: OK content: application/json: + schema: + type: object example: { "saml_config": diff --git a/user_account_operations.yaml b/user_account_operations.yaml index ae9a2c9..a550af6 100644 --- a/user_account_operations.yaml +++ b/user_account_operations.yaml @@ -7693,6 +7693,8 @@ paths: description: OK content: application/json: + schema: + type: object example: { "my_managed_apps": @@ -7943,7 +7945,7 @@ paths: insert_row: 0 modify_row: 1 delete_row: 0 - /api/v2.1/dtable-activities/detail: + /api/v2.1/dtable-activities/detail/: get: tags: [Activities & Logs] summary: Get Base Activity Details