List files accessible to the authenticated user

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lighton.ai/api/v3/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lighton.ai/api/v3/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lighton.ai/api/v3/files"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.lighton.ai/api/v3/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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": []
      }
    ]
  ]
}

Files

List files accessible to the authenticated user

Retrieve a paginated list of files (documents) accessible to the authenticated user. Results are ordered by upload date (newest first) by default. When using the search parameter, results are ordered by relevance.

Public datasets: instance admins (holding MANAGE_PUBLIC_DATASET) always see public-dataset files. A company that has opted in (allow_access_to_public_datasets) with a workspace-scoped API key granting a public workspace also sees its files — filter with workspace_id to scope the list to it.

GET

api

files

List files accessible to the authenticated user

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lighton.ai/api/v3/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lighton.ai/api/v3/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lighton.ai/api/v3/files"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.lighton.ai/api/v3/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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.

string

Semantic search query. When provided, results are ordered by combined retrieval score descending. No relevance scoring is applied — scores.relevance is always null in search_details chunks.

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

Show child attributes

string<uri> | null

Example:

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

string<uri> | null

Example:

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

⌘I

Overview

Intelligence

Document Processing

Administration

List files accessible to the authenticated user

Authorizations

Query Parameters

Response