> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.



## OpenAPI

````yaml /api-reference/openapi-v3.yaml get /api/v3/files
openapi: 3.0.3
info:
  title: Paradigm API
  version: xenial-xerus (v3)
  description: >-
    A versatile and adaptable tool designed to integrate Generative AI into your
    applications
servers:
  - url: https://paradigm.lighton.ai
security: []
tags:
  - name: Agents
    description: Operations about agents
  - name: Threads
    description: Operations about agents conversation threads
  - name: Tools
    description: Operations about native tools
  - name: Models
    description: Operations about AI models
  - name: MCP
    description: Operations about MCP servers
  - name: Sources
    description: Operations about sources used by agents conversation threads
  - name: Artifacts
    description: Operations about artifacts generated by agents conversation threads
  - name: Agent
    description: >-
      Operations about agents (deprecated). Please use the 'Agents' API
      component instead.
  - name: Files
    description: Operations about files
  - name: Files Processing
    description: Operations about files processing
  - name: Tags
    description: Operations about tags
  - name: Workspaces
    description: Operations about workspaces
  - name: Users
    description: Operations about users
  - name: User Groups
    description: Operations about user groups
  - name: Companies
    description: Operations about companies
  - name: SCIM
    description: Operations about SCIM
paths:
  /api/v3/files:
    get:
      tags:
        - Files
      summary: List files accessible to the authenticated user
      description: >-
        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.
      operationId: api_v3_files_list
      parameters:
        - in: query
          name: created_at_after
          schema:
            type: string
            format: date-time
          description: >-
            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)
        - in: query
          name: created_at_before
          schema:
            type: string
            format: date-time
          description: >-
            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)
        - in: query
          name: extension
          schema:
            type: string
          description: >-
            Filter by file extensions (comma-separated, e.g.,
            ?extension=pdf,docx)
        - in: query
          name: external_metadata__doc_type
          schema:
            type: string
          description: >-
            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.
        - in: query
          name: external_metadata__external_id
          schema:
            type: string
          description: >-
            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
        - in: query
          name: filename
          schema:
            type: string
          description: Filter by filename (case-insensitive partial match)
        - in: query
          name: group_id
          schema:
            type: string
          description: Filter by group IDs (comma-separated, e.g., ?group_id=1,2,3)
        - in: query
          name: include_details
          schema:
            type: boolean
          description: >-
            Include detail fields (e.g., TLSH signature for duplicate detection,
            parser/ingestion pipeline). Default: false.
        - in: query
          name: max_documents
          schema:
            type: integer
          description: >-
            Maximum number of documents to return (default: 50, minimum: 1,
            maximum: 500)
        - in: query
          name: ordering
          schema:
            type: string
          description: >-
            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).
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
        - in: query
          name: search
          schema:
            type: string
          description: >-
            Optional semantic search query. When provided, results are ordered
            by relevance.
        - in: query
          name: search_details
          schema:
            type: boolean
          description: >-
            When true (and search is provided), include top relevant chunk(s)
            per document.
        - in: query
          name: search_details_chunks_limit
          schema:
            type: integer
          description: >-
            Max number of relevant chunks to return per document when
            search_details=true (1-10, default: 3).
        - in: query
          name: status
          schema:
            type: string
            enum:
              - embedded
              - embedding
              - embedding_failed
              - fail
              - parsing
              - parsing_failed
              - pending
              - updating
          description: >-
            Filter by status values (comma-separated, e.g.,
            ?status=pending,embedded)
        - in: query
          name: status_vision
          schema:
            type: string
            enum:
              - '-'
              - embedded
              - fail
              - pending
              - processing
          description: >-
            Filter by vision status values (comma-separated, e.g.,
            ?status_vision=pending,embedded)
        - in: query
          name: tag_id
          schema:
            type: string
          description: Filter by tag IDs (comma-separated, e.g., ?tag_id=1,2,3)
        - in: query
          name: title
          schema:
            type: string
          description: Filter by title (case-insensitive partial match)
        - in: query
          name: total_pages_max
          schema:
            type: integer
            maximum: 2147483647
            minimum: -2147483648
            nullable: true
          description: >-
            Filter by total pages range (e.g.,
            ?total_pages_min=10&total_pages_max=50)
        - in: query
          name: total_pages_min
          schema:
            type: integer
            maximum: 2147483647
            minimum: -2147483648
            nullable: true
          description: >-
            Filter by total pages range (e.g.,
            ?total_pages_min=10&total_pages_max=50)
        - in: query
          name: updated_at_after
          schema:
            type: string
            format: date-time
          description: >-
            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)
        - in: query
          name: updated_at_before
          schema:
            type: string
            format: date-time
          description: >-
            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)
        - in: query
          name: upload_session_uuid
          schema:
            type: string
          description: >-
            Filter by upload session UUID (e.g.,
            ?upload_session_uuid=123e4567-e89b-12d3-a456-426614174000)
        - in: query
          name: workspace_id
          schema:
            type: string
          description: Filter by workspace IDs (comma-separated, e.g., ?workspace_id=1,2,3)
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFileListResponseSerializerV3List'
              examples:
                ListOfFiles:
                  value:
                    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
                  summary: List of files
                ListOfFiles(withSearchDetails):
                  value:
                    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: []
                          created_by:
                            id: 42
                            first_name: Jane
                            last_name: Doe
                            username: jdoe
                          external_metadata: null
                          search_details:
                            relevant_chunks:
                              - text: >-
                                  This paragraph is a representative excerpt of
                                  the highest-ranked chunk.
                                metadata:
                                  pages: 12-12
                                  title: Q4 Project Proposal
                                chunk_type: text
                                final_score: 0.0328
                                lexical_score: 0.71
                                distance: 0.18
                  summary: List of files (with search details)
                ListOfFiles(withIncludeDetails=true):
                  value:
                    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: []
                          created_by:
                            id: 42
                            first_name: Jane
                            last_name: Doe
                            username: jdoe
                          signature: >-
                            T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2
                          parser: v2.2.1
                        - 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
                          signature: >-
                            T1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2G3
                          parser: v2.2.1
                  summary: List of files (with include_details=true)
          description: List of files accessible to the authenticated user
        '401':
          description: Authentication failed - missing or invalid API key
        '403':
          description: Permission denied
        '404':
          description: Not found
        '429':
          description: Too many requests - rate limit exceeded
      security:
        - bearerAuth: []
