Retrieve a single file by ID

curl --request GET \
  --url https://paradigm.lighton.ai/api/v3/files/{id} \
  --header 'Authorization: Bearer <token>'

{
  "id": 123,
  "filename": "project_proposal.pdf",
  "workspace": {
    "id": 1,
    "name": "Engineering Team"
  },
  "summaries": [
    {
      "language": "en",
      "summary": "This document outlines Q4 initiatives..."
    }
  ],
  "title": "Q4 Project Proposal",
  "extension": "pdf",
  "status": "embedded",
  "status_vision": "embedded",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:35:00Z",
  "total_pages": 25,
  "size": 2458624,
  "tags": [
    {
      "id": 10,
      "name": "Project X",
      "auto_assigned": false
    }
  ],
  "created_by": {
    "id": 42,
    "first_name": "Jane",
    "last_name": "Doe",
    "username": "jdoe"
  },
  "signature": "T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2",
  "parser": "v2.2.1",
  "external_metadata": null
}

Files

Retrieve a single file by 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)

GET

/

api

/

v3

/

files

/

{id}

Retrieve a single file by ID

curl --request GET \
  --url https://paradigm.lighton.ai/api/v3/files/{id} \
  --header 'Authorization: Bearer <token>'

{
  "id": 123,
  "filename": "project_proposal.pdf",
  "workspace": {
    "id": 1,
    "name": "Engineering Team"
  },
  "summaries": [
    {
      "language": "en",
      "summary": "This document outlines Q4 initiatives..."
    }
  ],
  "title": "Q4 Project Proposal",
  "extension": "pdf",
  "status": "embedded",
  "status_vision": "embedded",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:35:00Z",
  "total_pages": 25,
  "size": 2458624,
  "tags": [
    {
      "id": 10,
      "name": "Project X",
      "auto_assigned": false
    }
  ],
  "created_by": {
    "id": 42,
    "first_name": "Jane",
    "last_name": "Doe",
    "username": "jdoe"
  },
  "signature": "T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2",
  "parser": "v2.2.1",
  "external_metadata": null
}

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

id

integer

required

read-only

filename

string

required

read-only

Filename of the document

workspace

object

required

Workspace the document belongs to

Show child attributes

summaries

object[]

required

read-only

Document summaries (all languages)

Show child attributes

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

size

integer | null

required

read-only

Size of the file in bytes.

tags

object[]

required

read-only

List of tags associated with the document

Show child attributes

created_by

object

required

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

Show child attributes

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.

external_metadata

object

required

External document metadata

Show child attributes

title

string | null

Maximum string length: 255

status

enum<string>

pending - Pending
parsing - Parsing
parsing_failed - Parsing Failed
embedding - Embedding
embedding_failed - Embedding Failed
embedded - Embedded
fail - Fail
updating - Updating

Available options:

pending,

parsing,

parsing_failed,

embedding,

embedding_failed,

embedded,

fail,

updating

status_vision

enum<string>

pending - Pending
processing - Processing
embedded - Embedded
fail - Fail
- - Not available

Available options:

pending,

processing,

embedded,

fail,

-

content

string | null

Full text content of the document. Only included when include_content=true query parameter is provided.

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

Upload a file Delete a file