Re-index Documents

post/knowledge-fs/spaces/{knowledge_base_id}/documents/reindex

Request example

curl --request POST \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/reindex \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <string>' \
  --header 'Content-Type: application/json' \
  --data '{
  "all": true
}'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/reindex"
headers = {
    "Authorization": "Bearer <token>",
    "Idempotency-Key": "<string>",
    "Content-Type": "application/json",
}
payload = {
    "all": True
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/reindex', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Idempotency-Key': '<string>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "all": true
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/reindex',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "all": true
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Idempotency-Key: <string>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/reindex"
	payload := strings.NewReader("{\n  \"all\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Idempotency-Key", "<string>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/reindex"))
    .header("Authorization", "Bearer <token>")
    .header("Idempotency-Key", "<string>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"all\": true\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/reindex')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Idempotency-Key'] = '<string>'
request['Content-Type'] = 'application/json'
request.body = '{
  "all": true
}'

response = http.request(request)
puts response.read_body

Response

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

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400,
  "violations": [
    {
      "field": [
        "documentIds"
      ],
      "type": "too_long"
    }
  ]
}

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

{
  "code": "knowledge_fs_invalid_credential",
  "message": "Invalid Agent Knowledge Base service credential.",
  "status": 401
}

{
  "code": "unauthorized",
  "message": "Access token is invalid",
  "status": 401
}

{
  "code": "forbidden",
  "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
  "status": 403
}

{
  "code": "knowledge_fs_access_denied",
  "message": "Agent Knowledge Base operation is not allowed.",
  "status": 403
}

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

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

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

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

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

{
  "code": "knowledge_fs_request_too_large",
  "message": "Agent Knowledge Base request is too large.",
  "status": 413
}

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

{
  "code": "knowledge_fs_upstream_unavailable",
  "message": "Agent Knowledge Base is unavailable.",
  "status": 502
}

{
  "code": "knowledge_fs_operation_unavailable",
  "message": "Agent Knowledge Base operation is not available.",
  "status": 503
}

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

post/knowledge-fs/spaces/{knowledge_base_id}/documents/reindex

Authorization

Authorizationstringheaderrequired#

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

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Path parameters

knowledge_base_idstringrequired#

Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.

Headers

Idempotency-Keystring#

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.

Length: 8–255

Body

application/json

One of

allenum<boolean>required#

Options:true

documentIdsenum<array>#

Options:null

allenum<boolean>#

Options:falsenull

documentIdsany[]required#

Items: min 1

Responses

application/json

The indexing tasks were queued.

bulk_job_idstring#

Bulk task ID. Poll it with Get Bulk Task.

itemsobject[]#

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.

Show child attributes

assetobject#

The document file being re-indexed. null unless status is queued.

Show child attributes

created_atstring#

When the file was stored, ISO 8601.

filenamestring#

Original file name.

idstring#

Document file ID. Different from the document ID in the address bar of the open document in Dify.

knowledge_space_idstring#

Internal ID of the knowledge base. Not the knowledge base ID in the path.

metadataobject#

Metadata recorded with the file when it was uploaded or imported.

mime_typestring#

MIME type of the file.

object_keystring#

Key of the file in object storage. No operation in this API returns the file's content.

parser_statusstring#

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.

sha256string#

SHA-256 hash of the file content, hex-encoded.

size_bytesinteger#

File size in bytes.

source_idstring#

ID of the source the file was imported from. null for uploaded files.

updated_atstring#

When the file record last changed, ISO 8601. null when it has not changed since creation.

versioninteger#

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.

codestring#

Failure code when status is failed. null otherwise.

compilation_jobobject#

The indexing task. null unless status is queued.

Show child attributes

idstring#

Indexing task ID. Poll it with Get Indexing Task.

stagestring#

Always queued at this point.

document_idstring#

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.

errorstring#

Failure message when status is failed. null otherwise.

statusstring#

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.

status_urlstring#

Internal path of the task. Informational. Follow the task with Get Bulk Task instead. null unless status is queued.

totalinteger#

Number of entries in items.

Delete Document Files in Batch Get Indexing Task