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

# list_files

> 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.



## OpenAPI

````yaml /openapi.json get /v1/workspaces/{workspace_id}/files
openapi: 3.1.0
info:
  description: >-
    Document intelligence: parse, split, classify, extract, and ground files, or
    build a searchable workspace. Authenticate with ``X-API-Key``.
  title: NDI Platform API
  version: 0.1.0
servers:
  - url: https://ndi-api.nace.ai
security: []
tags: []
paths:
  /v1/workspaces/{workspace_id}/files:
    get:
      tags:
        - files
      summary: list_files
      description: >-
        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.
      operationId: list_files_v1_workspaces__workspace_id__files_get
      parameters:
        - description: Workspace identifier.
          in: path
          name: workspace_id
          required: true
          schema:
            description: Workspace identifier.
            format: uuid
            title: Workspace Id
            type: string
        - description: Restrict to paths starting with this prefix.
          in: query
          name: path_prefix
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Restrict to paths starting with this prefix.
            title: Path Prefix
        - description: Restrict to these ingestion statuses.
          in: query
          name: ingestion_status
          required: false
          schema:
            anyOf:
              - items:
                  $ref: '#/components/schemas/IngestionStatus'
                type: array
              - type: 'null'
            description: Restrict to these ingestion statuses.
            title: Ingestion Status
        - description: Restrict to these categories.
          in: query
          name: categories
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Restrict to these categories.
            title: Categories
        - description: Restrict to these file extensions.
          in: query
          name: file_types
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Restrict to these file extensions.
            title: File Types
        - description: Only files updated after this timestamp.
          in: query
          name: modified_after
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: Only files updated after this timestamp.
            title: Modified After
        - description: Only files updated before this timestamp.
          in: query
          name: modified_before
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: Only files updated before this timestamp.
            title: Modified Before
        - description: >-
            Opaque cursor from a previous page's `next_cursor`. Omit for the
            first page.
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Opaque cursor from a previous page's `next_cursor`. Omit for the
              first page.
            title: Cursor
        - description: Rows per page.
          in: query
          name: limit
          required: false
          schema:
            default: 50
            description: Rows per page.
            maximum: 200
            minimum: 1
            title: Limit
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListPage'
          description: Successful Response
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Gateway Timeout
        default:
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  detail: null
                  message: >-
                    Request body has extra fields that this operation does not
                    accept.
                  request_id: req-01j9k2n3p4q5r6s7t8v9
                  retryable: false
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: >-
            Typed error envelope used by every 4xx and 5xx. ``error.code``
            distinguishes the failure; HTTP status is a consequence of the code.
      security:
        - APIKeyHeader: []
