---
title: "list_files"
method: GET
path: "/v1/workspaces/{workspace_id}/files"
tags: ["files"]
---

# list_files

`GET /v1/workspaces/{workspace_id}/files`

## Request

- Base URL: `https://ndi-api.nace.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/files`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/nace/apis/ndi-service/docs/v1/workspaces/:workspace_id/files/get.ts> (a function with typed inputs; its response is checked against the schema)

List source files with exact totals and access-filtered coverage.

Cost class: **fast** (structured-metadata predicates only; no index lookup).

The sanctioned completeness instrument: ``total_count`` is exact and
access-filtered; ``coverage`` says how many candidates the access gate
withheld and which labels would have been needed.  A caller that cannot
reconcile ``total_count`` with their own ledger knows the gap is
labelled content rather than a missing file.

Args:
    context: Resolved workspace plus the caller's access predicate.
    session: Database session.
    path_prefix: Only files whose path starts with this string.
    ingestion_status: Restrict to these ingestion statuses.
    categories: Restrict to these categories.
    file_types: Restrict to these file extensions (e.g. ``["pdf", "xlsx"]``).
    modified_after: Only files updated after this timestamp.
    modified_before: Only files updated before this timestamp.
    cursor: Opaque keyset cursor from the previous page's ``next_cursor``.
    limit: Rows per page.

Returns:
    ``FileListPage`` with items, paging metadata, and access coverage.

## Path parameters

- `workspace_id` string, uuid, required: Workspace identifier.

## Query parameters

- `path_prefix` string, nullable: Restrict to paths starting with this prefix.
- `ingestion_status` IngestionStatus[], nullable: Restrict to these ingestion statuses.
- `categories` string[], nullable: Restrict to these categories.
- `file_types` string[], nullable: Restrict to these file extensions.
- `modified_after` string, date-time, nullable: Only files updated after this timestamp.
- `modified_before` string, date-time, nullable: Only files updated before this timestamp.
- `cursor` string, nullable: Opaque cursor from a previous page's `next_cursor`. Omit for the first page.
- `limit` integer: Rows per page.

## Response `200`

Successful Response

- FileListPage: A page of source files plus the access honesty block. ``coverage`` reports how many candidates the access gate withheld and which labels would have been needed to see them. A workspace that declares no access labels always has an empty ``coverage``; ``total_count`` is always exact after filtering.
  - `items` File[], required: This page's rows, in the list's order.
    - `file_id` string, uuid, required
    - `workspace_id` string, uuid, required
    - `path` string, required: Full path relative to the workspace root. Send this exact string wherever a tool takes `path`: tools match it exactly.
    - `file_name` string, required: The last segment of `path`, for display only. A tool given it as `path` answers file_not_found.
    - `file_type` string, required
    - `size_bytes` integer, required
    - `observed_hash` string, required
    - `ingested_hash` string, nullable: Content hash at the last successful ingestion. Null with ingested_at means never ingested.
    - `ingestion_status` 'discovered' | 'queued' | 'ingesting' | 'ingested' | 'stale' | 'expired' | 'failed' | 'not_required', required: The only thing that says whether a file is searchable. ``expired`` cannot be derived from the hash pair: retention clears ``ingested_hash``, so an aged-out file and a never-ingested file look identical. They call for different customer actions, so the status carries the distinction the hashes cannot.
    - `ingested_at` string, date-time, nullable
    - `version` integer, required: Starts at 1; increments on every content replacement.
    - `category` string, nullable: Null until categorised.
    - `access_label` string, nullable: Exactly one label, or null when the workspace declares none.
    - `access_label_source` 'inherited' | 'classified' | 'mirrored': Which mechanism produced a document's label. The ``default_label`` fallback records as ``inherited``, so an audit can tell a real classification from a fallback.
    - `expires_at` string, date-time, nullable: When derived material for this file ages out.
    - `graph_inclusion` 'auto' | 'include' | 'exclude': This file's knowledge-graph inclusion policy, not its effective membership. 'auto' defers to the workspace's KG exclusion rules; 'include'/'exclude' override them for this one file. A file excluded by a workspace rule still reads 'auto' here, so this does not on its own tell an excluded file from one whose graph is not built yet — read representations.knowledge_graph for whether a build has covered it.
    - `labels` object: Caller-supplied metadata.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `next_cursor` string, nullable: Opaque; null means the last page.
  - `total_count` integer, required: Exact, and filtered by the caller's access predicate.
  - `coverage` Coverage: What the access gate withheld, in counts and label names only. Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request.
    - `restricted_candidates` integer
    - `labels_required` string[]: Which labels would have been needed to see the withheld candidates.
    - `request_access_hint` string, nullable

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `410`: Gone
- `413`: Request Entity Too Large
- `422`: Unprocessable Entity
- `424`: Failed Dependency
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `503`: Service Unavailable
- `504`: Gateway Timeout

---

[API](https://skmtc.dev/nace/apis/ndi-service.md) - [All operations](https://skmtc.dev/nace/apis/ndi-service/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/ndi-service/revisions/d9d1f8ec2207?raw)