Skip to main content
GET
/
api
/
v3
/
files
/
{id}
Retrieve a single file by ID
curl --request GET \
  --url https://api.lighton.ai/api/v3/files/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": 124,
  "filename": "customer_nda.pdf",
  "workspace": {
    "id": 3,
    "name": "Legal Team",
    "workspace_type": "custom"
  },
  "summaries": [
    {
      "language": "en",
      "summary": "Non-disclosure agreement between LightOn and Nimbus Labs."
    }
  ],
  "title": "Customer NDA",
  "extension": "pdf",
  "status": "embedded",
  "status_vision": "embedded",
  "created_at": "2024-01-14T14:20:00Z",
  "updated_at": "2024-01-14T14:22:00Z",
  "total_pages": 8,
  "tags": [
    {
      "id": 7,
      "name": "confidential",
      "auto_assigned": true
    },
    {
      "id": 12,
      "name": "Q1-2026",
      "auto_assigned": false
    }
  ],
  "created_by": {
    "id": 42,
    "first_name": "Jane",
    "last_name": "Doe",
    "username": "jdoe"
  },
  "signature": "T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2",
  "external_metadata": {
    "external_id": "legal-doc-456789",
    "doc_type": "nda",
    "additional_metadata": {
      "external_url": "https://contracts.example.com/legal/customer-nda"
    }
  },
  "content_types": [
    {
      "code": "nda",
      "path": "legal:contract:nda",
      "label": "Non-Disclosure Agreement",
      "breadcrumb": [
        {
          "code": "legal",
          "path": "legal",
          "label": "Legal"
        },
        {
          "code": "contract",
          "path": "legal:contract",
          "label": "Contract"
        },
        {
          "code": "nda",
          "path": "legal:contract:nda",
          "label": "Non-Disclosure Agreement"
        }
      ],
      "attribute_values": {
        "jurisdiction": {
          "value": [
            "FR",
            "US"
          ],
          "type": "multi-select",
          "attribute": {
            "name": "jurisdiction",
            "label": "Jurisdiction",
            "type": "multi-select",
            "required": true,
            "choices": [
              "FR",
              "US",
              "UK",
              "DE"
            ]
          }
        },
        "is_mutual": {
          "value": true,
          "type": "boolean",
          "attribute": {
            "name": "is_mutual",
            "label": "Is Mutual",
            "type": "boolean",
            "required": false
          }
        },
        "counterparty": {
          "value": "Nimbus Labs",
          "type": "text",
          "attribute": {
            "name": "counterparty",
            "label": "Counterparty",
            "type": "text",
            "required": false
          }
        }
      }
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
integer
required

A unique integer value identifying this Document.

Query Parameters

​
include_content
boolean

When true, include the full text content of the document in the response (default: false). Recommended to only enable when needed as content can be large.

Response

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

​
id
integer
required
read-only
​
filename
string
required
read-only

Filename of the document

​
workspace
object | null
required

Workspace the document belongs to

​
summaries
object[]
required
read-only

Document summaries (all languages)

​
extension
string
required

File extension of the document

​
created_at
string<date-time>
required

Creation date of the resource

​
updated_at
string<date-time>
required
read-only
​
total_pages
integer
required
read-only

Total number of pages

​
tags
object[]
required
read-only

List of tags associated with the document

​
created_by
object | null
required

User who created the file. Null when the file was created by the system.

​
upload_session_uuid
string<uuid> | null
required
read-only

Upload session UUID associated with this document

​
signature
string | null
required
read-only

TLSH hash for duplicate detection.

​
content_types
object[]
required
read-only

Facet content types with nested attribute values. Excludable via ?exclude=content_types.

​
title
string | null
Maximum string length: 255
​
status
enum<string>
  • 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
Available options:
pending,
pending_conversion,
converting,
parsing,
parsing_failed,
embedding,
embedding_failed,
embedded,
parsed,
fail,
updating
​
status_vision
enum<string>
  • pending - Pending
  • processing - Processing
  • embedded - Embedded
  • fail - Fail
  • - - Not available
Available options:
pending,
processing,
embedded,
fail,
-
​
size
integer | null
read-only

Size of the file in bytes.

​
content
string | null
deprecated
read-only

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
object[]
read-only

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.

​
status_detail
string | null

Detailed error information. Only present when document processing has failed.

​
parser
string | null

Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0').

​
external_metadata
object

External document metadata