components:
  schemas:
    IngestionStatus:
      description: >-
        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.
      enum:
        - discovered
        - queued
        - ingesting
        - ingested
        - stale
        - expired
        - failed
        - not_required
      title: IngestionStatus
      type: string
    FileListPage:
      additionalProperties: false
      description: >-
        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.
      properties:
        coverage:
          $ref: '#/components/schemas/Coverage'
        items:
          items:
            $ref: '#/components/schemas/File'
          title: Items
          type: array
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: Opaque; null means the last page.
          title: Next Cursor
        total_count:
          description: Exact, and filtered by the caller's access predicate.
          title: Total Count
          type: integer
      required:
        - items
        - total_count
      title: FileListPage
      type: object
    ErrorEnvelope:
      description: Every non-2xx body on ``/v1``.
      example:
        error:
          code: invalid_request
          detail: null
          message: Request body has extra fields that this operation does not accept.
          request_id: req-01j9k2n3p4q5r6s7t8v9
          retryable: false
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
        - error
      title: ErrorEnvelope
      type: object
    Coverage:
      additionalProperties: false
      description: >-
        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.
      properties:
        labels_required:
          description: Which labels would have been needed to see the withheld candidates.
          items:
            type: string
          title: Labels Required
          type: array
        request_access_hint:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Access Hint
        restricted_candidates:
          default: 0
          title: Restricted Candidates
          type: integer
      title: Coverage
      type: object
    File:
      additionalProperties: false
      description: >-
        A source file. The derived tree is platform-owned and has no CRUD
        surface.
      properties:
        access_label:
          anyOf:
            - type: string
            - type: 'null'
          description: Exactly one label, or null when the workspace declares none.
          title: Access Label
        access_label_source:
          anyOf:
            - $ref: '#/components/schemas/AccessLabelSource'
            - type: 'null'
        category:
          anyOf:
            - type: string
            - type: 'null'
          description: Null until categorised.
          title: Category
        created_at:
          format: date-time
          title: Created At
          type: string
        expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When derived material for this file ages out.
          title: Expires At
        file_id:
          format: uuid
          title: File Id
          type: string
        file_name:
          title: File Name
          type: string
        file_type:
          title: File Type
          type: string
        graph_inclusion:
          default: auto
          description: >-
            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.
          enum:
            - auto
            - include
            - exclude
          title: Graph Inclusion
          type: string
        ingested_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Ingested At
        ingested_hash:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Content hash at the last successful ingestion. Null with ingested_at
            means never ingested.
          title: Ingested Hash
        ingestion_status:
          $ref: '#/components/schemas/IngestionStatus'
        labels:
          additionalProperties:
            type: string
          description: Caller-supplied metadata.
          title: Labels
          type: object
        observed_hash:
          title: Observed Hash
          type: string
        path:
          title: Path
          type: string
        size_bytes:
          title: Size Bytes
          type: integer
        updated_at:
          format: date-time
          title: Updated At
          type: string
        version:
          description: Starts at 1; increments on every content replacement.
          title: Version
          type: integer
        workspace_id:
          format: uuid
          title: Workspace Id
          type: string
      required:
        - file_id
        - workspace_id
        - path
        - file_name
        - file_type
        - size_bytes
        - observed_hash
        - ingestion_status
        - version
        - created_at
        - updated_at
      title: File
      type: object
    Error:
      description: The error object, per spec 12 §1.8.
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        detail:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Structured payload, when the code carries one.
          title: Detail
        message:
          description: Human- and model-readable; says what to do differently.
          title: Message
          type: string
        request_id:
          description: Per-request correlation id; matches the ``X-Request-Id`` header.
          title: Request Id
          type: string
        retryable:
          description: Whether retrying the identical request could succeed.
          title: Retryable
          type: boolean
      required:
        - code
        - message
        - retryable
        - request_id
      title: Error
      type: object
    AccessLabelSource:
      description: |-
        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.
      enum:
        - inherited
        - classified
        - mirrored
      title: AccessLabelSource
      type: string
    ErrorCode:
      description: |-
        Every error the ``/v1`` surface can return.

        Clients must treat this as an **open** enum: a new member is an additive
        change (spec 12 §9), and a client that crashes on an unknown code makes
        every future error a breaking change.
      enum:
        - invalid_request
        - unsupported_file_type
        - file_too_large
        - invalid_schema
        - invalid_sql
        - invalid_path_prefix
        - command_not_permitted
        - batch_too_large
        - domain_validation_failed
        - default_label_required
        - wait_required_for_zero_retention
        - workspace_not_found
        - file_not_found
        - job_not_found
        - upload_not_found
        - node_not_found
        - schema_not_found
        - domain_not_found
        - session_not_found
        - access_label_not_found
        - path_conflict
        - schema_version_conflict
        - access_label_name_taken
        - workspace_name_taken
        - access_label_in_use
        - upload_expired
        - file_not_ingested
        - workspace_deleting
        - workspace_not_deletable
        - ingestion_in_progress
        - job_not_cancellable
        - confirmation_required
        - domain_not_published
        - domain_in_use
        - reserved_domain_slug
        - kg_not_built
        - kg_build_in_progress
        - session_busy
        - range_not_satisfiable
        - result_expired
        - access_denied
        - access_backstop_violation
        - access_mode_not_implemented
        - rate_limited
        - concurrency_limit_reached
        - quota_exceeded
        - corrupt_file
        - zero_byte_file
        - encrypted_file
        - parse_failed
        - ocr_failed
        - conversion_failed
        - sheetless_workbook
        - unplayable_media
        - unclassified_pages
        - job_cancelled
        - job_timeout
        - upstream_unavailable
        - internal_error
        - unauthorized
        - not_implemented
      title: ErrorCode
      type: string
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey

````