List Document Revisions

Lists a document’s revisions, newest first. Takes the document ID from List Documents, not the document file ID.

Each revision names the document file behind it. For how document IDs and document file IDs relate, see Browse Documents and Chunks.

Revisions whose document file the key cannot read are left out before the page is filled. Follow next_cursor even when a page contains fewer than limit revisions.

1 min read

get/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_id}/revisions

Request example

curl --request GET \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_id}/revisions \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_id}/revisions"
headers = {
    "Authorization": "Bearer <token>",
}

response = requests.request("GET", url, headers=headers)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_id}/revisions', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>'
  }
});

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/{document_id}/revisions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
  ],
]);

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

echo $response;

package main

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

func main() {
	url := "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_id}/revisions"

	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Add("Authorization", "Bearer <token>")

	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/{document_id}/revisions"))
    .header("Authorization", "Bearer <token>")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/{document_id}/revisions')

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

request = Net::HTTP::Get.new(url)
request['Authorization'] = 'Bearer <token>'

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

Response

{
  "data": [
    {
      "activated_at": "2026-09-03T10:05:00Z",
      "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "created_at": "2026-09-03T10:02:11Z",
      "document_asset_id": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
      "document_asset_version": 1,
      "document_id": "3d2f1c0b-9a8e-4d7c-b6a5-4f3e2d1c0b9a",
      "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
      "mime_type": "application/pdf",
      "revision": 2,
      "size_bytes": 482113,
      "state": "active"
    },
    {
      "activated_at": "2026-09-01T08:15:00Z",
      "content_hash": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
      "created_at": "2026-09-01T08:12:45Z",
      "document_asset_id": "4b81d2c6-0e5f-4a73-9c8b-5d6e7f8a9b0c",
      "document_asset_version": 1,
      "document_id": "3d2f1c0b-9a8e-4d7c-b6a5-4f3e2d1c0b9a",
      "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
      "mime_type": "application/pdf",
      "revision": 1,
      "size_bytes": 471002,
      "state": "superseded"
    }
  ],
  "next_cursor": null
}

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

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400
}

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

get/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_id}/revisions

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.

document_idstringrequired#

The document ID, from List Documents or from the address bar of the open document (/datasets/new/<knowledge base ID>/documents/<document ID>).

Query parameters

cursorstring#

Cursor from the previous page's next_cursor.

Length: 1–1000

limitinteger#

Revisions per page.

Default: 50

Range: 1–100

Responses

application/json

One page of revisions.

dataobject[]#

One page of revisions, newest first. The newest revision is not always the active one.

Show child attributes

activated_atstring#

When the revision became active, ISO 8601. null for a revision that never became active.

content_hashstring#

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

created_atstring#

When the revision was created, ISO 8601.

document_asset_idstring#

ID of the document file behind this revision. Use it with Get Document File.

document_asset_versioninteger#

The document file's version when this revision was created.

document_idstring#

Document ID: the id of Get Document.

knowledge_space_idstring#

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

mime_typestring#

MIME type of the document file.

revisioninteger#

Revision number, starting at 1. The revision path value for List Chunks.

size_bytesinteger#

Size of the document file in bytes.

statestring#

candidate while the revision is being indexed, active for the revision the knowledge base serves, superseded after a newer revision became active, failed when indexing failed.

next_cursorstring#

Cursor for the next page, or null on the last page. Send it back as cursor.

Get Document Outline List Chunks