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": "shared"
        },
        "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": [
          {
            "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"
        },
        "external_metadata": {
          "external_id": "legal-doc-456789",
          "doc_type": "nda",
          "additional_metadata": {
            "external_url": "https://contracts.example.com/legal/customer-nda"
          }
        },
        "content_types": [
          {
            "path": "legal:contract:nda",
            "label": "Non-Disclosure Agreement"
          }
        ]
      },
      {
        "id": 123,
        "filename": "design_doc.pdf",
        "workspace": {
          "id": 1,
          "name": "Engineering Team",
          "workspace_type": "shared"
        },
        "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"
        },
        "content_types": []
      }
    ]
  ]
}

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. Repeated attribute entries are ANDed; values inside one entry are ORed with | (pipe is the recommended OR delimiter — comma also works but can be ambiguous with multi-key values). Example: attribute=fiscal_year:2024|2025&attribute=status:active → (fiscal_year 2024 OR 2025) AND (status active). Formats: name (has any value), name:value (exact), name:>value / name:>=value (gt/gte), name:<value / name:<=value (lt/lte), name:prefix* (starts with, case-insensitive), name:*text* (contains, case-insensitive), name:a|b (OR). Smart dates: filing_date:2023 (year), filing_date:2023-06 (month). Type-aware: booleans (true/false), multi-select (membership check). Scoped: content_type(legal:compliance).regulation:AML.

​
content_type
string

[Facet] Filter by content type path. Multiple values are OR. Exact-or-subtree matching by default (e.g. legal matches legal, legal:contract). 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)

​
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, parser, summaries, and content type attribute values). 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, filename, title, total_pages, size. 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:
converting,
embedded,
embedding,
embedding_failed,
fail,
parsed,
parsing,
parsing_failed,
pending,
pending_conversion,
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"