> ## 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 scoped to an agent

> 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/agents/{id}/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/agents/{id}/files:
    get:
      tags:
        - Agents
      summary: List files scoped to an agent
      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_agents_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: array
            items:
              type: string
          description: >-
            Filter by file extensions (comma-separated, e.g.,
            ?extension=pdf,docx)
          explode: false
          style: form
        - in: query
          name: external_metadata__doc_type
          schema:
            type: string
          description: >-
            Filter by external document type (case-insensitive partial match,
            e.g., ?external_metadata__doc_type=gitlab)
        - in: query
          name: external_metadata__external_id
          schema:
            type: string
          description: >-
            Filter by external document ID (exact match, e.g.,
            ?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: array
            items:
              type: integer
          description: Filter by user group IDs (comma-separated, e.g., ?group_id=1,2,3)
          explode: false
          style: form
        - in: path
          name: id
          schema:
            type: integer
          required: true
        - name: ordering
          required: false
          in: query
          description: Which field to use when ordering the results.
          schema:
            type: string
        - 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: status
          schema:
            type: array
            items:
              type: string
          description: >-
            Filter by status values (comma-separated, e.g.,
            ?status=pending,embedded)
          explode: false
          style: form
        - in: query
          name: status_vision
          schema:
            type: array
            items:
              type: string
          description: >-
            Filter by vision status values (comma-separated, e.g.,
            ?status_vision=pending,embedded)
          explode: false
          style: form
        - in: query
          name: tag_id
          schema:
            type: array
            items:
              type: integer
          description: Filter by tag IDs (comma-separated, e.g., ?tags=1,2,3)
          explode: false
          style: form
        - 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: array
            items:
              type: integer
          description: Filter by workspace IDs (comma-separated, e.g., ?workspace_id=1,2,3)
          explode: false
          style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFileListResponseSerializerV3List'
          description: ''
      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.

````