> ## 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/2026-02-09/api-reference/endpoints/workflow/create-workflow-run), [creating evaluation set items](https://docs.extend.ai/2026-02-09/api-reference/endpoints/evaluation/create-evaluation-set-item), [parsing](https://docs.extend.ai/2026-02-09/api-reference/endpoints/parse/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/2026-02-09/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/api-reference/endpoints/file/upload-file ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://api.extend.ai` (Production, default) - `https://api.us2.extend.app` (Production US2) - `https://api.eu1.extend.ai` (Production EU1) ## 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` ("2026-02-09", optional, default: 2026-02-09) — API version to use for the request. If you're using an SDK, you can ignore this parameter. If you are not using an SDK and 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/2026-02-09/api-reference/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/2026-02-09/api-reference/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 - `password` (string, optional) — The password to unlock a password-protected PDF. ## Response ### 200 Successfully uploaded file - `object` (enum, required) — The type of object. Will always be `"file"`. - Allowed values: `file` - `id` (string, required) — ID for the file. Example: `"file_xK9mLPqRtN3vS8wF5hB2cQ"` - `name` (string, required) — The name of the file Example: `"Invoices.pdf"` - `type` (enum, required, nullable) — The type of the file. **Availability:** Present when the file type could be determined. - Allowed values: `PDF`, `CSV`, `IMG`, `TXT`, `DOCX`, `EXCEL`, `XML`, `HTML` - `presignedUrl` (string, required, nullable) — A presigned URL to download the file. Expires after 15 minutes. **Availability:** Present on `GET /files/{id}`. Not present on `POST /files/upload` or when the file is embedded in other resources (e.g., in run responses). - `parentFileId` (string, required, nullable) — ID of the parent file. **Availability:** Present for files created via a Splitter in a workflow. - `metadata` (object, required) - `pageCount` (double, optional) — The number of pages in the file. This is only set for PDF/DOCX files. - `parentSplit` (object, optional) — The split metadata details for a derivative file. **Availability:** 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. - `createdAt` (string, required) — The time (in UTC) at which the object was created. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"` - `updatedAt` (string, required) — The time (in UTC) at which the object was last updated. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"` - `contents` (object, required, nullable, deprecated) — **Deprecated:** Use the `POST /parse_runs` endpoint instead to parse and retrieve file contents. The parse runs endpoint provides more control over parsing configuration and better performance. The parsed content of the file. This field will only contain data after the file has been parsed via a parse run, extract run, classify run, split run, edit run, or workflow run. **Availability:** Only present and populated on `GET /files/{id}` when the file has been previously parsed and the corresponding query parameters are set to true. Will be `null` on `POST /files/upload` and for files that haven't been parsed. The structure varies based on file type. - `rawText` (string, optional) — The raw text content of the file. Available for all file types when the `rawText` query parameter is set to true. - **PDF/IMG**: Concatenated raw text from all pages - **DOCX**: The document's raw text - **CSV**: Concatenated chunks or CSV text - **EXCEL**: Not included (use `sheets` instead) - **TXT/XML/HTML**: The file's text content - `pages` (list of object, optional) — Page-level content for document file types. - **PDF/IMG**: Contains `pageNumber`, `pageHeight`, `pageWidth`, and `markdown` (if `markdown` query param is true) - **DOCX**: Contains `pageNumber` and `html` (if `html` query param is true) - **Other file types**: Empty array - `pageNumber` (integer, required) — The page number of this page in the document. - `pageHeight` (double, optional) — The height of the page in points. Available for PDF and IMG file types. - `pageWidth` (double, optional) — The width of the page in points. Available for PDF and IMG file types. - `markdown` (string, optional) — Cleaned and structured markdown content of this page. Available for PDF and IMG file types when the `markdown` query parameter is set to true. - `html` (string, optional) — HTML content of the page. Available for DOCX file types when the `html` query parameter is set to true. - `sections` (list of object, optional) — Section-level content for documents that support section-based chunking. Available for PDF and IMG file types. - `startPageNumber` (integer, required) — The starting page number of this section. - `endPageNumber` (integer, required) — The ending page number of this section. - `markdown` (string, required) — The markdown content of this section. - `sheets` (list of object, optional) — Sheet-level content for spreadsheet file types. Available for EXCEL files. - `sheetName` (string, required) — The name of the sheet. - `rawText` (string, optional) — The raw text content of the sheet in CSV format. ## Errors ### 400 Bad Request Error Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations. - `code` (string, required) — Error code for programmatic handling. - `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change. - `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying. - `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error. - `docUrl` (string, optional) — Link to relevant documentation when one is available. ### 401 Unauthorized Error Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations. - `code` (string, required) — Error code for programmatic handling. - `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change. - `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying. - `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error. - `docUrl` (string, optional) — Link to relevant documentation when one is available. ### 402 Payment Required Error Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations. - `code` (string, required) — Error code for programmatic handling. - `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change. - `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying. - `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error. - `docUrl` (string, optional) — Link to relevant documentation when one is available. ### 403 Forbidden Error Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations. - `code` (string, required) — Error code for programmatic handling. - `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change. - `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying. - `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error. - `docUrl` (string, optional) — Link to relevant documentation when one is available. ### 404 Not Found Error Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations. - `code` (string, required) — Error code for programmatic handling. - `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change. - `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying. - `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error. - `docUrl` (string, optional) — Link to relevant documentation when one is available. ### 422 Unprocessable Entity Error Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations. - `code` (string, required) — Error code for programmatic handling. - `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change. - `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying. - `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error. - `docUrl` (string, optional) — Link to relevant documentation when one is available. ### 429 Too Many Requests Error Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations. - `code` (string, required) — Error code for programmatic handling. - `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change. - `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying. - `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error. - `docUrl` (string, optional) — Link to relevant documentation when one is available. ### 500 Internal Server Error Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations. - `code` (string, required) — Error code for programmatic handling. - `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change. - `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying. - `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error. - `docUrl` (string, optional) — Link to relevant documentation when one is available. ## Examples **Request** ```json { "file": "" } ``` **Response** ```json { "object": "file", "id": "file_xK9mLPqRtN3vS8wF5hB2cQ", "name": "Invoices.pdf", "type": "PDF", "presignedUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H", "metadata": { "pageCount": 30, "parentSplit": { "id": "string", "type": "Invoice", "identifier": "other_2_9", "startPage": 1, "endPage": 10 } }, "createdAt": "2024-03-21T16:45:00Z", "updatedAt": "2024-03-21T16:45:00Z", "contents": { "rawText": "string", "pages": [ { "pageNumber": 1, "pageHeight": 792, "pageWidth": 612, "markdown": "# Heading\n\nThis is a paragraph with **bold** and *italic* text.\n\n- List item 1\n- List item 2\n\n> This is a blockquote", "html": "
This is the html of the page.
" } ], "sections": [ { "startPageNumber": 1, "endPageNumber": 3, "markdown": "# Section Header\n\nContent spanning multiple pages...\n" } ], "sheets": [ { "sheetName": "Sheet1", "rawText": "Column1,Column2\nValue1,Value2" } ] } } ``` **SDK Code** ```python from extend_ai import Extend client = Extend(token="YOUR_API_KEY") with open("invoice.pdf", "rb") as f: file = client.files.upload(file=f) print(file.id) ``` ```python from extend_ai import Extend client = Extend( token="YOUR_TOKEN_HERE", extend_api_version="2026-02-09", ) client.files.upload( file="example_file", ) ``` ```typescript import { ExtendClient } from "extend-ai"; import { createReadStream } from "fs"; const client = new ExtendClient({ token: "YOUR_API_KEY" }); const file = await client.files.upload(createReadStream("invoice.pdf"), {}); console.log(file.id); ``` ```go f, err := os.Open("invoice.pdf") if err != nil { log.Fatal(err) } defer f.Close() file, err := client.Files.Upload(context.TODO(), f, &extend.FilesUploadRequest{}) if err != nil { log.Fatal(err) } fmt.Println(file.ID) ``` ```go package example import ( context "context" strings "strings" extend "github.com/extend-hq/extend-go-sdk" client "github.com/extend-hq/extend-go-sdk/client" option "github.com/extend-hq/extend-go-sdk/option" ) func do() { client := client.NewClient( option.WithToken( "YOUR_TOKEN_HERE", ), ) request := &extend.FilesUploadRequest{} client.Files.Upload( context.TODO(), strings.NewReader( "", ), request, ) } ``` ```java import ai.extend.ExtendClient; import ai.extend.requests.FilesUploadRequest; import ai.extend.types.File; ExtendClient client = ExtendClient.builder() .apiKey("YOUR_API_KEY") .build(); File file = client.files().upload( new java.io.File("invoice.pdf"), FilesUploadRequest.builder().build()); System.out.println(file.getId()); ``` ```java package com.example.usage; import ai.extend.ExtendClient; import ai.extend.resources.files.requests.FilesUploadRequest; public class Example { public static void main(String[] args) { ExtendClient client = ExtendClient .builder() .token("YOUR_TOKEN_HERE") .extendApiVersion("2026-02-09") .build(); client.files().upload( null, FilesUploadRequest .builder() .build() ); } } ```