> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Files

> List file objects stored in document storage (S3) for a namespace you own. API key authentication.

## Overview

Returns every **file object** under your namespace prefix in document storage (S3): file name, size, and last modified time. The namespace must exist and belong to the authenticated user.

<Info>
  This lists **raw files** in storage (for example after [Get Upload URL](/api-reference/files/upload-file-url) uploads). It is different from [Get Documents](/api-reference/data/get-documents), which returns **indexed text documents** by ID from the text pipeline.
</Info>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

## Path Parameters

<ParamField path="namespace_name" type="string" required>
  Namespace name in the URL path. Must be a namespace you own.
</ParamField>

## Request

No query parameters or body. Use **GET** only.

<RequestExample>
  ```bash List all files in a namespace theme={null}
  curl -X GET "https://api.moorcheh.ai/v1/namespaces/my-namespace/list-files" \
    -H "x-api-key: your-api-key-here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={null}
  {
    "success": true,
    "namespace": "my-namespace",
    "file_count": 2,
    "files": [
      {
        "file_name": "report.pdf",
        "size": 245678,
        "last_modified": "2026-05-10T14:22:11.000Z"
      },
      {
        "file_name": "notes.txt",
        "size": 1204,
        "last_modified": "2026-05-09T09:01:00.000Z"
      }
    ]
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "error": "namespace_name is required in the URL path"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": "Unauthorized: API key is required"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "error": "Namespace 'unknown' not found"
  }
  ```

  ```json 429 - Too Many Requests theme={null}
  {
    "error": "API request limit reached for your plan (100000 requests). Current usage: 100000."
  }
  ```
</ResponseExample>

#### Success Response (200 OK)

<ResponseField name="success" type="boolean">
  Always `true` when the listing succeeds
</ResponseField>

<ResponseField name="namespace" type="string">
  The namespace that was listed (same as path parameter)
</ResponseField>

<ResponseField name="file_count" type="integer">
  Number of file objects returned
</ResponseField>

<ResponseField name="files" type="array">
  Array of objects, each with `file_name` (string, path under the namespace prefix), `size` (bytes), and `last_modified` (ISO 8601 timestamp from storage)
</ResponseField>

## Notes

* **Method:** `GET` only
* **Size:** Each item’s `size` field is the stored object’s length in **bytes** (same notion as S3 object size / `Content-Length` in bytes), not KB or MB.
* **Usage:** Each successful call increments API request usage (and related credit accounting) like other public API key endpoints.
* **Empty namespace:** `files` may be an empty array and `file_count` will be `0`.
* **Ordering:** Order follows underlying object listing; do not rely on a specific sort unless you sort client-side.

## Related Endpoints

* [Get Upload URL](/api-reference/files/upload-file-url) — Upload files to a namespace
* [Delete File](/api-reference/files/delete-file) — Remove files from a namespace
* [Get Documents](/api-reference/data/get-documents) — Fetch indexed text documents by ID