> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # Re-index Documents > Queues an indexing task to rebuild each selected document's index from its current file. Returns a bulk task ID to follow the tasks together. Exactly one of `all: true` or `documentIds` must be given. No file is re-uploaded. Follow each task with [Get Indexing Task](/en/api-reference/indexing-tasks/get-indexing-task) using `compilation_job.id`, and the whole request with [Get Bulk Task](/en/api-reference/indexing-tasks/get-bulk-task). For the re-index flow, see [Re-index and Track Indexing](/en/api-reference/guides/knowledge-base#track-indexing). ## OpenAPI ````yaml /en/api-reference/openapi_service.json post /knowledge-fs/spaces/{knowledge_base_id}/documents/reindex openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline - description: Ask a knowledge base a question and stream the answer. name: Queries - description: Inspect what a query retrieved and why. name: Query Records - description: Run a research question in the background and collect its results. name: Research Tasks - description: >- Read the documents in a knowledge base, their files, revisions, and chunks; label documents with metadata. name: Documents and Chunks - description: >- Follow, cancel, or retry indexing, and list the knowledge base's background tasks. name: Indexing Tasks - description: >- Follow the deletion of a document file, a batch of files, or a source until it finishes. name: Deletion Jobs - description: >- Manage the sources that feed a knowledge base, their sync schedules, and their connections. name: Sources - description: >- Sync a source now, import website pages or provider items, and follow, cancel, or retry the runs. name: Source Syncs and Imports - description: >- Read and change the knowledge base's models and retrieval settings, and follow the migration a change starts. name: Settings paths: /knowledge-fs/spaces/{knowledge_base_id}/documents/reindex: post: tags: - Documents and Chunks summary: Re-index Documents description: >- Queues an indexing task to rebuild each selected document's index from its current file. Returns a bulk task ID to follow the tasks together. Exactly one of `all: true` or `documentIds` must be given. No file is re-uploaded. Follow each task with [Get Indexing Task](/en/api-reference/indexing-tasks/get-indexing-task) using `compilation_job.id`, and the whole request with [Get Bulk Task](/en/api-reference/indexing-tasks/get-bulk-task). For the re-index flow, see [Re-index and Track Indexing](/en/api-reference/guides/knowledge-base#track-indexing). operationId: reindexDocuments parameters: - description: >- Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's **API Access** dialog (`…/knowledge-fs/spaces/`), and the segment after `/datasets/new/` in the address bar. in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- Send a key on every call. It makes the call safe to retry. Use 8 to 255 printable ASCII characters without leading or trailing whitespace; a malformed key answers `400`. Repeating the same key and body returns the original bulk task instead of starting new indexing tasks. Reusing the key with a different body, from another API key, in another knowledge base, or for another operation answers `409`. in: header name: Idempotency-Key required: false schema: maxLength: 255 minLength: 8 type: string requestBody: content: application/json: examples: all: summary: Request Example - Every document file value: all: true by_id: summary: Request Example - Selected documents value: documentIds: - 3d2f1c0b-9a8e-4d7c-b6a5-4f3e2d1c0b9a - 8f14e45f-ceea-467a-9575-62c9a2d3e6b1 schema: additionalProperties: false description: >- Send `all: true` or a nonempty `documentIds` array, but not both. With `documentIds`, `all` may be omitted, `false`, or `null`. With `all: true`, `documentIds` may be omitted or `null`; an empty array is rejected. oneOf: - properties: all: enum: - true nullable: false type: boolean documentIds: enum: - null nullable: true type: array required: - all title: All Documents - properties: all: enum: - false - null nullable: true type: boolean documentIds: minItems: 1 nullable: false type: array required: - documentIds title: Selected Documents properties: all: description: >- Set to `true` to re-index every document file the key can read. When there are more than the cap (100 by default), the call answers `400` and nothing is re-indexed. nullable: true type: boolean documentIds: description: >- Documents to re-index, by document ID (from [List Documents](/en/api-reference/documents-and-chunks/list-documents)) or by document file ID (from [List Document Files](/en/api-reference/documents-and-chunks/list-document-files)). The deployment may set a lower cap. Duplicate IDs are collapsed, so `total` can be smaller than the number sent. Send each ID once, and `items` lines up with your request in order. items: format: uuid type: string maxItems: 100 minItems: 1 nullable: true type: array type: object description: >- Optional fields marked nullable treat `null` as omitted. The normalized request must fit within 1,048,576 UTF-8 bytes. See [Request Size Limits](/en/api-reference/guides/knowledge-base#request-size-limits). required: true responses: '202': content: application/json: examples: success: summary: Response Example value: bulk_job_id: 5a1c2e3d-7b8f-4a9c-8d1e-2f3a4b5c6d7e items: - asset: created_at: '2026-09-03T10:02:11Z' filename: handbook.pdf id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b metadata: {} mime_type: application/pdf object_key: >- 1a7c9e40-2b3d-4f56-8a90-b1c2d3e4f506/spaces/9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b/documents/6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b/handbook.pdf parser_status: parsed sha256: >- 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 size_bytes: 482113 source_id: null updated_at: null version: 1 code: null compilation_job: id: e4a1f0b2-7c3d-4e5f-9a1b-2c3d4e5f6a7b stage: queued document_id: null error: null status: queued status_url: >- /knowledge-spaces/9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b/documents/3d2f1c0b-9a8e-4d7c-b6a5-4f3e2d1c0b9a/processing-tasks/e4a1f0b2-7c3d-4e5f-9a1b-2c3d4e5f6a7b - asset: null code: null compilation_job: null document_id: 8f14e45f-ceea-467a-9575-62c9a2d3e6b1 error: null status: not_found status_url: null total: 2 schema: properties: bulk_job_id: description: >- Bulk task ID. Poll it with [Get Bulk Task](/en/api-reference/indexing-tasks/get-bulk-task). type: string items: description: >- One entry per distinct ID sent, in request order, followed by one entry per selected file when `all` is `true`. IDs that resolve to the same document file share one entry. items: properties: asset: allOf: - $ref: '#/components/schemas/KnowledgeBaseDocumentFile' description: >- The document file being re-indexed. `null` unless `status` is `queued`. nullable: true code: description: >- Failure code when `status` is `failed`. `null` otherwise. nullable: true type: string compilation_job: description: >- The indexing task. `null` unless `status` is `queued`. nullable: true properties: id: description: >- Indexing task ID. Poll it with [Get Indexing Task](/en/api-reference/indexing-tasks/get-indexing-task). type: string stage: description: Always `queued` at this point. type: string type: object document_id: description: >- The ID as sent, or the document file ID for items selected by `all: true`. Set when `status` is `disabled`, `not_found`, `failed`, or `pending`. `null` for `queued` items, whose document file ID is `asset.id`. nullable: true type: string error: description: >- Failure message when `status` is `failed`. `null` otherwise. nullable: true type: string status: description: >- - `queued`: an indexing task was started, and `asset`, `compilation_job`, and `status_url` are set. - `disabled`: the document is disabled, so nothing was queued, and the bulk task counts it as canceled. No operation in this API enables a document. - `not_found`: no readable document file matched the ID. - `failed`: no indexing task was started. `code` and `error` say why. - `pending`: it could not be confirmed whether an indexing task was started. type: string status_url: description: >- Internal path of the task. Informational. Follow the task with [Get Bulk Task](/en/api-reference/indexing-tasks/get-bulk-task) instead. `null` unless `status` is `queued`. nullable: true type: string type: object type: array total: description: Number of entries in `items`. type: integer type: object description: The indexing tasks were queued. '400': content: application/json: examples: knowledge_fs_invalid_request_local: summary: knowledge_fs_invalid_request (request validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - documentIds type: too_long knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (rejected) value: code: knowledge_fs_invalid_request failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`: the request failed validation. `violations` names each failing field. Giving neither or both of `all: true` and `documentIds` answers `400`. - `knowledge_fs_invalid_request`: `documentIds` has more entries than the deployment's cap, `all: true` selects more files than the cap, or an ID is not a UUID. - `knowledge_fs_invalid_request`: `Idempotency-Key` is not 8 to 255 printable ASCII characters, or has leading or trailing whitespace. '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`: the `Authorization` header is missing, or the key is unknown or not a knowledge base API key. - `knowledge_fs_invalid_credential`: the key is valid, but no knowledge base with this ID exists in the key's workspace, or the key is not tied to a workspace. '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied_scope: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_upstream: summary: knowledge_fs_access_denied (rejected) value: code: knowledge_fs_access_denied failure: action: contact_admin category: authorization code: KNOWLEDGE_FS_ACCESS_DENIED message: >- You do not have permission to perform this Agent Knowledge Base operation. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- You do not have permission to perform this Agent Knowledge Base operation. status: 403 description: >- - `knowledge_fs_access_denied`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `knowledge_fs_access_denied`: the key has no access to this knowledge base's content. - `forbidden`: on Dify Cloud, the workspace has reached the knowledge base request rate limit of its subscription. Every call counts, reads included. '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: >- - `knowledge_fs_resource_not_found`: the knowledge base ID isn't recognized. - `knowledge_fs_resource_not_found`: a selected document file is no longer readable with this key, for example on a repeat with the same `Idempotency-Key` after the key's access changed. - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '409': content: application/json: examples: knowledge_fs_conflict: summary: knowledge_fs_conflict value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_FS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. retryPolicy: manual traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`: the knowledge base is still migrating from the classic knowledge base format. Retry later. - `knowledge_fs_conflict`: a document has no active revision, and the indexing task of its latest revision cannot be retried. - `knowledge_fs_conflict`: `Idempotency-Key` was already used with a different body, from another API key, in another knowledge base, or for another operation. '413': content: application/json: examples: knowledge_fs_request_too_large: summary: knowledge_fs_request_too_large value: code: knowledge_fs_request_too_large failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The Agent Knowledge Base request is invalid. status: 413 knowledge_fs_request_too_large_budget: summary: knowledge_fs_request_too_large (request budget) value: code: knowledge_fs_request_too_large message: Agent Knowledge Base request is too large. status: 413 description: >- - `knowledge_fs_request_too_large`: The knowledge base exceeds a configured resource quota, or the service cannot complete the quota check. The body's `failure.code` is `KNOWLEDGE_FS_INVALID_REQUEST`. - `knowledge_fs_request_too_large`: the request, once Dify adds its defaults, exceeds 1,048,576 UTF-8 bytes. See [Request Size Limits](/en/api-reference/guides/knowledge-base#request-size-limits). '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 knowledge_fs_upstream_unavailable_transport: summary: knowledge_fs_upstream_unavailable (no response) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`: no answer came back in time, or the answer couldn't be read. Indexing may have started before the response was lost. If you received task IDs, poll them. If you sent `Idempotency-Key`, send the same request again with the same key: it returns the original bulk task. '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`: the Agent Knowledge Base feature is not set up for this workspace, this operation is not available on the deployment, or the key's access to this knowledge base changed while the request was being authorized. - `knowledge_fs_operation_unavailable`: the request can't be served right now. Follow `failure.retryPolicy`. - `knowledge_fs_operation_unavailable`: with `all: true`, the request gave up before it could list the files the key can read, which happens when most files are hidden from this key. components: schemas: KnowledgeBaseDocumentFile: properties: created_at: description: When the file was stored, ISO 8601. type: string filename: description: Original file name. type: string id: description: >- Document file ID. Different from the document ID in the address bar of the open document in Dify. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string metadata: additionalProperties: true description: Metadata recorded with the file when it was uploaded or imported. type: object mime_type: description: MIME type of the file. type: string object_key: description: >- Key of the file in object storage. No operation in this API returns the file's content. type: string parser_status: description: >- Parse state of this version of the file: `pending`, `parsed`, or `failed`. Parsing is one step of indexing. A `parsed` file can still have no outline and no chunks. type: string sha256: description: SHA-256 hash of the file content, hex-encoded. type: string size_bytes: description: File size in bytes. type: integer source_id: description: >- ID of the source the file was imported from. `null` for uploaded files. nullable: true type: string updated_at: description: >- When the file record last changed, ISO 8601. `null` when it has not changed since creation. nullable: true type: string version: description: >- Always `1` for this file ID. A content update, including a source sync, creates a different file ID rather than incrementing this value. This is separate from the document's content revision. Send it as `expectedRevision` to [Delete Document File](/en/api-reference/documents-and-chunks/delete-document-file). type: integer type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.