Skip to main content
GET
/
api
/
v3
/
files
List files accessible to the authenticated user
curl --request GET \
  --url https://api.lighton.ai/api/v3/files \
  --header 'Authorization: Bearer <token>'
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    [
      {
        "id": 124,
        "filename": "customer_nda.pdf",
        "workspace": {
          "id": 3,
          "name": "Legal Team",
          "workspace_type": "custom"
        },
        "summaries": [],
        "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": [],
        "created_by": {
          "id": 42,
          "first_name": "Jane",
          "last_name": "Doe",
          "username": "jdoe"
        },
        "external_metadata": {
          "external_id": "legal-doc-456789",
          "doc_type": "nda",
          "additional_metadata": {
            "external_url": "https://contracts.example.com/legal/customer-nda",
            "external_full_path": "Contracts > Customers > NDA"
          }
        },
        "content_types": [
          {
            "path": "legal:contract:nda",
            "label": "Non-Disclosure Agreement",
            "labels": [
              "Legal",
              "Contract",
              "Non-Disclosure Agreement"
            ],
            "attributes": [
              {
                "name": "jurisdiction",
                "label": "Jurisdiction",
                "value": [
                  "FR",
                  "US"
                ],
                "type": "multi-select"
              },
              {
                "name": "confidentiality_level",
                "label": "Confidentiality Level",
                "value": "Confidential",
                "type": "select"
              },
              {
                "name": "parties",
                "label": "Parties",
                "value": "LightOn, Nimbus Labs",
                "type": "text"
              },
              {
                "name": "contract_status",
                "label": "Contract Status",
                "value": "Executed",
                "type": "select"
              },
              {
                "name": "counterparty",
                "label": "Counterparty",
                "value": "Nimbus Labs",
                "type": "text"
              },
              {
                "name": "is_mutual",
                "label": "Is Mutual",
                "value": true,
                "type": "boolean"
              }
            ]
          }
        ]
      },
      {
        "id": 123,
        "filename": "design_doc.pdf",
        "workspace": {
          "id": 1,
          "name": "Engineering Team",
          "workspace_type": "custom"
        },
        "summaries": [
          {
            "language": "en",
            "summary": "This document outlines Q4 initiatives..."
          }
        ],
        "title": "Retrieval Service Design Document",
        "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"
        },
        "external_metadata": null,
        "content_types": [
          {
            "path": "tech:specification:design-doc",
            "label": "Design Document",
            "labels": [
              "Tech",
              "Specification",
              "Design Document"
            ],
            "attributes": [
              {
                "name": "owner_team",
                "label": "Owner Team",
                "value": "Platform Engineering",
                "type": "text"
              },
              {
                "name": "maturity",
                "label": "Maturity",
                "value": "Approved",
                "type": "select"
              },
              {
                "name": "component",
                "label": "Component",
                "value": "Document Retrieval Service",
                "type": "text"
              }
            ]
          }
        ]
      }
    ]
  ]
}

Documentation Index

Fetch the complete documentation index at: https://developers.lighton.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
attribute
string

[Facet] Filter by attribute value. Repeatable for AND. Formats: ?attribute=name (has any value), ?attribute=name:value (exact match), ?attribute=name:>value (gt), ?attribute=name:<value (lt), ?attribute=name:>=value, ?attribute=name:<=value, ?attribute=name:prefix* (starts with). Pipe or comma for OR inside one parameter: ?attribute=status:active|draft or ?attribute=status:active,draft. Repeated attribute parameters mean AND across filters. Scoped syntax: ?attribute=content_type(legal:compliance).regulation:AML. Smart dates: ?attribute=filing_date:2023 (year), ?attribute=filing_date:2023-06 (month). Type-aware matching: booleans use true/false, select uses one choice string, and multi-select matches list membership.

​
content_type
string

[Facet] Filter by content type path (comma-separated). Default plain-path behavior is exact-or-subtree matching (legal matches legal, legal:contract, legal:contract:nda). Comma-separated values are OR. Wildcards: *contract* (contains), legal:contract* (prefix).

