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.

GET /api/v3/files

List files accessible to the authenticated user

cURL

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

200

ListOfFiles

{
  "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",
        "uploaded_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:35:00Z",
        "total_pages": 25,
        "tags": [
          {
            "id": 10,
            "name": "Project X",
            "auto_assigned": false
          }
        ],
        "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",
            "external_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": "-",
        "uploaded_at": "2024-01-14T14:20:00Z",
        "updated_at": "2024-01-14T14:22:00Z",
        "total_pages": 8,
        "tags": [],
        "external_metadata": null
      },
      {
        "id": 125,
        "filename": "data_analysis.xlsx",
        "workspace": null,
        "summaries": [],
        "title": "Sales Data Analysis",
        "extension": "xlsx",
        "status": "parsing",
        "status_vision": "-",
        "uploaded_at": "2024-01-16T09:15:00Z",
        "updated_at": "2024-01-16T09:16:00Z",
        "total_pages": 1,
        "tags": [],
        "external_metadata": null
      }
    ]
  ]
}

Authorizations

Authorization · string · header · required

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

Query Parameters

extension · string

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

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: uploaded_at, title, filename. Default: -uploaded_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)

uploaded_at_after · string<date-time>

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

uploaded_at_before · string<date-time>

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

workspace_id · string

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

Response

200

application/json

List of files accessible to the authenticated user

count · integer · required

Example:

123

results · object[] · required

Show child attributes

next · string<uri> | null

Example:

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

previous · string<uri> | null

Example:

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