Skip to main content
GET
/
namespaces
/
{namespace_name}
/
files
List Files
curl --request GET \
  --url http://localhost:8080/namespaces/{namespace_name}/files
{
  "status": "success",
  "count": 1,
  "files": [
    {
      "file_id": "a1b2c3d4e5f67890",
      "absolute_path": "/uploads/document.pdf",
      "filename": "document.pdf",
      "file_type": ".pdf",
      "file_size": 125440,
      "file_mtime": "2026-06-05T18:50:08Z",
      "chunk_count": 3,
      "summary_count": 1,
      "status": "indexed",
      "path_exists": true,
      "ingested_at": "2026-06-05T18:50:20Z",
      "last_error": null,
      "metadata": { "department": "engineering" }
    }
  ]
}

​
Overview

Returns all file records from the namespace file registry: paths, chunk counts, upload status, and custom metadata.

​
Path parameters

​
namespace_name
string
required
Text namespace to list.

​
Request example

curl "http://localhost:8080/namespaces/my-documents/files"

​
Response fields

​
status
string
"success" on success.
​
count
number
Number of file records.
​
files
array
File records sorted by filename.
​
files[].file_id
string
Server-generated file id (use for delete by id).
​
files[].absolute_path
string
Container path used at upload (e.g. /uploads/document.pdf).
​
files[].filename
string
Basename of the file.
​
files[].file_type
string
File extension including the dot (e.g. .pdf).
​
files[].file_size
number
File size in bytes at upload time.
​
files[].file_mtime
string
File last-modified time (ISO 8601) used for deduplication.
​
files[].chunk_count
number
Content chunks indexed for this file.
​
files[].summary_count
number
Batch summary chunks created (one per 100 content chunks).
​
files[].status
string
indexed, processing, failed, or file_missing (path no longer readable).
​
files[].path_exists
boolean
Whether the source file still exists at absolute_path inside the container.
​
files[].ingested_at
string
When the file was last successfully indexed (ISO 8601).
​
files[].last_error
string | null
Error from the last failed upload attempt, or null.
​
files[].metadata
object
Custom metadata merged from the upload request.
{
  "status": "success",
  "count": 1,
  "files": [
    {
      "file_id": "a1b2c3d4e5f67890",
      "absolute_path": "/uploads/document.pdf",
      "filename": "document.pdf",
      "file_type": ".pdf",
      "file_size": 125440,
      "file_mtime": "2026-06-05T18:50:08Z",
      "chunk_count": 3,
      "summary_count": 1,
      "status": "indexed",
      "path_exists": true,
      "ingested_at": "2026-06-05T18:50:20Z",
      "last_error": null,
      "metadata": { "department": "engineering" }
    }
  ]
}