> ## Documentation Index > Fetch the complete documentation index at: https://dify-6c0370d8-fix-template-upload-size-guidance.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List Documents > Returns a paginated list of documents in a knowledge base. ## OpenAPI ````yaml /en/api-reference/openapi_service.json get /datasets/{dataset_id}/documents 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 paths: /datasets/{dataset_id}/documents: get: tags: - Documents summary: List Documents description: Returns a paginated list of documents in a knowledge base. operationId: listDocuments parameters: - description: >- Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). in: path name: dataset_id required: true schema: format: uuid type: string - description: Page number. in: query name: page schema: default: 1 type: integer - description: Number of items per page. Server caps at `100`. in: query name: limit schema: default: 20 type: integer - description: Search keyword to filter by document name. in: query name: keyword schema: type: string - description: Filter by display status. in: query name: status schema: enum: - queuing - indexing - paused - error - available - disabled - archived type: string responses: '200': content: application/json: examples: success: summary: Response Example value: data: - archived: false created_at: 1741267200 created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4 created_from: api data_source_detail_dict: upload_file: created_at: 1741267200 created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4 extension: txt id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 mime_type: text/plain name: guide.txt size: 2048 data_source_info: upload_file_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 data_source_type: upload_file dataset_process_rule_id: e1f2a3b4-c5d6-7890-ef12-345678901234 disabled_at: null disabled_by: null display_status: available doc_form: text_model doc_metadata: [] enabled: true error: null hit_count: 0 id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac indexing_status: completed name: guide.txt need_summary: false position: 1 summary_index_status: null tokens: 512 word_count: 350 has_more: false limit: 20 page: 1 total: 1 schema: properties: data: description: Array of document objects. items: $ref: '#/components/schemas/Document' type: array has_more: description: Whether more items exist on the next page. type: boolean limit: description: Number of items per page. type: integer page: description: Current page number. type: integer total: description: Total number of matching items. type: integer type: object description: List of documents. '403': content: application/json: examples: forbidden: summary: forbidden (api access) value: code: forbidden message: Dataset api access is not enabled. status: 403 description: '`forbidden` : Knowledge base API access is not enabled.' '404': content: application/json: examples: not_found: summary: not_found value: code: not_found message: Dataset not found. status: 404 description: '`not_found` : Knowledge base not found.' components: schemas: Document: properties: archived: description: Whether the document is archived. type: boolean created_at: description: Creation timestamp (Unix epoch in seconds). type: number created_by: description: ID of the user who created the document. type: string created_from: description: >- Origin of the document. `api` for API creation, `web` for UI creation. type: string data_source_detail_dict: description: Detailed data source information including file details. type: object data_source_info: description: Raw data source information, varies by `data_source_type`. type: object data_source_type: description: >- How the document was created. `upload_file` for file uploads, `notion_import` for Notion imports. type: string dataset_process_rule_id: description: ID of the processing rule applied to this document. type: string disabled_at: description: Timestamp when the document was disabled. `null` if enabled. nullable: true type: number disabled_by: description: ID of the user who disabled the document. `null` if enabled. nullable: true type: string display_status: description: >- User-facing display status derived from `indexing_status` and `enabled` state. type: string doc_form: description: >- Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction. type: string doc_metadata: description: Metadata values assigned to this document. items: properties: id: description: Metadata field identifier. type: string name: description: Metadata field name. type: string type: description: Metadata field value type. type: string value: description: Metadata value for this document. type: string type: object type: array enabled: description: Whether the document is enabled for retrieval. type: boolean error: description: Error message if indexing failed. `null` when no error. nullable: true type: string hit_count: description: Number of times the document has been matched in retrieval queries. type: integer id: description: Unique identifier of the document. type: string indexing_status: description: >- Current indexing status. `waiting` for queued, `parsing` while extracting content, `cleaning` while removing noise, `splitting` while chunking, `indexing` while building vectors, `completed` when ready, `error` if failed, `paused` if manually paused. type: string name: description: Document name. type: string need_summary: description: Whether a summary needs to be generated for this document. type: boolean position: description: Display position of the document in the list. type: integer summary_index_status: description: >- Status of the summary index for this document. `null` if summary indexing is not configured. nullable: true type: string tokens: description: Total number of tokens in the document. type: integer word_count: description: Total word count of the document. 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 ````