Skip to main content
GET
/
api
/
v3
/
files
List files accessible to the authenticated user
curl --request GET \
  --url https://paradigm.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": 123,
        "filename": "project_proposal.pdf",
        "workspace": {
          "id": 1,
          "name": "Engineering Team",
          "workspace_type": "custom"
        },
        "summaries": [
          {
            "language": "en",
            "summary": "This document outlines Q4 initiatives..."
          }
        ],
        "title": "Q4 Project Proposal",
        "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": {
          "external_id": "srv-456789",
          "doc_type": "incident",
          "additional_metadata": {
            "name": "ServiceNow Incident SRV-456789",
            "version": "2.3",
            "mime_type": "34",
            "created_at": "2024-01-10T08:00:00Z",
            "modified_at": "2024-01-12T16:45:00Z",
            "last_synced_time_at": "2024-01-12T17:00:00Z",
            "external_url": "https://servicenow.example.com/incident/srv-456789",
            "full_path": "ServiceNow > Incidents > SRV-456789"
          }
        }
      },
      {
        "id": 124,
        "filename": "meeting_notes.docx",
        "workspace": {
          "id": 2,
          "name": "Marketing",
          "workspace_type": "custom"
        },
        "summaries": [],
        "title": "Team Meeting Notes - January",
        "extension": "docx",
        "status": "embedded",
        "status_vision": "-",
        "created_at": "2024-01-14T14:20:00Z",
        "updated_at": "2024-01-14T14:22:00Z",
        "total_pages": 8,
        "tags": [],
        "created_by": {
          "id": 43,
          "first_name": "John",
          "last_name": "Smith",
          "username": "jsmith"
        },
        "external_metadata": null
      },
      {
        "id": 125,
        "filename": "KB-2024-003.pdf",
        "workspace": null,
        "summaries": [],
        "title": "Knowledge Base Article KB-2024-003",
        "extension": "pdf",
        "status": "parsing",
        "status_vision": "-",
        "created_at": "2024-01-16T09:15:00Z",
        "updated_at": "2024-01-16T09:16:00Z",
        "total_pages": 1,
        "tags": [],
        "created_by": null,
        "external_metadata": {
          "external_id": "KB-2024-003",
          "doc_type": "knowledge_article",
          "additional_metadata": {
            "external_url": "https://confluence.example.com/kb/KB-2024-003",
            "external_full_path": "Confluence > Knowledge Base > KB-2024-003"
          }
        }
      }
    ]
  ]
}

Authorizations

​
Authorization
string
header
required

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

Query Parameters

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

​
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"