---
title: "List Documents"
method: GET
path: "/api/v3/documents/list"
tags: ["Documents"]
---

# List Documents

`GET /api/v3/documents/list`

## Request

- Base URL: `https://api.nugen.in`
- URL: `https://api.nugen.in/api/v3/documents/list`
- Auth: HTTP bearer

Retrieve all documents and categories for the authenticated user.

This endpoint returns a paginated, lean list row per document. Fetch `GET /documents/{id}` for the full record: filename, type, size, uploader, processing progress.


**Query Parameters:**

- `status` (optional): Filter by document status
- `limit` (optional): Number of documents to return (1-100, default: 10)
- `offset` (optional): Number of documents to skip for pagination (default: 0)


**Returns:**

- `List of document objects, each containing`:
  - `document_id`: Unique document identifier
  - `document_name`: Display name of the document
  - `status`: Processing status (`QUEUED`, `PROCESSING`, `READY`, `FAILED`)
  - `created_at`: ISO 8601 timestamp when the document was created
  - `categories`: List of category names assigned to this document

- `categories`: List of category objects, each containing:
  - `name`: Category name
  - `count`: Number of documents in this category


**Example Request:**

```json
GET /api/v3/documents/list
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{
  "documents": [
    {
      "document_id": "document_01k4x9m2p7q3r5s8",
      "document_name": "Quarterly Report",
      "status": "READY",
      "created_at": "2024-01-15T10:30:00Z",
      "categories": ["financial", "2024"]
    },
    {
      "document_id": "document_01k4x9m2p7q3r5sa",
      "document_name": "Meeting Notes",
      "status": "PROCESSING",
      "created_at": "2024-01-16T14:20:00Z",
      "categories": ["meetings"]
    }
  ],
  "categories": [
    {
      "name": "financial",
      "count": 5
    },
    {
      "name": "2024",
      "count": 12
    },
    {
      "name": "meetings",
      "count": 8
    }
  ]
}
```


**Notes:**

- Categories are automatically extracted and organized for easy filtering
- Each category shows the total count of documents tagged with that category

## Query parameters

- `status` string, nullable: Filter by document status
- `limit` integer: Number of documents to return
- `offset` integer: Number of documents to skip

## Response `200`

Returns a lean list of all documents uploaded by the authenticated user, and available document categories with counts

- DocumentListResponse: The caller's documents.
  - `documents` DocumentListItem[], required: List of all documents uploaded by the user
    - `document_id` string, required: Unique identifier for the document
    - `document_name` string, nullable: Display name of the document. Defaults to the document id if not set at upload.
    - `status` 'QUEUED' | 'PROCESSING' | 'READY' | 'FAILED' | 'STOPPED', required: Lifecycle status of a resource that runs asynchronously. Stored as is and returned as is, with no translation in between. - `QUEUED`: accepted and waiting for its workflow to start - `PROCESSING`: running - `READY`: finished successfully - `FAILED`: failed at any stage - `STOPPED`: stopped by the user before completion
    - `created_at` string, date-time, required: Timestamp when the document was created
    - `categories` string[], required: List of category tags assigned to the document for organization and retrieval
  - `categories` DocumentCategory[], required: List of all document categories with document counts for filtering and organization
    - `name` string, required: Name of the category
    - `count` integer, required: Number of documents tagged with this category
  - `storage` DocumentStorageStats, required: Storage used by the caller's documents.
    - `total_size` number, required: Total size of all documents in MB
    - `total_words` integer, required: Total word count across all documents

## Other responses

- `401`: Invalid API key
- `403`: Authorization header missing or not a Bearer token
- `422`: Validation Error

---

[API](https://skmtc.dev/nugen/apis/nugen-intelligence-api.md) - [All operations](https://skmtc.dev/nugen/apis/nugen-intelligence-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nugen/apis/nugen-intelligence-api/revisions/62baa7960a4a?raw)