curl --request PATCH \
  --url https://paradigm-preprod.lighton.ai/api/v3/files/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data'

{
  "id": 123,
  "filename": "project_proposal.pdf",
  "workspace": {
    "id": 1,
    "name": "Engineering Team"
  },
  "summaries": [
    {
      "language": "en",
      "summary": "This document outlines Q4 initiatives..."
    }
  ],
  "title": "Updated Document Title",
  "extension": "pdf",
  "status": "embedded",
  "status_vision": "embedded",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:45:00Z",
  "total_pages": 25,
  "size": 2458624,
  "tags": [
    {
      "id": 1,
      "name": "Compliance",
      "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

Update file metadata

Update mutable fields of a file (document).

Updatable fields:

title: Update the document title
tags: Replace ALL tags for the document (both manual and auto-assigned)
external_metadata: Create or update external source metadata

Tag replacement behavior:

Providing a tags array replaces ALL existing tags (manual and auto-assigned)
To remove all tags, send [0] (sentinel value for multipart format)
Omitting tags field leaves tags unchanged
New tags are marked as manually assigned (auto_assigned=False)

External metadata behavior:

When creating for the first time, external_id is required
When updating existing metadata, external_id is optional (existing value is preserved)
Fields in additional_metadata are merged (not replaced) with existing values

Validation:

Returns 400 if only immutable fields are provided (mutable fields: ‘external_metadata’, ‘tags’, ‘title’)
Returns 400 if tag IDs are invalid or don’t belong to user’s company
Returns 404 if document doesn’t exist or user doesn’t have access

PATCH

/

api

/

v3

/

files

/

{id}

curl --request PATCH \
  --url https://paradigm-preprod.lighton.ai/api/v3/files/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data'

{
  "id": 123,
  "filename": "project_proposal.pdf",
  "workspace": {
    "id": 1,
    "name": "Engineering Team"
  },
  "summaries": [
    {
      "language": "en",
      "summary": "This document outlines Q4 initiatives..."
    }
  ],
  "title": "Updated Document Title",
  "extension": "pdf",
  "status": "embedded",
  "status_vision": "embedded",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:45:00Z",
  "total_pages": 25,
  "size": 2458624,
  "tags": [
    {
      "id": 1,
      "name": "Compliance",
      "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.

Body

Request serializer for PATCH /api/v3/files/{id} endpoint.

Allows partial updates to mutable document fields:

title: Update the document title
tags: Replace ALL tags for the document (both manual and auto-assigned)
external_metadata: Create or update external source metadata

Immutable fields (if provided, will return 400):

file, filename, workspace_id, parser, etc.

title

string

Updated title for the document.

Maximum string length: 255

tags

integer[]

List of tag IDs to replace ALL existing tags (both manual and auto-assigned). To remove all tags when using multipart format, send [0] as the sentinel value.

external_metadata

object

External source metadata to create or update. external_id is required when no external metadata record exists yet. Fields in additional_metadata are merged (not replaced) with existing values.

Show child attributes

Response

File updated successfully

id

integer

required

filename

string

required

Filename of the document

workspace

object

required

Workspace the document belongs to

Show child attributes

summaries

object[]

required

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

total_pages

integer

required

Total number of pages

size

integer | null

required

Size of the file in bytes.

tags

object[]

required

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

Upload session UUID associated with this document

signature

string | null

required

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

Delete a file Retrieve document chunks