components:
  schemas:
    PaginatedFileListResponseSerializerV3List:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/FileListResponseSerializerV3'
    FileListResponseSerializerV3:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        filename:
          type: string
          readOnly: true
          description: Filename of the document
        workspace:
          allOf:
            - $ref: '#/components/schemas/WorkspaceInFileResponseSerializerV3'
          nullable: true
          readOnly: true
          description: Workspace the document belongs to
        summaries:
          type: array
          items:
            $ref: '#/components/schemas/DocumentSummaryResponse'
          readOnly: true
          description: Document summaries (all languages)
        title:
          type: string
          nullable: true
          maxLength: 255
        extension:
          type: string
          description: File extension of the document
        status:
          $ref: '#/components/schemas/Status88dEnum'
        status_detail:
          type: string
          nullable: true
          description: >-
            Detailed error information. Only present when document processing
            has failed.
        status_vision:
          $ref: '#/components/schemas/StatusVisionEnum'
        created_at:
          type: string
          format: date-time
          description: Creation date of the resource
        updated_at:
          type: string
          format: date-time
          readOnly: true
        total_pages:
          type: integer
          readOnly: true
          description: Total number of pages
        size:
          type: integer
          nullable: true
          readOnly: true
          description: Size of the file in bytes.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagItem'
          readOnly: true
          description: List of tags associated with the document
        created_by:
          allOf:
            - $ref: '#/components/schemas/CreatedBy'
          nullable: true
          readOnly: true
          description: >-
            User who created the file. Null when the file was created by the
            system.
        upload_session_uuid:
          type: string
          format: uuid
          nullable: true
          readOnly: true
          description: Upload session UUID associated with this document
        search_details:
          allOf:
            - $ref: '#/components/schemas/SearchDetails'
          nullable: true
          readOnly: true
          description: Only present when search_details=true and search is provided.
        signature:
          type: string
          nullable: true
          readOnly: true
          description: >-
            TLSH hash for duplicate detection. Only included when
            include_details=true (detail field).
        parser:
          type: string
          nullable: true
          description: >-
            Parser/ingestion pipeline used for document processing (e.g.,
            'v2.1', 'v3.0'). Only included when include_details=true (detail
            field).
        external_metadata:
          allOf:
            - $ref: '#/components/schemas/ExternalMetadata'
          description: External document metadata
      required:
        - created_at
        - created_by
        - extension
        - external_metadata
        - filename
        - id
        - search_details
        - signature
        - size
        - summaries
        - tags
        - total_pages
        - updated_at
        - upload_session_uuid
        - workspace
    WorkspaceInFileResponseSerializerV3:
      type: object
      description: Minimal workspace info for file responses.
      properties:
        id:
          type: integer
          description: Workspace ID
        name:
          type: string
          description: Workspace name
        workspace_type:
          type: string
          description: Workspace type (company, personal, or custom)
      required:
        - id
        - name
        - workspace_type
    DocumentSummaryResponse:
      type: object
      properties:
        language:
          allOf:
            - $ref: '#/components/schemas/DocumentSummaryResponseLanguageEnum'
          description: |-
            Language of the summary.

            * `en` - English
            * `fr` - French
            * `es` - Spanish
            * `it` - Italian
            * `ar` - Arabic
            * `nl` - Dutch
            * `sv` - Swedish
            * `de` - German
            * `ja` - Japanese
            * `zh` - Chinese
            * `ko` - Korean
        summary:
          type: string
          description: Summary of the document.
      required:
        - summary
    Status88dEnum:
      enum:
        - pending
        - parsing
        - parsing_failed
        - embedding
        - embedding_failed
        - embedded
        - fail
        - updating
      type: string
      description: |-
        * `pending` - Pending
        * `parsing` - Parsing
        * `parsing_failed` - Parsing Failed
        * `embedding` - Embedding
        * `embedding_failed` - Embedding Failed
        * `embedded` - Embedded
        * `fail` - Fail
        * `updating` - Updating
    StatusVisionEnum:
      enum:
        - pending
        - processing
        - embedded
        - fail
        - '-'
      type: string
      description: |-
        * `pending` - Pending
        * `processing` - Processing
        * `embedded` - Embedded
        * `fail` - Fail
        * `-` - Not available
    TagItem:
      type: object
      description: Serializer for tag items in file list response.
      properties:
        id:
          type: integer
          description: Tag ID
        name:
          type: string
          description: Tag name
        auto_assigned:
          type: boolean
          description: >-
            True if this tag was automatically assigned by the system, False if
            manually assigned by a user
      required:
        - auto_assigned
        - id
        - name
    CreatedBy:
      type: object
      description: Shallow user object for the file creator.
      properties:
        id:
          type: integer
          description: User ID
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
        username:
          type: string
          description: Username
      required:
        - first_name
        - id
        - last_name
        - username
    SearchDetails:
      type: object
      description: Serializer for search details in file list response.
      properties:
        relevant_chunks:
          type: array
          items:
            $ref: '#/components/schemas/DocumentChunkWithScoreResponse'
          description: Relevant chunks ordered by final_score descending
      required:
        - relevant_chunks
    ExternalMetadata:
      type: object
      properties:
        external_id:
          type: string
          description: External document ID
        doc_type:
          type: string
          description: External document type
        additional_metadata:
          description: Additional metadata associated with the document
      required:
        - additional_metadata
        - doc_type
        - external_id
    DocumentSummaryResponseLanguageEnum:
      enum:
        - en
        - fr
        - es
        - it
        - ar
        - nl
        - sv
        - de
        - ja
        - zh
        - ko
      type: string
      description: |-
        * `en` - English
        * `fr` - French
        * `es` - Spanish
        * `it` - Italian
        * `ar` - Arabic
        * `nl` - Dutch
        * `sv` - Swedish
        * `de` - German
        * `ja` - Japanese
        * `zh` - Chinese
        * `ko` - Korean
    DocumentChunkWithScoreResponse:
      type: object
      description: >-
        Minimal chunk payload for "credibility snippet" UI.


        Intentionally omits technical/audit fields such as
        uuid/content_id/document/created_at/updated_at.
      properties:
        text:
          type: string
          description: Chunk text content
        chunk_type:
          type: string
          description: Chunk type (e.g. text/table)
        final_score:
          type: number
          format: double
          description: Final chunk score used for ranking (higher is better)
        lexical_score:
          type: number
          format: double
          nullable: true
          description: Lexical score from hybrid search (higher is better)
        distance:
          type: number
          format: double
          nullable: true
          description: Vector distance from hybrid search (lower is better)
      required:
        - final_score
        - text
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your auth token.

````