---
title: "Upload a file"
method: POST
path: "/api/v3/files"
tags: ["Files"]
---

# Upload a file

`POST /api/v3/files`

Upload a file to a workspace.

Files are added to an upload session and queued for asynchronous processing. To track progress, retrieve the file details using the GET endpoints to check the current status.

**Idempotent upload:** When `external_metadata.external_id` is provided and a manually-uploaded document with the same external ID already exists in the target workspace, the existing document is returned with `200 OK` instead of creating a duplicate. This makes bulk re-runs safe without requiring a pre-check. Datasource-imported documents are not affected.

**Accepted file formats:** `csv`, `doc`, `docx`, `htm`, `html`, `jpeg`, `jpg`, `md`, `odp`, `odt`, `pdf`, `png`, `ppt`, `pptx`, `txt`, `xhtml`, `xls`, `xlsx`

**Customization Options:**
- `title`: Customize the document title (defaults to filename without extension)
- `filename`: Override the uploaded filename
- `parser`: Specify a custom ingestion pipeline instead of using the default

## Response `200`

Document already exists (idempotent). Returned when `external_metadata.external_id` matches a manually-uploaded document in the same workspace. The existing document is returned without creating a duplicate.

- FileCreateResponseSerializerV3
  - `id` integer, required
  - `filename` string, required — Filename of the document
  - `workspace` WorkspaceInFileResponseSerializerV3, required — Minimal workspace info for file responses.
    - `id` integer, required — Workspace ID
    - `name` string, required — Workspace name
    - `workspace_type` string, required — Workspace type (shared or personal)
  - `summaries` DocumentSummaryResponse[], required — Document summaries (all languages)
    - `language` 'en' | 'fr' | 'es' | 'it' | 'ar' | 'nl' | 'sv' | 'de' | 'ja' | 'zh' | 'ko' — * `en` - English * `fr` - French * `es` - Spanish * `it` - Italian * `ar` - Arabic * `nl` - Dutch * `sv` - Swedish * `de` - German * `ja` - Japanese * `zh` - Chinese * `ko` - Korean
    - `summary` string, required — Summary of the document.
  - `title` string, nullable
  - `extension` string, required — File extension of the document
  - `status` 'pending' | 'pending_conversion' | 'converting' | 'parsing' | 'parsing_failed' | 'embedding' | 'embedding_failed' | 'embedded' | 'parsed' | 'fail' | 'updating' — * `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
  - `status_vision` 'pending' | 'processing' | 'embedded' | 'fail' | '-' — * `pending` - Pending * `processing` - Processing * `embedded` - Embedded * `fail` - Fail * `-` - Not available
  - `created_at` string, date-time, required — Creation date of the resource
  - `updated_at` string, date-time, required
  - `total_pages` integer, required — Total number of pages
  - `tags` TagItem[], required — List of tags associated with the document
    - `id` integer, required — Tag ID
    - `name` string, required — Tag name
    - `auto_assigned` boolean, required — True if this tag was automatically assigned by the system, False if manually assigned by a user
  - `created_by` CreatedBy, required — Shallow user object for the file creator.
    - `id` integer, required — User ID
    - `first_name` string, required — First name
    - `last_name` string, required — Last name
    - `username` string, required — Username
  - `upload_session_uuid` string, uuid, nullable, required — Upload session UUID associated with this document
  - `external_metadata` ExternalMetadataResponse, required
    - `external_id` string, required — External document ID
    - `doc_type` string, required — External document type
    - `additional_metadata` unknown, required
  - `message` string, required — Status message about the file upload

## Other responses

- `201` — File queued for processing successfully
- `207` — Document uploaded but tag assignment failed (partial success)
- `400` — Validation error
- `401` — Authentication credentials were not provided
- `403` — You do not have permission to perform this action
- `429` — Too many concurrent uploads for this session

---

[API](https://skmtc.net/lighton/apis/lighton-api.md) · [All operations](https://skmtc.net/lighton/apis/lighton-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lighton/lighton-api/versions/86c57e94ef15/schema)