curl --request PATCH \
  --url https://paradigm.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.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

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

Delete a file Retrieve document chunks