---
title: "Retrieve a single file by ID"
method: GET
path: "/api/v3/files/{id}"
tags: ["Files"]
---

# Retrieve a single file by ID

`GET /api/v3/files/{id}`

Retrieve detailed information for a single file by its ID.
Only files that the authenticated user is authorized to access will be returned.
Returns 404 if the file does not exist or the user does not have access.

Query Parameters:
- include_content: Set to 'true' to include the full text content of the document (default: false)

The response includes comprehensive document details including:
- Basic metadata (id, filename, title, extension, dates, page count)
- Full text content of the document (only when include_content=true)
- Processing status (status, status_vision, status_detail if failed)
- Associated tags and workspace information
- File size (if available)
- Parser/ingestion pipeline (if available, after parsing starts)
- Signature (TLSH hash for duplicate detection)
- Facet content types and nested attribute values (full expanded with attribute definitions)

**Public datasets:** reachable by instance admins (`MANAGE_PUBLIC_DATASET`) unconditionally,
and by a company that has opted in (`allow_access_to_public_datasets`) with a
workspace-scoped API key granting the file's public workspace.

## Path parameters

- `id` integer, required

## Query parameters

- `include_content` boolean

## Response `200`

Detailed file information. Always uses full expanded content types (Tier 3) with breadcrumb, code, and attribute definitions including type, required, and choices.

- FileRetrieveResponseSerializerV3
  - `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[], required — 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_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
  - `signature` string, nullable, required — TLSH hash for duplicate detection.
  - `content` string, nullable — Deprecated — use `pages[]` instead. Full text content of the document, derived from per-page text, as a single flat string. Only included when include_content=true query parameter is provided. Will be removed in a future release.
  - `pages` Page[] — Per-page document text in the canonical `{ index, markdown }` shape shared with /parse and /ocr. Only included when include_content=true. Intended replacement for the flat `content` string. For documents ingested before per-page text was stored, the full `content` is returned as a single page (index 1); empty only when there is no content at all.
    - `index` integer, required — Page number within the document (1-based).
    - `markdown` string, required — Page text rendered as Markdown.
  - `status_detail` string, nullable — Detailed error information. Only present when document processing has failed.
  - `parser` string, nullable — Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0').
  - `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
- `404` — File not found or not accessible

---

[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)