---
title: "List files accessible to the authenticated user"
method: GET
path: "/api/v3/files"
tags: ["Files"]
---

# List files accessible to the authenticated user

`GET /api/v3/files`

Retrieve a paginated list of files (documents) accessible to the authenticated user.
Results are ordered by upload date (newest first) by default.
When using the `search` parameter, results are ordered by relevance.

**Public datasets:** instance admins (holding `MANAGE_PUBLIC_DATASET`) always see
public-dataset files. A company that has opted in (`allow_access_to_public_datasets`)
with a workspace-scoped API key granting a public workspace also sees its files —
filter with `workspace_id` to scope the list to it.

## Query parameters

- `attribute` string
- `content_type` string
- `created_at_after` string, date-time
- `created_at_before` string, date-time
- `extension` string
- `external_metadata__doc_type` string
- `external_metadata__external_id` string
- `filename` string
- `group_id` string
- `include_details` boolean
- `max_documents` integer
- `ordering` string
- `owner_id` string
- `page` integer
- `page_size` integer
- `search` string
- `search_details` boolean
- `search_details_chunks_limit` integer
- `status` 'converting' | 'embedded' | 'embedding' | 'embedding_failed' | 'fail' | 'parsed' | 'parsing' | 'parsing_failed' | 'pending' | 'pending_conversion' | 'updating'
- `status_vision` '-' | 'embedded' | 'fail' | 'pending' | 'processing'
- `tag_id` string
- `title` string
- `total_pages_max` integer, nullable
- `total_pages_min` integer, nullable
- `updated_at_after` string, date-time
- `updated_at_before` string, date-time
- `upload_session_uuid` string
- `workspace_id` string

## Response `200`

List of files accessible to the authenticated user

- PaginatedFileListResponseSerializerV3List
  - `count` integer, required
  - `next` string, uri, nullable
  - `previous` string, uri, nullable
  - `results` FileListResponseSerializerV3[], required
    - `id` integer, required
    - `filename` string, required — Filename of the document
    - `workspace` WorkspaceInFileResponseSerializerV3, required — Minimal workspace info for file responses.
      - `id` integer, required — Workspace ID
      - `name` string, required — Workspace name
      - `workspace_type` string, required — Workspace type (shared or personal)
    - `summaries` DocumentSummaryResponse[] — Document summaries (all languages)
      - `language` 'en' | 'fr' | 'es' | 'it' | 'ar' | 'nl' | 'sv' | 'de' | 'ja' | 'zh' | 'ko' — * `en` - English * `fr` - French * `es` - Spanish * `it` - Italian * `ar` - Arabic * `nl` - Dutch * `sv` - Swedish * `de` - German * `ja` - Japanese * `zh` - Chinese * `ko` - Korean
      - `summary` string, required — Summary of the document.
    - `title` string, nullable
    - `extension` string, required — File extension of the document
    - `status` 'pending' | 'pending_conversion' | 'converting' | 'parsing' | 'parsing_failed' | 'embedding' | 'embedding_failed' | 'embedded' | 'parsed' | 'fail' | 'updating' — * `pending` - Pending * `pending_conversion` - Pending Conversion * `converting` - Converting * `parsing` - Parsing * `parsing_failed` - Parsing Failed * `embedding` - Embedding * `embedding_failed` - Embedding Failed * `embedded` - Embedded * `parsed` - Parsed * `fail` - Fail * `updating` - Updating
    - `status_detail` string, nullable — Detailed error information. Only present when document processing has failed.
    - `status_vision` 'pending' | 'processing' | 'embedded' | 'fail' | '-' — * `pending` - Pending * `processing` - Processing * `embedded` - Embedded * `fail` - Fail * `-` - Not available
    - `created_at` string, date-time, required — Creation date of the resource
    - `updated_at` string, date-time, required
    - `total_pages` integer, required — Total number of pages
    - `size` integer, nullable — Size of the file in bytes.
    - `tags` TagItem[], required — List of tags associated with the document
      - `id` integer, required — Tag ID
      - `name` string, required — Tag name
      - `auto_assigned` boolean, required — True if this tag was automatically assigned by the system, False if manually assigned by a user
    - `created_by` CreatedBy, required — Shallow user object for the file creator.
      - `id` integer, required — User ID
      - `first_name` string, required — First name
      - `last_name` string, required — Last name
      - `username` string, required — Username
    - `upload_session_uuid` string, uuid, nullable, required — Upload session UUID associated with this document
    - `search_details` SearchDetails — Serializer for search details in file list response.
      - `relevant_chunks` RelevantChunkScoredV3[], required — Relevant chunks ordered by score descending
        - `text` string, required — Chunk text content
        - `chunk_type` string — Chunk type (e.g. text/table)
        - `score` number, double, required — Combined retrieval score (higher is better, no fixed upper bound). No relevance scoring runs on file search.
        - `scores` ChunkScoresSchema, required — Per-signal score breakdown. Schema for OpenAPI; higher is better; null = not computed. ``text``/``vision`` are 0–1 similarities; ``keyword`` and ``multivector`` are unbounded (higher is better). Same shape as /api/v3/search and /retrieve. ``relevance`` is always null on the file-search path — no relevance scoring runs on this endpoint. Defined locally to avoid a circular import with the /retrieve serializer module.
          - `text` number, double, nullable, required — Semantic text similarity (0–1, higher is better). Null in vision mode.
          - `vision` number, double, nullable, required — Vision page similarity (0–1, higher is better). Null when the document has no vision index.
          - `keyword` number, double, nullable, required — Keyword match score (higher is better, no fixed upper bound). Null in vision mode.
          - `multivector` number, double, nullable, required — Token-level similarity score (higher is better, no fixed upper bound). Null when multi-vector scoring is disabled.
          - `relevance` number, double, nullable, required — Relevance score (0–1, higher is better). Always null on file search — no relevance scoring runs on this endpoint.
    - `signature` string, nullable — TLSH hash for duplicate detection. Only included when include_details=true (detail field).
    - `parser` string, nullable — Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0'). Only included when include_details=true (detail field).
    - `external_metadata` ExternalMetadataResponse
      - `external_id` string, required — External document ID
      - `doc_type` string, required — External document type
      - `additional_metadata` unknown, required
    - `content_types` DocumentFacetCompactSchema[], required — Facet content types with nested attribute values. Excludable via ?exclude=content_types.
      - `path` string, required — Colon-separated content type path (e.g. legal:contract:nda)
      - `label` string, required — User-readable label (leaf node)
      - `attribute_values` object — Map of attribute name to {value, type}. Only present when include_details=true.

## Other responses

- `401` — Authentication failed - missing or invalid API key
- `403` — Permission denied
- `404` — Not found
- `429` — Too many requests - rate limit exceeded

---

[API](https://skmtc.net/lighton/apis/lighton-api.md) · [All operations](https://skmtc.net/lighton/apis/lighton-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lighton/lighton-api/versions/86c57e94ef15/schema)