Skip to main content
Retrieve a paginated list of all documents you have access to in your Paradigm instance. This endpoint supports advanced filtering, semantic search, and flexible pagination.

​
Prerequisites

  • A Paradigm API key: if you do not have one, go to your Paradigm profile and generate a new API key.
  • Access to documents: You need appropriate permissions to view documents in your instance.

​
Basic Usage

import requests
import os

api_key = os.getenv("PARADIGM_API_KEY")
base_url = os.getenv("PARADIGM_BASE_URL", "https://paradigm.lighton.ai/api/v3")

response = requests.get(
    url=f"{base_url}/files",
    headers={'Authorization': f"Bearer {api_key}"},
)

print(response.json())

​
Response Format

{
  "next": "https://paradigm.lighton.ai/api/v3/files?page=2",
  "previous": null,
  "count": 42,
  "results": [
    {
      "id": 123,
      "filename": "report.pdf",
      "workspace_id": 5,
      "title": "Q4 Financial Report",
      "extension": "pdf",
      "status": "embedded",
      "status_vision": "embedded",
      "uploaded_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z",
      "total_pages": 24
    }
  ]
}

​
Pagination & Limits

  • Page size: 20 documents per page (fixed)
  • max_documents: Total documents to return (1-500, default: 50)
  • page: Navigate through paginated results

​
Available Filters

All filters are documented in the Swagger/OpenAPI specification. Key filters include:
FilterDescription
workspace_idComma-separated workspace IDs
extensionComma-separated file extensions (e.g., pdf,docx)
status, status_visionEmbedding status values (complete value list :
https://paradigm.lighton.ai/api/v3/docs/#/Files/api_v3_files_list )
title, filenamePartial match (case-insensitive)
uploaded_at_after/beforeDate range for upload time
updated_at_after/beforeDate range for last update
total_pages_min/maxPage count range
tag_idComma-separated tag IDs
The search parameter enables intelligent document discovery using hybrid search. When provided, results are ordered by relevance instead of upload date. 
response = requests.get(
    url=f"{base_url}/files",
    headers={'Authorization': f"Bearer {api_key}"},
    params={
        "search": "machine learning best practices",
        "max_documents": 20
    }
)

​
How it Works

The DocFinder service uses a hybrid ranking approach that incorporates both semantic and lexical signals to find and rank relevant documents.
Filters are applied before the search, allowing you to search within a specific subset of documents.

​
cURL

curl --request GET \
  --url "$PARADIGM_BASE_URL/files?search=financial%20report&extension=pdf" \
  --header "Authorization: Bearer $PARADIGM_API_KEY"