> ## 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. **Public datasets:** instance admins (holding `MANAGE_PUBLIC_DATASET`) always see public-dataset files. A company that has opted in (`allow_access_to_public_datasets`) with a workspace-scoped API key granting a public workspace also sees its files — filter with `workspace_id` to scope the list to it. ## OpenAPI ````yaml /api-reference/openapi-v3.yaml get /api/v3/agents/{id}/files openapi: 3.1.0 info: title: LightOn API version: 3.15.0 (v3) description: >- LightOn gives you an API to search, parse, and ingest documents at scale. Build knowledge-retrieval pipelines without managing vector databases or OCR models. 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: Facets description: Operations about facets - name: Tags description: Operations about tags - name: Workspaces description: Operations about workspaces - name: Files Processing description: Operations about files processing - name: Users description: Operations about users - name: API Keys description: Operations about API keys - name: User Groups description: Operations about user groups - 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. **Public datasets:** instance admins (holding `MANAGE_PUBLIC_DATASET`) always see public-dataset files. A company that has opted in (`allow_access_to_public_datasets`) with a workspace-scoped API key granting a public workspace also sees its files — filter with `workspace_id` to scope the list to it. 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: items: type: string type: array 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 - in: query name: owner_id schema: type: array items: type: integer description: Filter by owner user IDs (comma-separated, e.g., ?owner_id=1,2,3) explode: false style: form - 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: items: type: string type: array description: >- Filter by status values (comma-separated, e.g., ?status=pending,embedded) explode: false style: form - in: query name: status_vision schema: items: type: string type: array 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 - 'null' maximum: 2147483647 minimum: -2147483648 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 - 'null' maximum: 2147483647 minimum: -2147483648 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: '' '503': description: >- API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' 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' ServiceMaintenance503: type: object description: >- Returned by the maintenance middleware when the requested endpoint is blocked. required: - detail - error - mode properties: detail: type: string example: System is under maintenance. error: type: string example: service_maintenance mode: type: string enum: - full_shutdown - warning_banner description: >- `full_shutdown` blocks all traffic; `warning_banner` also blocks and shows a dismissible toast. reason: type: string description: Operator-supplied maintenance reason, if any. started_at: type: string format: date-time endpoint_category_names: type: array items: type: string description: >- Non-empty only for category-scoped periods. Empty means all endpoints are affected. FileListResponseSerializerV3: type: object properties: id: type: integer readOnly: true filename: type: string readOnly: true description: Filename of the document workspace: oneOf: - $ref: '#/components/schemas/WorkspaceInFileResponseSerializerV3' - type: 'null' 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 - 'null' maxLength: 255 extension: type: string description: File extension of the document status: $ref: '#/components/schemas/DocumentStatusEnum' status_detail: type: - string - 'null' 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 - 'null' 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: oneOf: - $ref: '#/components/schemas/CreatedBy' - type: 'null' readOnly: true description: >- User who created the file. Null when the file was created by the system. upload_session_uuid: type: - string - 'null' format: uuid readOnly: true description: Upload session UUID associated with this document search_details: oneOf: - $ref: '#/components/schemas/SearchDetails' - type: 'null' readOnly: true description: Only present when search_details=true and search is provided. signature: type: - string - 'null' readOnly: true description: >- TLSH hash for duplicate detection. Only included when include_details=true (detail field). parser: type: - string - 'null' description: >- Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0'). Only included when include_details=true (detail field). external_metadata: oneOf: - $ref: '#/components/schemas/ExternalMetadataResponse' - type: 'null' description: External document metadata content_types: type: array items: $ref: '#/components/schemas/DocumentFacetCompactSchema' readOnly: true description: >- Facet content types with nested attribute values. Excludable via ?exclude=content_types. thumbnail: allOf: - $ref: '#/components/schemas/ThumbnailResponse' readOnly: true description: Thumbnail preview of the document (256x256 WebP). required: - content_types - created_at - created_by - extension - filename - id - tags - thumbnail - 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 (shared or personal) 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 DocumentStatusEnum: enum: - pending - pending_conversion - converting - parsing - parsing_failed - embedding - embedding_failed - embedded - parsed - fail - updating type: string description: |- * `pending` - Pending * `pending_conversion` - Pending Conversion * `converting` - Converting * `parsing` - Parsing * `parsing_failed` - Parsing Failed * `embedding` - Embedding * `embedding_failed` - Embedding Failed * `embedded` - Embedded * `parsed` - Parsed * `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/RelevantChunkScoredV3' description: Relevant chunks ordered by score descending required: - relevant_chunks ExternalMetadataResponse: 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 DocumentFacetCompactSchema: type: object description: >- OpenAPI schema for compact content type response (Tier 1 — list default). properties: path: type: string description: Colon-separated content type path (e.g. legal:contract:nda) label: type: string description: User-readable label (leaf node) attribute_values: type: object additionalProperties: $ref: '#/components/schemas/DocumentFacetAttributeValueSchema' description: >- Map of attribute name to {value, type}. Only present when include_details=true. required: - label - path ThumbnailResponse: type: object description: Thumbnail status and URL for file responses. properties: status: allOf: - $ref: '#/components/schemas/ThumbnailResponseStatusEnum' description: >- Thumbnail generation status: MISSING (not available), PROCESSING (being generated), READY (available) * `MISSING` - MISSING * `PROCESSING` - PROCESSING * `READY` - READY url: type: - string - 'null' description: >- Relative URL to the thumbnail image (WebP, 256x256). Null when status is not READY. required: - status - url 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 RelevantChunkScoredV3: type: object description: >- Relevant chunk with the unified scoring shape, aligned with /api/v3/search. Exposes ``score`` + ``scores`` (text/vision/keyword/multivector/relevance) instead of the legacy final_score/lexical_score/distance. ``scores.relevance`` is always null on this path — no relevance scoring runs on file search. properties: text: type: string description: Chunk text content chunk_type: type: string description: Chunk type (e.g. text/table) score: type: number format: double readOnly: true description: >- Combined retrieval score (higher is better, no fixed upper bound). No relevance scoring runs on file search. scores: allOf: - $ref: '#/components/schemas/_ChunkScoresSchema' readOnly: true required: - score - scores - text DocumentFacetAttributeValueSchema: type: object description: OpenAPI schema for a compact attribute value entry. properties: value: description: Attribute value (type depends on attribute definition) type: type: string description: Attribute type (text, number, date, boolean, select, multi_select) label: type: string description: User-readable attribute label (present when include_details=true) required: - type - value ThumbnailResponseStatusEnum: enum: - MISSING - PROCESSING - READY type: string description: |- * `MISSING` - MISSING * `PROCESSING` - PROCESSING * `READY` - READY _ChunkScoresSchema: type: object description: >- Per-signal score breakdown. Schema for OpenAPI; higher is better; null = not computed. ``text``/``vision`` are 0–1 similarities; ``keyword`` and ``multivector`` are unbounded (higher is better). Same shape as /api/v3/search and /retrieve. ``relevance`` is always null on the file-search path — no relevance scoring runs on this endpoint. Defined locally to avoid a circular import with the /retrieve serializer module. properties: text: type: - number - 'null' format: double description: >- Semantic text similarity (0–1, higher is better). Null in vision mode. vision: type: - number - 'null' format: double description: >- Vision page similarity (0–1, higher is better). Null when the document has no vision index. keyword: type: - number - 'null' format: double description: >- Keyword match score (higher is better, no fixed upper bound). Null in vision mode. multivector: type: - number - 'null' format: double description: >- Token-level similarity score (higher is better, no fixed upper bound). Null when multi-vector scoring is disabled. relevance: type: - number - 'null' format: double description: >- Relevance score (0–1, higher is better). Always null on file search — no relevance scoring runs on this endpoint. required: - keyword - multivector - relevance - text - vision securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````