​
created_at_after
string<date-time>

Filter by created_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?created_at_after=2024-01-01&created_at_before=2024-01-01T23:59:59)

​
created_at_before
string<date-time>

Filter by created_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?created_at_after=2024-01-01&created_at_before=2024-01-01T23:59:59)

​
exclude
string

Exclude nested fields for a lighter response. Comma-separated. Excludable: summaries, tags, content_types, content_types.attributes, workspace, created_by, external_metadata.

​
extension
string

Filter by file extensions (comma-separated, e.g., ?extension=pdf,docx)

​
external_metadata__doc_type
string

Filter by external document type (case-insensitive partial match). Only returns documents that have external metadata. Example: ?external_metadata__doc_type=gitlab matches 'gitlab issue', 'gitlab ticket', 'Gitlab MR', etc.

​
external_metadata__external_id
string

Filter by external document ID (exact match). Matches the doc_id stored in the document's external metadata. Only returns documents that have external metadata. Example: ?external_metadata__external_id=SN-12345

​
filename
string

Filter by filename (case-insensitive partial match)

​
group_id
string

Filter by group IDs (comma-separated, e.g., ?group_id=1,2,3)

​
include_details
boolean

Include detail fields (e.g., TLSH signature for duplicate detection, parser/ingestion pipeline). Default: false.

​
max_documents
integer

Maximum number of documents to return (default: 50, minimum: 1, maximum: 500)

​
ordering
string

Sort results by field. Prefix with '-' for descending order. Allowed fields: created_at, title, filename. Default: -created_at (newest first). Ignored when 'search' is provided (results ordered by relevance).

​
owner_id
string

Filter by owner user IDs (comma-separated, e.g., ?owner_id=1,2,3)

​
page
integer

A page number within the paginated result set.

​
page_size
integer

Number of results to return per page.

​
search
string

Optional semantic search query. When provided, results are ordered by relevance.

​
search_details
boolean

When true (and search is provided), include top relevant chunk(s) per document.

​
search_details_chunks_limit
integer

Max number of relevant chunks to return per document when search_details=true (1-10, default: 3).

​
status
enum<string>

Filter by status values (comma-separated, e.g., ?status=pending,embedded)

Available options:
embedded,
embedding,
embedding_failed,
fail,
parsing,
parsing_failed,
pending,
updating
​
status_vision
enum<string>

Filter by vision status values (comma-separated, e.g., ?status_vision=pending,embedded)

Available options:
-,
embedded,
fail,
pending,
processing
​
tag_id
string

Filter by tag IDs (comma-separated, e.g., ?tag_id=1,2,3)

​
title
string

Filter by title (case-insensitive partial match)

​
total_pages_max
integer | null

Filter by total pages range (e.g., ?total_pages_min=10&total_pages_max=50)

Required range: -2147483648 <= x <= 2147483647
​
total_pages_min
integer | null

Filter by total pages range (e.g., ?total_pages_min=10&total_pages_max=50)

Required range: -2147483648 <= x <= 2147483647
​
updated_at_after
string<date-time>

Filter by updated_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?updated_at_after=2024-01-01&updated_at_before=2024-01-01T23:59:59)

​
updated_at_before
string<date-time>

Filter by updated_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?updated_at_after=2024-01-01&updated_at_before=2024-01-01T23:59:59)

​
upload_session_uuid
string

Filter by upload session UUID (e.g., ?upload_session_uuid=123e4567-e89b-12d3-a456-426614174000)

​
workspace_id
string

Filter by workspace IDs (comma-separated, e.g., ?workspace_id=1,2,3)

Response

List of files accessible to the authenticated user

​
count
integer
required
Example:

123

​
results
object[]
required
​
next
string<uri> | null
Example:

"http://api.example.org/accounts/?page=4"

​
previous
string<uri> | null
Example:

"http://api.example.org/accounts/?page=2"