docs: release the cloud 1.18.0 docs

en/api-reference/guides/errors.mdx

@@ -4,7 +4,7 @@ sidebarTitle: Errors & Rate Limits
 description: The error envelope, what each status class means, and which failures are worth retrying
 ---
 
-Every documented error uses the same three-field JSON envelope:
+App and classic knowledge base endpoints return errors in the same three-field JSON envelope:
 
 ```json
 {
@@ -16,18 +16,26 @@ Every documented error uses the same three-field JSON envelope:
 
 `status` mirrors the HTTP status; `code` is the stable identifier to branch on; `message` is human-readable detail. Each endpoint page lists exactly which codes it can raise.
 
+<Info>
+The agent knowledge base API uses the same three fields and adds a `failure` object to many errors. For what `failure` tells you and when to retry, see its [Handle Errors](/en/api-reference/guides/knowledge-base#handle-errors) section.
+</Info>
+
 ## Status Classes at a Glance
 
 | Status | Meaning | Typical codes |
 |:-------|:--------|:--------------|
 | 400 | The request or the app's configuration is invalid | `invalid_param`, `bad_request`, `app_unavailable`, provider errors (below) |
-| 401 | Missing or invalid API key | `unauthorized` |
-| 403 | The key can't act here: access restrictions or plan limits | `forbidden` |
+| 401 | Authentication failed or access was denied | `unauthorized` |
+| 403 | This action is not permitted, or a plan limit applies | `forbidden` |
 | 404 | The resource doesn't exist or isn't visible to this key or `user` | `not_found` |
 | 413 / 415 | A file is too large or of an unsupported type | `file_too_large`, `unsupported_file_type` |
 | 429 | Too many requests right now, or a quota is exhausted | `too_many_requests`, `rate_limit_error` |
 | 500 | Something failed on Dify's side | `internal_server_error` |
 
+<Note>
+On Dify Cloud, a `401` response from an app API can also mean the request was blocked by [IP access control](/en/cloud/use-dify/publish/ip-access-control). If your API key is valid, ask the app administrator to check whether the request’s source IP is allowed.
+</Note>
+
 ## Provider Errors Are Configuration Errors
 
 Four common 400 codes point at the app's model setup rather than your request:
@@ -46,11 +54,11 @@ The two 429 codes mean different things:
 - `too_many_requests` is a concurrency ceiling—too many simultaneous requests for the app right now. Back off and retry.
 - `rate_limit_error` is a plan quota on Dify Cloud, such as workflow executions. Retrying won't clear it; it resets with the quota period or a plan change.
 
-On Dify Cloud, knowledge write endpoints also enforce plan limits as `403` responses. These carry the same `forbidden` code as access restrictions—the `message` is what tells you it's a plan limit, so don't build a switch on `code` alone for 403s.
+On Dify Cloud, knowledge base endpoints also enforce plan limits as `403` responses, such as the [request rate limit](/en/cloud/use-dify/knowledge/knowledge-request-rate-limit). These carry the `forbidden` code. Classic knowledge base endpoints use the same code for access restrictions, so read the `message` to tell them apart rather than switching on `code` alone.
 
 ## Errors Inside Streams
 
-Once a stream opens, the HTTP status is already `200`: failures arrive as an `error` event and end the stream. The event's `code` values are the same ones documented here—classify them with the same rules. See [Consume Streaming Responses](/en/api-reference/guides/streaming) for details.
+Once an app stream opens, the HTTP status is already `200`: failures arrive as an `error` event and end the stream. The event's `code` values are the same ones documented here—classify them with the same rules. See [Consume Streaming Responses](/en/api-reference/guides/streaming) for details.
 
 ## What to Retry
 

en/api-reference/guides/get-started.mdx

@@ -18,13 +18,11 @@ Call the API from your backend only. A key embedded in frontend code or a client
     Your calls tell people apart with a per-person `user` value. See [End User Identity](/en/api-reference/guides/end-user-identity) for details.
     </Info>
 
-- For knowledge bases, go to **Knowledge**, click **Service API** in the top-right corner and create an API key there.
-
-    You can [scope the key](/en/api-reference/guides/knowledge#scoped-api-keys) to only the knowledge bases the integration needs access to.
+- For knowledge bases, see the [Knowledge Base API](/en/api-reference/guides/knowledge-base-api) guide.
 
 ## Make Your First Call
 
-Every request carries the key as a Bearer token. For Dify Cloud, the base URL is `https://api.dify.ai/v1`; for self-hosted deployments, use your own instance's API base URL.
+Most requests carry the key as a Bearer token. For Dify Cloud, the base URL is `https://api.dify.ai/v1`; for self-hosted deployments, use your own instance's API base URL.
 
 The fastest first call needs no code: open [Get App Info](/en/api-reference/applications/get-app-info), click **Try it**, paste your key into the **Authorization** field, and press **Send**. It works for every app type.
 
