---
title: "Upload documents"
method: POST
path: "/projects/{project_id}/documents/"
tags: ["Documents"]
---

# Upload documents

`POST /projects/{project_id}/documents/`

## Request

- Base URL: `https://api.parsewise.ai/api/v1`
- URL: `https://api.parsewise.ai/api/v1/projects/{project_id}/documents/`
- Auth: API key in header `X-API-Key`

Upload one or more documents to the project. Send the files as `multipart/form-data` under the `files` field (repeat the field for multiple files). Successful uploads return `202 Accepted`: the accepted document rows are created immediately and returned in `documents`, while parsing/conversion continues in the background. Excel workbooks produce one document per accepted sheet; email uploads can also produce attachment documents.

## Path parameters

- `project_id` string, uuid, required

## Request body `multipart/form-data`

- V1DocumentUploadRequest
  - `files` string[], required: One or more files to upload. Repeat the `files` field once per file (standard multipart/form-data multi-file upload). Supported types: PDF, Word, Excel, PPT, Image, Email (.eml), and UTF-8 plain text (.txt) or Markdown (.md, .markdown). Text and Markdown are paginated as written, without Markdown formatting; a text file that cannot be read (for example not UTF-8 or empty) is created with status `Failed`.
  - `skip_sheets` string: Optional JSON-encoded object of the form `{"filename.xlsx": [{"name": "Sheet1", "estimatedPages": 1500}, ...]}` listing Excel sheets the caller chose not to upload because they exceeded size limits. Used for logging and quota accounting only; omit if not applicable.

## Response `202`

Files accepted; document rows created; parsing/conversion queued or started.

- V1DocumentUploadResponse
  - `excel_count` integer, required: Number of top-level Excel files accepted for asynchronous sheet-by-sheet processing. `0` when no top-level Excel files were accepted.
  - `files` V1DocumentUploadResponseFile[], required: Compatibility field containing stored file locations for accepted non-Excel upload files. Use `documents` to reconcile uploads with document UUIDs.
    - `file_url` string, uri, required: Stored location of the uploaded file.
    - `file_name` string, required: Original filename of the uploaded file.
  - `documents` V1DocumentUploadResponseDocument[], required: Created document rows. This is the recommended field for reconciling uploads to UUIDs.
    - `id` string, uuid, required: Stable identifier for the created document.
    - `file_name` string, required: Resulting document filename.
    - `source_file_name` string, required: Uploaded file that produced this document.
    - `type` 'PDF' | 'Audio' | 'Image' | 'Text' | 'Excel' | 'PPT' | 'Word Document' | 'Website' | 'Email', required: * `PDF` - PDF * `Audio` - Audio * `Image` - Image * `Text` - Text * `Excel` - Excel * `PPT` - PPT * `Word Document` - Word Document * `Website` - Website * `Email` - Email
    - `status` 'Pending' | 'Processed' | 'Failed', required: * `Pending` - Pending * `Processed` - Processed * `Failed` - Failed
    - `uploaded_at` string, date-time, required: Timestamp when the document row was created.
    - `page_count` integer, required: Number of pages, or 0 until parsing/conversion computes it.
    - `sheet_name` string: Original Excel sheet name when this document was created from a workbook sheet.
    - `parent_document_id` string, uuid: Parent email document UUID when this document came from an email attachment.
    - `parent_file_name` string: Parent email filename when this document came from an email attachment.

---

[API](https://skmtc.dev/parsewise/apis/parsewise-api.md) - [All operations](https://skmtc.dev/parsewise/apis/parsewise-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parsewise/apis/parsewise-api/revisions/5db46512debf?raw)