> ## Documentation Index > Fetch the complete documentation index at: https://developers.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update file metadata or replace its file > Update mutable fields of a file (document). **Updatable fields:** - `title`: Update the document title - `tags`: Replace ALL tags for the document (both manual and auto-assigned) - `external_metadata`: Create or update external source metadata - `file`: Replace the original file and re-ingest the document **Tag replacement behavior:** - Providing a tags array replaces ALL existing tags (manual and auto-assigned) - To remove all tags, send `[0]` (sentinel value for multipart format) - Omitting `tags` field leaves tags unchanged - New tags are marked as manually assigned (`auto_assigned=False`) **External metadata behavior:** - When creating for the first time, `external_id` is required - When updating existing metadata, `external_id` is optional (existing value is preserved) - Fields in `additional_metadata` are merged (not replaced) with existing values - `external_id` cannot be changed on a document imported from a datasource: the sync matches its documents on it, so a rename would detach the document from its source. `doc_type` and `additional_metadata` stay editable **File replacement behavior:** - The document keeps its `id`, `title`, manually assigned tags, content types, attribute values and external metadata. Only the file and everything derived from it (text, chunks, embeddings, auto-assigned tags, summaries) are rebuilt. - Any supported file type is accepted, including one that differs from the current file — the processing statuses are re-derived from the new file. - Replacing the file additionally requires an owner or editor role in the document's workspace, and is not available in workspaces configured for synced documents. - The storage quota is checked on the size difference, not the full new size. - `file` can be combined with `title`, `tags` and `external_metadata` in the same request: the metadata changes apply immediately, the file is queued. - The response reflects the document as it still is: `filename`, `extension`, `size`, `total_pages`, `status`, `signature`, `summaries` and `content` describe the previous file until re-ingestion begins. The document keeps serving its previous content — search, extracts and download stay consistent — and leaves the search index only once processing actually starts. - `pending_reprocess` is set to `update` on the response and on subsequent reads, and is the only signal that the queued file has not been processed yet: `status` still reports the previous run's outcome (typically `Embedded`) until the pipeline picks the document up. Poll until `pending_reprocess` is null **and** `status` is terminal — treating a terminal `status` alone as completion reports success against the previous file. - Sending a new file while one is already queued replaces the queued file, and a file replacement supersedes any other reprocessing already queued for the document: the most recent request is always the one that goes live. - Once re-ingestion starts, a document whose new file needs rendering has no rendered PDF until conversion completes. `download?purpose=rendered_pdf` serves the original during that window, as it does for any file still being converted, so a viewer can receive a non-PDF body. Gate the viewer on `status` rather than on the download succeeding. - The request is applied in full or not at all: tags are validated before the file is queued, so an invalid tag id rejects the whole request without staging anything. **Public datasets:** editing a public-dataset file requires the instance-admin `MANAGE_PUBLIC_DATASET` permission. A workspace-scoped API key with read access (company opted in via `allow_access_to_public_datasets`) can see a public-dataset file but is refused permission to edit it — public datasets are read-only. ## OpenAPI ````yaml /api-reference/api-console.yaml patch /api/v3/files/{id} openapi: 3.1.0 info: title: LightOn API version: 3.15.0 (v1) 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://api.lighton.ai security: [] tags: - name: Ask description: >- Retrieval-augmented generation: search your indexed corpus and generate an LLM answer grounded in the retrieved passages. Supports streaming (SSE) and synchronous modes. - name: Search description: >- Hybrid vector + text retrieval over your indexed corpus. Returns ranked passages with provenance (file, page range, workspace). Optional reranking and vision mode. - name: Files description: Upload, list, fetch, and delete documents indexed in your workspaces. - name: Facets description: >- Organise documents with hierarchical content types and custom attributes per file. Start from starter templates or build your own classification schema from scratch. - name: Tags description: >- Manage flat, company-wide labels used to scope search and group content across workspaces. - name: Workspaces description: >- Create and manage workspaces — the access-controlled containers your documents live in. - name: Parse description: >- Convert documents into structured Markdown — PDFs, images, Office files, and HTML. Synchronous endpoint capped at 20 MB / 15 pages. - name: Extract description: >- Pull typed fields out of documents using a JSON Schema you provide. Sync mode for small documents (≤20 MB / 15 pages); async mode for larger jobs (≤100 MB / 1000 pages) with polling on a job ID. - name: API Keys description: >- Provision and revoke API keys used to authenticate against the Console API. - name: Budget description: >- Manage your organization's monthly spend budget and alert thresholds. Set a hard cap that blocks API requests when reached, and configure email notifications at custom spend percentages. paths: /api/v3/files/{id}: patch: tags: - Files summary: Update file metadata or replace its file description: > Update mutable fields of a file (document). **Updatable fields:** - `title`: Update the document title - `tags`: Replace ALL tags for the document (both manual and auto-assigned) - `external_metadata`: Create or update external source metadata - `file`: Replace the original file and re-ingest the document **Tag replacement behavior:** - Providing a tags array replaces ALL existing tags (manual and auto-assigned) - To remove all tags, send `[0]` (sentinel value for multipart format) - Omitting `tags` field leaves tags unchanged - New tags are marked as manually assigned (`auto_assigned=False`) **External metadata behavior:** - When creating for the first time, `external_id` is required - When updating existing metadata, `external_id` is optional (existing value is preserved) - Fields in `additional_metadata` are merged (not replaced) with existing values - `external_id` cannot be changed on a document imported from a datasource: the sync matches its documents on it, so a rename would detach the document from its source. `doc_type` and `additional_metadata` stay editable **File replacement behavior:** - The document keeps its `id`, `title`, manually assigned tags, content types, attribute values and external metadata. Only the file and everything derived from it (text, chunks, embeddings, auto-assigned tags, summaries) are rebuilt. - Any supported file type is accepted, including one that differs from the current file — the processing statuses are re-derived from the new file. - Replacing the file additionally requires an owner or editor role in the document's workspace, and is not available in workspaces configured for synced documents. - The storage quota is checked on the size difference, not the full new size. - `file` can be combined with `title`, `tags` and `external_metadata` in the same request: the metadata changes apply immediately, the file is queued. - The response reflects the document as it still is: `filename`, `extension`, `size`, `total_pages`, `status`, `signature`, `summaries` and `content` describe the previous file until re-ingestion begins. The document keeps serving its previous content — search, extracts and download stay consistent — and leaves the search index only once processing actually starts. - `pending_reprocess` is set to `update` on the response and on subsequent reads, and is the only signal that the queued file has not been processed yet: `status` still reports the previous run's outcome (typically `Embedded`) until the pipeline picks the document up. Poll until `pending_reprocess` is null **and** `status` is terminal — treating a terminal `status` alone as completion reports success against the previous file. - Sending a new file while one is already queued replaces the queued file, and a file replacement supersedes any other reprocessing already queued for the document: the most recent request is always the one that goes live. - Once re-ingestion starts, a document whose new file needs rendering has no rendered PDF until conversion completes. `download?purpose=rendered_pdf` serves the original during that window, as it does for any file still being converted, so a viewer can receive a non-PDF body. Gate the viewer on `status` rather than on the download succeeding. - The request is applied in full or not at all: tags are validated before the file is queued, so an invalid tag id rejects the whole request without staging anything. **Public datasets:** editing a public-dataset file requires the instance-admin `MANAGE_PUBLIC_DATASET` permission. A workspace-scoped API key with read access (company opted in via `allow_access_to_public_datasets`) can see a public-dataset file but is refused permission to edit it — public datasets are read-only. operationId: api_v3_files_partial_update parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this Document. required: true requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/PatchedFileUpdateRequestSerializerV3' examples: UpdateTitleOnly: value: title: Updated Document Title summary: Update title only description: Update only the document title ReplaceAllTags: value: tags: - 1 - 2 summary: Replace all tags description: >- Replace all existing tags (both manual and auto-assigned) with new ones. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. RemoveAllTags: value: tags: - 0 summary: Remove all tags description: Remove all tags using sentinel value [0] CreateExternalMetadata: value: external_metadata: external_id: gitlab-issue-456 doc_type: gitlab_issue additional_metadata: external_url: https://gitlab.example.com/project/-/issues/456 name: Fix authentication bug summary: Create external metadata description: >- Attach external source metadata to a document that has none yet. `external_id` is required for creation. `external_metadata` must be sent as a JSON string when using multipart/form-data. UpdateExistingExternalMetadata: value: external_metadata: additional_metadata: last_synced_at: '2024-01-15T10:00:00Z' name: Updated Name summary: Update existing external metadata description: >- Update fields on an existing external metadata record. `external_id` is optional when a record already exists — it will be preserved if omitted. Fields inside `additional_metadata` are merged with existing values, not replaced. ReplaceTheFile: value: file: (binary file data) summary: Replace the file description: >- Send a new original as the `file` part of a multipart request. The document keeps its id, title, manual tags, facets and external metadata, and is re-ingested from the new content. Until re-ingestion begins it still serves its previous file. ReplaceTheFileAndRenameTheDocument: value: file: (binary file data) title: Q4 Report (revised) summary: Replace the file and rename the document description: >- Metadata changes apply immediately; the file is queued for re-ingestion. The document `title` is only ever changed when explicitly provided — it never follows the new file's name. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedFileUpdateRequestSerializerV3' examples: UpdateTitleOnly: value: title: Updated Document Title summary: Update title only description: Update only the document title ReplaceAllTags: value: tags: - 1 - 2 summary: Replace all tags description: >- Replace all existing tags (both manual and auto-assigned) with new ones. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. RemoveAllTags: value: tags: - 0 summary: Remove all tags description: Remove all tags using sentinel value [0] CreateExternalMetadata: value: external_metadata: external_id: gitlab-issue-456 doc_type: gitlab_issue additional_metadata: external_url: https://gitlab.example.com/project/-/issues/456 name: Fix authentication bug summary: Create external metadata description: >- Attach external source metadata to a document that has none yet. `external_id` is required for creation. `external_metadata` must be sent as a JSON string when using multipart/form-data. UpdateExistingExternalMetadata: value: external_metadata: additional_metadata: last_synced_at: '2024-01-15T10:00:00Z' name: Updated Name summary: Update existing external metadata description: >- Update fields on an existing external metadata record. `external_id` is optional when a record already exists — it will be preserved if omitted. Fields inside `additional_metadata` are merged with existing values, not replaced. ReplaceTheFile: value: file: (binary file data) summary: Replace the file description: >- Send a new original as the `file` part of a multipart request. The document keeps its id, title, manual tags, facets and external metadata, and is re-ingested from the new content. Until re-ingestion begins it still serves its previous file. ReplaceTheFileAndRenameTheDocument: value: file: (binary file data) title: Q4 Report (revised) summary: Replace the file and rename the document description: >- Metadata changes apply immediately; the file is queued for re-ingestion. The document `title` is only ever changed when explicitly provided — it never follows the new file's name. responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileRetrieveResponseSerializerV3' examples: FileUpdatedSuccessfully: value: id: 123 filename: project_proposal.pdf workspace: id: 1 name: Engineering Team summaries: - language: en summary: This document outlines Q4 initiatives... title: Updated Document Title extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:45:00Z' total_pages: 25 size: 2458624 tags: - id: 1 name: Compliance auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: >- T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 parser: v2.2.1 external_metadata: null content_types: - code: design-doc path: tech:specification:design-doc label: Design Document breadcrumb: - code: tech path: tech label: Tech - code: specification path: tech:specification label: Specification - code: design-doc path: tech:specification:design-doc label: Design Document attribute_values: owner_team: value: Platform Engineering type: text attribute: name: owner_team label: Owner Team type: text required: true maturity: value: Approved type: select attribute: name: maturity label: Maturity type: select required: false choices: - Draft - Review - Approved component: value: Document Retrieval Service type: text attribute: name: component label: Component type: text required: false pending_reprocess: null summary: File updated successfully FileReplacementQueued: value: id: 123 filename: project_proposal.pdf workspace: id: 1 name: Engineering Team summaries: - language: en summary: This document outlines Q4 initiatives... title: Project Proposal extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:45:00Z' total_pages: 25 size: 2458624 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe external_metadata: null content_types: - code: annual-report path: finance:reporting:annual-report label: Annual Report breadcrumb: - code: finance path: finance label: Finance - code: reporting path: finance:reporting label: Reporting - code: annual-report path: finance:reporting:annual-report label: Annual Report attribute_values: fiscal_year: value: 2024 type: number attribute: name: fiscal_year label: Fiscal Year type: number required: true entity: value: LightOn SA type: text attribute: name: entity label: Entity type: text required: false pending_reprocess: update summary: File replacement queued description: >- A request including `file`. Every file-derived field still describes the previous file — `pending_reprocess: update` is what says the new one has not been processed yet. Classification survives the replacement: `content_types` and their attribute values are returned unchanged. FileUpdatedWithExternalMetadata: value: id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team summaries: [] title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:45:00Z' total_pages: 3 size: 102400 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: >- T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 external_metadata: external_id: legal-doc-456789 doc_type: nda additional_metadata: external_url: https://contracts.example.com/legal/customer-nda last_synced_at: '2024-01-15T10:00:00Z' content_types: - code: nda path: legal:contract:nda label: Non-Disclosure Agreement breadcrumb: - code: legal path: legal label: Legal - code: contract path: legal:contract label: Contract - code: nda path: legal:contract:nda label: Non-Disclosure Agreement attribute_values: jurisdiction: value: - FR - US type: multi-select attribute: name: jurisdiction label: Jurisdiction type: multi-select required: true choices: - FR - US - UK - DE confidentiality_level: value: Confidential type: select attribute: name: confidentiality_level label: Confidentiality Level type: select required: false choices: - Public - Internal - Confidential counterparty: value: Nimbus Labs type: text attribute: name: counterparty label: Counterparty type: text required: false is_mutual: value: true type: boolean attribute: name: is_mutual label: Is Mutual type: boolean required: false pending_reprocess: null summary: File updated with external metadata description: File updated successfully '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: StorageQuotaExceeded: value: id: null code: 400 error: STORAGE_LIMIT_REACHED detail: >- The custom workspace storage limit for your company is 10240 MB and you are currently using 10230.5 MB. Delete stale documents or ask your company admin to request an increase of your storage quota. doc_url: https://developers.lighton.ai/errors#bad_request summary: Storage quota exceeded description: >- Domain rules rejected the update: the workspace only accepts synced documents, the company storage quota does not cover the size increase, or the request changes the `external_id` of a datasource-imported document. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: >- Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' description: >- Editing is not permitted, or — when replacing the file — the caller has no owner/editor role in the document's workspace. '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '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: PatchedFileUpdateRequestSerializerV3: type: object description: >- Request serializer for PATCH /api/v3/files/{id} endpoint. Allows partial updates to mutable document fields: - title: Update the document title - tags: Replace ALL tags for the document (both manual and auto-assigned) - external_metadata: Create or update external source metadata - file: Replace the original file and re-ingest (document keeps its id) Immutable fields (if provided, will return 400): - filename, workspace_id, parser, etc. properties: file: type: string format: uri description: >- New original file. The document is re-ingested from the new content. Any supported file type is accepted, including one that differs from the current file. Until re-ingestion starts the document still serves its previous content. title: type: string description: Updated title for the document. maxLength: 255 tags: type: array items: type: integer description: >- List of tag IDs to replace ALL existing tags (both manual and auto-assigned). To remove all tags when using multipart format, send [0] as the sentinel value. external_metadata: oneOf: - $ref: '#/components/schemas/ExternalMetadataRequest' - type: 'null' description: >- External source metadata to create or update. `external_id` is required when no external metadata record exists yet. Fields in `additional_metadata` are merged (not replaced) with existing values. FileRetrieveResponseSerializerV3: 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_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 signature: type: - string - 'null' readOnly: true description: TLSH hash for duplicate detection. content: type: - string - 'null' deprecated: true readOnly: true description: >- Deprecated — use `pages[]` instead. Full text content of the document, derived from per-page text, as a single flat string. Only included when include_content=true query parameter is provided. Will be removed in a future release. pages: type: array items: $ref: '#/components/schemas/Page' readOnly: true description: >- Per-page document text in the canonical `{ index, markdown }` shape shared with /parse and /ocr. Only included when include_content=true. Intended replacement for the flat `content` string. For documents ingested before per-page text was stored, the full `content` is returned as a single page (index 1); empty only when there is no content at all. status_detail: type: - string - 'null' description: >- Detailed error information. Only present when document processing has failed. parser: type: - string - 'null' description: >- Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0'). 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). pending_reprocess: description: >- The reprocessing level queued for this document, or null when none is. Non-null means work has been accepted but has not started yet — `status` and `status_vision` still describe the previous run. It clears the moment processing starts, from which point the statuses track the new run. `update` (a file replacement) additionally leaves the file-derived fields (`filename`, `extension`, `size`, `total_pages`, `signature`, `summaries`, `content`) describing the previous file until then. readOnly: true oneOf: - $ref: '#/components/schemas/PendingReprocessEnum' - $ref: '#/components/schemas/NullEnum' required: - content_types - created_at - created_by - extension - filename - id - pending_reprocess - signature - summaries - tags - thumbnail - total_pages - updated_at - upload_session_uuid - workspace APIV3ErrorResponse: type: object properties: id: type: - string - 'null' description: >- Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page required: - code - detail - doc_url - error - id APIV3ValidationErrorResponse: type: object properties: id: type: - string - 'null' description: >- Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page fields: type: object additionalProperties: type: array items: $ref: '#/components/schemas/APIV3FieldError' description: Field-level validation errors keyed by field name required: - code - detail - doc_url - error - id 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. ExternalMetadataRequest: type: object description: >- Validates external document metadata for V3 file endpoints. All fields are optional to support both creation (where doc_id is typically required - validated at the view level) and partial updates (all optional). properties: external_id: type: string description: >- External document ID in the source system. Required when creating external metadata for the first time. doc_type: type: string description: External document type (e.g. 'incident', 'page') additional_metadata: description: >- Arbitrary JSON object with extra information about the document (e.g. URL, version, timestamps). Passed through as-is. 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/LanguageEnum' 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 Page: type: object description: >- Canonical per-page document text object. Originates with /parse and is reused by /ocr and /files (the latter imports it from here) so a client can switch between live parsing and reading an already-ingested file without reshaping page data. Defined once and reused everywhere — never redefine this shape per app. Extensible: future per-page fields (tables, images, confidence, ...) can be added here without breaking callers that only consume ``index`` + ``markdown``. properties: index: type: integer description: Page number within the document (1-based). markdown: type: string description: Page text rendered as Markdown. required: - index - markdown 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 PendingReprocessEnum: enum: - reparse - rechunk - reembed - reembed_vision - update type: string NullEnum: type: 'null' APIV3FieldError: type: object properties: error: type: string description: Error code / translation key detail: type: string description: Human-readable description of the field error required: - detail - error LanguageEnum: 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 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 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````