> This page is for version v2025-04-21.
> For other versions, use one of these documentation indexes:
> - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt
> - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt
> - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.ai/llms.txt
> Use this file to discover all available pages before exploring further.
>
> ## API version
> The current API version is `2026-02-09`, served at the site root (no version prefix in URLs).
> If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version.
> Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version.
> Do not treat older-version pages as the source of truth for new integrations.

# Upload File

POST https://api.extend.ai/files/upload
Content-Type: multipart/form-data

Upload and create a new file in Extend.

This endpoint accepts file contents and registers them as a File in Extend, which can be used for [running workflows](https://docs.extend.ai/2025-04-21/developers/api-reference/workflow-endpoints/run-workflow), [creating evaluation set items](https://docs.extend.ai/2025-04-21/developers/api-reference/evaluation-set-endpoints/bulk-create-evaluation-set-items), [parsing](https://docs.extend.ai/2025-04-21/developers/api-reference/parse-endpoints/parse-file), etc.

If an uploaded file is detected as a Word or PowerPoint document, it will be automatically converted to a PDF.

Supported file types can be found [here](https://docs.extend.ai/2025-04-21/product/general/supported-file-types).

This endpoint requires multipart form encoding. Most HTTP clients will handle this encoding automatically (see the examples).


Reference: https://docs.extend.ai/2025-04-21/developers/api-reference/file-endpoints/upload-file

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Query parameters

- `convertToPdf` (boolean, optional, default: false) — When true, converts the uploaded file to PDF. Supported file types include images (JPEG, PNG, TIFF, GIF, BMP, WebP, HEIC/HEIF), Word documents, PowerPoint, Excel, and HTML.

### Headers

- `x-extend-api-version` ("2025-04-21", optional, default: 2025-04-21) — API version to use for the request. If you do not specify a version, you will either receive a `400 Bad Request` or be set to a previous legacy version. See [API Versioning](https://docs.extend.ai/2025-04-21/developers/api-versioning) for more details.
- `x-extend-workspace-id` (string, optional) — The workspace ID to target. **Required** when using an organization-scoped API key; optional for workspace-scoped keys (the key is already tied to a workspace). See [Authentication](https://docs.extend.ai/2025-04-21/developers/authentication) for details on API key scopes.

### Body (multipart/form-data)

This endpoint expects a multipart form containing a file.

- `file` (file, required) — The file contents to upload

## Response

### 200

Successfully uploaded file

- `success` (boolean, required)
- `file` (File, required)

## Errors

### 400 Bad Request Error

Bad Request

- `success` (boolean, optional)
- `error` (string, optional) — Error message
- `code` (enum, optional)
  - Allowed values: `FILE_TYPE_NOT_SUPPORTED`, `FILE_SIZE_TOO_LARGE`, `CORRUPT_FILE`, `PASSWORD_PROTECTED_FILE`

### 401 Unauthorized Error

Unauthorized

- `success` (boolean, optional)
- `error` (string, optional) — Error message

## Types

### File

- `object` (string, required) — The type of response. In this case, it will always be "file".
- `id` (string, required) — Extend's internal ID for the file. It will always start with `"file_"`. Example: `"file_xK9mLPqRtN3vS8wF5hB2cQ"`
- `name` (string, required) — The name of the file Example: `"Invoices.pdf"`
- `metadata` (FileMetadata, required)
- `createdAt` (string, required) — The time (in UTC) at which the file was created. Will follow the RFC 3339 format. Example: `"2024-03-21T15:30:00Z"`
- `updatedAt` (string, required) — The time (in UTC) at which the file was last updated. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`
- `type` (enum, optional) — The type of the file
  - Allowed values: `PDF`, `CSV`, `IMG`, `TXT`, `DOCX`, `EXCEL`, `XML`, `HTML`
- `presignedUrl` (string, optional) — A presigned URL to download the file. Expires after 15 minutes.
- `parentFileId` (string, optional) — The ID of the parent file. Only included if this file is a derivative of another file, for instance if it was created via a Splitter in a workflow.
- `contents` (FileContents, optional)
- `usage` (FileCredits, optional) — These are usage credits for parsing the file. This field will not be returned for files processed before October 7, 2025, or for customers on legacy billing systems. For more details on how credits work, see our [Credits Guide](https://docs.extend.ai/general/how-credits-work).

### FileMetadata

- `pageCount` (double, optional) — The number of pages in the file. This is only set for PDF/DOCX files.
- `parentSplit` (FileMetadataParentSplit, optional) — The split metadata details. Only included if this file is a derivative of another file, for instance if it was created via a Splitter in a workflow.

### FileContents

- `rawText` (string, optional) — The raw text content of the file. This is included for all file types if the `rawText` query parameter is set to true in the endpoint request.
- `markdown` (string, optional) — Cleaned and structured markdown content of the entire file. Available for PDF and IMG file types. Only included if the `markdown` query parameter is set to true in the endpoint request.
- `pages` (list of FileContentsPagesItems, optional)
- `sheets` (list of FileContentsSheetsItems, optional)

### FileCredits

These are usage credits for parsing the file. This field will not be returned for files processed before October 7, 2025, or for customers on legacy billing systems. For more details on how credits work, see our [Credits Guide](https://docs.extend.ai/general/how-credits-work).

- `credits` (double, required) — The number of credits consumed specifically for parsing this file.

### FileMetadataParentSplit

The split metadata details. Only included if this file is a derivative of another file, for instance if it was created via a Splitter in a workflow.

- `id` (string, required) — The ID of the split.
- `type` (string, required) — The type of the split.
- `identifier` (string, required) — The identifier of the split.
- `startPage` (integer, required) — The start page of the split.
- `endPage` (integer, required) — The end page of the split.

### FileContentsPagesItems

- `pageNumber` (integer, required) — The page number of this page in the document.
- `pageHeight` (double, optional)
- `pageWidth` (double, optional)
- `rawText` (string, optional) — The raw text content extracted from this page.
- `markdown` (string, optional) — Cleaned and structured markdown content of this page.
- `html` (string, optional) — Cleaned and structured html content of the page. Available for DOCX file types (that were not auto-converted to PDFs). Only included if the `html` query parameter is set to true in the endpoint request.

### FileContentsSheetsItems

- `sheetName` (string, required) — The name of the sheet.
- `rawText` (string, optional) — The raw text content of the sheet.

## Examples

**Request**

```json
{
  "file": "<file: string>"
}
```

**Response**

```json
{
  "success": true,
  "file": {
    "object": "file",
    "id": "file_dmuFrLrcdW0Jv6f78f20a",
    "name": "My File",
    "metadata": {},
    "createdAt": "2025-05-12T20:57:39.105000+00:00",
    "updatedAt": "2025-05-12T20:57:39.111000+00:00",
    "type": "PDF",
    "contents": {}
  }
}
```