@@ -47,10 +45,7 @@ A response like this confirms the key works and shows which app it belongs to:
 }
 ```
 
-Using a knowledge API key?
-
-- **Scoped key**: [Copy the ID from Dify](/en/api-reference/guides/knowledge#knowledge-base-id) for a knowledge base in its scope, then call [Get Knowledge Base](/en/api-reference/knowledge-bases/get-knowledge-base).
-- **Key with access to all knowledge bases**: Call [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
+Using a knowledge base API key? See the [Knowledge Base API](/en/api-reference/guides/knowledge-base-api) guide.
 
 ## Find Your App Type's Endpoints
 
@@ -61,4 +56,4 @@ See each app type's own overview page for its full API surface:
 - [Agent](/en/api-reference/guides/agent) (`agent`)
 - [Chatbot and Legacy Agent](/en/api-reference/guides/chat) (`chat`, `agent-chat`)
 - [Text Generator](/en/api-reference/guides/completion) (`completion`)
-- [Knowledge](/en/api-reference/guides/knowledge)
+- [Knowledge Base](/en/api-reference/guides/knowledge-base-api)

en/api-reference/guides/knowledge-base-api.mdx

@@ -0,0 +1,50 @@
+---
+title: Knowledge Base API
+sidebarTitle: Knowledge Base
+description: Create and scope the API keys that both knowledge base APIs take, replace them safely, and find out why a call was refused
+---
+
+Each kind of knowledge base has its own API, and both take the same API keys:
+
+- [Agent Knowledge Base API](/en/api-reference/guides/knowledge-base) <Badge color="blue" size="sm">Cloud</Badge>
+- [Classic Knowledge Base API](/en/api-reference/guides/knowledge)
+
+## Create an API Key {#create-an-api-key}
+
+<Info>
+Only the workspace owner and admins can create, view, and delete keys.
+</Info>
+
+In **Knowledge**, click **Service API** in the top-right corner, then **API Key**. Each workspace can have up to 10 keys.
+
+The same panel shows the Service API endpoint, the base URL for both APIs.
+
+## Choose a Scope {#choose-a-scope}
+
+When you create a key, give it access to all knowledge bases, or only to the ones you pick, of either kind. Pick only the knowledge bases the integration works with. 
+
+If it also calls operations that name no knowledge base, such as listing or creating classic knowledge bases, managing tags, or [getting the available models](/en/api-reference/models/get-available-models), give it access to all knowledge bases instead.
+
+The scope can't be changed later. To change it, [replace the key](#replace-a-key).
+
+## Replace a Key {#replace-a-key}
+
+To change a key's scope, or to rotate it, create the new key, switch your integration to it, then delete the old one. A deleted key stops working right away.
+
+On agent knowledge bases, research tasks and deletion jobs can be read only with the key that started them. Before you delete the old key, let them finish and read their results.
+
+## When a Key Is Refused {#when-a-key-is-refused}
+
+| Cause | Classic knowledge base | Agent knowledge base |
+|:--|:--|:--|
+| The knowledge base is outside the key's scope | 403 `forbidden` | 403 `knowledge_fs_access_denied` |
+| A scoped key calls an operation that names no knowledge base | 403 `forbidden` | 403 `forbidden` |
+| **API access** was turned off for the knowledge base | 403 `forbidden` | 403 `knowledge_fs_access_denied` |
+| The key was deleted, directly or along with the only knowledge base it covered | 401 `unauthorized` | 401 `unauthorized` |
+| On Dify Cloud, the workspace reached its [request rate limit](/en/cloud/use-dify/knowledge/knowledge-request-rate-limit) | 403 `forbidden` | 403 `forbidden` |
+
+On a classic knowledge base, a 403 `forbidden` can have several of these causes, so read the error's `message` to tell them apart.
+
+A key scoped to a classic knowledge base doesn't cover the agent knowledge base upgraded from it. To reach the agent one, [replace the key](#replace-a-key) with one that includes it.
+
+An agent knowledge base ID that doesn't exist in the key's workspace returns 401 `knowledge_fs_invalid_credential`, as a bad key would. Check the ID before you replace the key.