> This page is for version v2026-02-09 (default).
> 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.

# Files Migration

> Changes to /files endpoints

## What's Changed

* **New `FileSummary` object** — Lightweight file info used in list responses
* **Content extraction moved** — Use Parse endpoints instead of `?markdown=true` query params
* **Simpler delete response** — Returns just `{ id }` instead of `{ success, fileId, message }`
* **Consistent SDK naming** — `client.file.*` → `client.files.*`

> **Info**
>
> These changes are straightforward. Most `/files` endpoint functionality works the same way.

---

This guide covers all breaking changes to the `/files` endpoints.

## Summary of Changes

| Old Endpoint         | New Endpoint         | Change Type | Description                                                     |
| -------------------- | -------------------- | ----------- | --------------------------------------------------------------- |
| `GET /files`         | `GET /files`         | Breaking    | Returns `FileSummary[]` instead of `File[]`, no `success` field |
| `GET /files/{id}`    | `GET /files/{id}`    | Breaking    | Query params removed, no `contents` field, SDK method renamed   |
| `DELETE /files/{id}` | `DELETE /files/{id}` | Breaking    | Response simplified to `{ id }`                                 |
| `POST /files/upload` | `POST /files/upload` | Breaking    | Returns `File` (with `presignedUrl: null`), no `success` field  |
| `POST /files`        | —                    | Removed     | Deprecated endpoint removed entirely                            |

---

## SDK Changes

The SDK group and method names have been updated for consistency:

#### TypeScript

**`Before (2025-04-21)`**

```typescript title="Before (2025-04-21)"
const files = await client.file.list();
const file = await client.file.get("file_abc123");
await client.file.delete("file_abc123");
const uploaded = await client.file.upload(fileData);
```

**`After (2026-02-09)`**

```typescript title="After (2026-02-09)"
const files = await client.files.list();
const file = await client.files.retrieve("file_abc123");
await client.files.delete("file_abc123");
const uploaded = await client.files.upload(fileData);
```

#### Python

**`Before (2025-04-21)`**

```python title="Before (2025-04-21)"
files = client.file.list()
file = client.file.get("file_abc123")
client.file.delete("file_abc123")
uploaded = client.file.upload(file_data)
```

**`After (2026-02-09)`**

```python title="After (2026-02-09)"
files = client.files.list()
file = client.files.retrieve("file_abc123")
client.files.delete("file_abc123")
uploaded = client.files.upload(file_data)
```

#### Java

**`After (2026-02-09)`**

```java title="After (2026-02-09)"
var files = client.files().list();
var file = client.files().retrieve("file_abc123");
client.files().delete("file_abc123");
var uploaded = client.files().upload(fileData, FilesUploadRequest.builder().build());
```

---

## File Schema

The `File` schema has been simplified. The `contents` field has been removed entirely—use the Parse endpoints for content extraction. Additionally, `parentFileId` is now **required but nullable** for a predictable response structure.

| Property       | Old (File)               | New (File)                  | Change                                                        |
| -------------- | ------------------------ | --------------------------- | ------------------------------------------------------------- |
| `object`       | Required `"file"`        | Required `"file"`           | No change                                                     |
| `id`           | Required `string`        | Required `string`           | No change                                                     |
| `name`         | Required `string`        | Required `string`           | No change                                                     |
| `type`         | Optional `FileType` enum | Required `FileType \| null` | Now required but nullable                                     |
| `presignedUrl` | Optional `string`        | Required `string \| null`   | Now required but nullable (only non-null on GET /files/\{id}) |
| `parentFileId` | Optional `string`        | Required `string \| null`   | Now required but nullable                                     |
| `contents`     | Optional `object`        | —                           | Removed (use Parse endpoints)                                 |
| `metadata`     | Required `object`        | Required `FileMetadata`     | Schema changed (only contains `parentSplit`)                  |
| `createdAt`    | Required `string`        | Required `string`           | No change                                                     |
| `updatedAt`    | Required `string`        | Required `string`           | No change                                                     |

### Response Example

```typescript
// Before (2025-04-21)
{
  "success": true,
  "file": {
    "object": "file",
    "id": "file_abc123",
    "name": "invoice.pdf",
    "type": "PDF",
    "presignedUrl": "https://storage.example.com/...",
    "parentFileId": "file_parent123",
    "contents": {
      "rawText": "Invoice #12345...",
      "markdown": "# Invoice\n\n...",
      "pages": [
        {
          "pageNumber": 1,
          "pageHeight": 792,
          "pageWidth": 612,
          "rawText": "Invoice #12345...",
          "markdown": "# Invoice\n\n..."
        }
      ],
      "sheets": null
    },
    "metadata": {
      "pageCount": 5,
      "parentSplit": null
    },
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

// After (2026-02-09) - derivative file (has parent)
{
  "object": "file",
  "id": "file_abc123",
  "name": "invoice.pdf",
  "type": "PDF",
  "presignedUrl": "https://storage.example.com/...",
  "parentFileId": "file_parent123",
  "metadata": {
    "parentSplit": {
      "id": "split_xyz",
      "type": "Invoice",
      "identifier": "invoice_1",
      "startPage": 1,
      "endPage": 3
    }
  },
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}

// After (2026-02-09) - regular file (no parent)
{
  "object": "file",
  "id": "file_abc123",
  "name": "invoice.pdf",
  "type": "PDF",
  "presignedUrl": "https://storage.example.com/...",
  "parentFileId": null,
  "metadata": {},
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}
```

---

## FileSummary Schema (New)

The new `FileSummary` schema is a lighter object used in list responses and upload responses. It excludes the `presignedUrl` and `contents` fields. Like `File`, `parentFileId` is now **required but nullable**.

| Property       | Old (File)               | New (FileSummary)           | Change                                       |
| -------------- | ------------------------ | --------------------------- | -------------------------------------------- |
| `object`       | Required `"file"`        | Required `"file"`           | No change                                    |
| `id`           | Required `string`        | Required `string`           | No change                                    |
| `name`         | Required `string`        | Required `string`           | No change                                    |
| `type`         | Optional `FileType` enum | Required `FileType \| null` | Now required but nullable                    |
| `presignedUrl` | Optional `string`        | —                           | Not included                                 |
| `parentFileId` | Optional `string`        | Required `string \| null`   | Now required but nullable                    |
| `contents`     | Optional `object`        | —                           | Not included                                 |
| `metadata`     | Required `object`        | Required `FileMetadata`     | Schema changed (only contains `parentSplit`) |
| `createdAt`    | Required `string`        | Required `string`           | No change                                    |
| `updatedAt`    | Required `string`        | Required `string`           | No change                                    |

### FileSummary Example

```typescript
// After (2026-02-09) - FileSummary object (regular file)
{
  "object": "file",
  "id": "file_abc123",
  "name": "invoice.pdf",
  "type": "PDF",
  "parentFileId": null,
  "metadata": {},
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}

// After (2026-02-09) - FileSummary object (derivative file)
{
  "object": "file",
  "id": "file_split456",
  "name": "invoice_page1.pdf",
  "type": "PDF",
  "parentFileId": "file_abc123",
  "metadata": {
    "parentSplit": {
      "id": "split_xyz",
      "type": "Invoice",
      "identifier": "invoice_1",
      "startPage": 1,
      "endPage": 3
    }
  },
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}
```

---

## FileMetadata Schema Changes

The metadata object structure has changed:

| Property      | Old (metadata)    | New (FileMetadata)     | Change    |
| ------------- | ----------------- | ---------------------- | --------- |
| `pageCount`   | Optional `number` | —                      | Removed   |
| `parentSplit` | Optional `object` | Optional `ParentSplit` | No change |

> **Warning**
>
> The `pageCount` property has been removed from the File object. To get page count information, use the [Parse endpoints](/api-reference/endpoints/parse/create-parse-run) which include `pageCount` in the output metadata.

---

## GET /files (List Files)

### Endpoint Path

```bash
# Path unchanged
GET /files
```

### Query Parameter Changes

No breaking changes to query parameters.

### Response Changes

> **Note**
>
> **Response shape changes:** List responses now use `{ "object": "list", "data": [...] }` format, and single object responses are returned directly (no wrapper key). See [Simplified Response Shapes](/api-reference/migrations/2026-02-09/overview#simplified-response-shapes) for details.

The response now returns `FileSummary` objects instead of `File` objects:

```typescript
// Before (2025-04-21)
{
  "success": true,
  "files": [
    {
      "object": "file",
      "id": "file_abc123",
      "name": "invoice.pdf",
      "type": "PDF",
      "presignedUrl": "https://...",
      "parentFileId": null,
      "contents": {
        "rawText": null,
        "markdown": null,
        "pages": null,
        "sheets": null
      },
      "metadata": {
        "pageCount": 5,
        "parentSplit": null
      },
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "nextPageToken": "..."
}

// After (2026-02-09)
{
  "object": "list",
  "data": [
    {
      "object": "file",
      "id": "file_abc123",
      "name": "invoice.pdf",
      "type": "PDF",
      "parentFileId": null,
      "metadata": {},
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "nextPageToken": "..."
}
```

**Key differences:**

* No `success` field
* List responses now use standardized format with `object: "list"` and `data` array
* `presignedUrl` not included (use `GET /files/{id}` to get download URL)
* `contents` field not included
* `pageCount` removed from metadata

---

## GET /files/\{id} (Get File)

### Endpoint Path

```bash
# Path unchanged
GET /files/{id}
```

### Query Parameter Changes

**Removed query parameters:**

| Old Parameter | New Parameter | Change  |
| ------------- | ------------- | ------- |
| `rawText`     | —             | Removed |
| `markdown`    | —             | Removed |
| `html`        | —             | Removed |

> **Warning**
>
> To get parsed content from files (raw text, markdown, HTML), use the [Parse endpoints](/api-reference/endpoints/parse/create-parse-run) instead.

```typescript
// Before (2025-04-21) - Getting markdown content
GET /files/file_abc123?markdown=true

// After (2026-02-09) - Use Parse endpoint instead
POST /parse_runs
{
  "file": { "id": "file_abc123" },
  "config": { "outputTypes": ["markdown"] }
}
```

### Response Changes

```typescript
// Before (2025-04-21)
{
  "success": true,
  "file": {
    "object": "file",
    "id": "file_abc123",
    "name": "invoice.pdf",
    "type": "PDF",
    "presignedUrl": "https://...",
    "parentFileId": "file_parent123",
    "contents": {
      "rawText": "...",
      "markdown": "...",
      "pages": [...],
      "sheets": [...]
    },
    "metadata": {
      "pageCount": 5,
      "parentSplit": null
    },
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

// After (2026-02-09) - derivative file example
{
  "object": "file",
  "id": "file_abc123",
  "name": "invoice.pdf",
  "type": "PDF",
  "presignedUrl": "https://...",
  "parentFileId": "file_parent123",
  "metadata": {
    "parentSplit": {
      "id": "split_xyz",
      "type": "Invoice",
      "identifier": "invoice_1",
      "startPage": 1,
      "endPage": 3
    }
  },
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}
```

**Key differences:**

* No `success` field
* `contents` field removed (use Parse endpoints for content extraction)
* `pageCount` removed from metadata
* `parentFileId` is now always present (`null` for non-derivative files)

---

## DELETE /files/\{id} (Delete File)

### Endpoint Path

```bash
# Path unchanged
DELETE /files/{id}
```

### Response Changes

The response has been significantly simplified:

```typescript
// Before (2025-04-21)
{
  "success": true,
  "fileId": "file_abc123",
  "message": "File data has been successfully deleted."
}

// After (2026-02-09)
{
  "id": "file_abc123"
}
```

**Key differences:**

* No `success` field
* `fileId` renamed to `id`
* `message` field removed

---

## POST /files/upload (Upload File)

### Endpoint Path

```bash
# Path unchanged
POST /files/upload
```

### Request Body

No changes to the request body. The endpoint still accepts `multipart/form-data` with a `file` field.

### Response Changes

The upload endpoint now returns a `File` object with consistent nullable fields:

```typescript
// Before (2025-04-21)
{
  "success": true,
  "file": {
    "object": "file",
    "id": "file_abc123",
    "name": "invoice.pdf",
    "type": "PDF",
    "presignedUrl": null,
    "parentFileId": null,
    "contents": {
      "rawText": null,
      "markdown": null,
      "pages": null,
      "sheets": null
    },
    "metadata": {
      "pageCount": null,
      "parentSplit": null
    },
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

// After (2026-02-09)
{
  "object": "file",
  "id": "file_abc123",
  "name": "invoice.pdf",
  "type": "PDF",
  "presignedUrl": null,
  "parentFileId": null,
  "metadata": {},
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}
```

**Key differences:**

* No `success` field
* `contents` field removed
* `presignedUrl` is `null` (only available on `GET /files/{id}`)
* All nullable fields are always present with explicit `null` values

---

## POST /files (Create File) - REMOVED

> **Warning**
>
> The `POST /files` endpoint has been completely removed. It was deprecated in API version 2025-04-21.

If you were using this endpoint, migrate to `POST /files/upload`:

```bash
# Before (2025-04-21) - Deprecated endpoint
POST /files
Content-Type: application/json
{
  "name": "invoice.pdf",
  "url": "https://example.com/invoice.pdf"
}

# After (2026-02-09) - Use upload endpoint with multipart form
POST /files/upload
Content-Type: multipart/form-data
# Include file contents directly
```

Alternatively, you can use inline file URLs directly in processing endpoints without uploading first:

```typescript
// Process a file by URL without uploading first
POST /extract_runs
{
  "file": {
    "url": "https://example.com/invoice.pdf",
    "name": "invoice.pdf"
  },
  "extractor": { "id": "ex_abc123" }
}
```

---

## SDK Method Reference

| Old SDK Method         | New SDK Method            |
| ---------------------- | ------------------------- |
| `client.file.list()`   | `client.files.list()`     |
| `client.file.get()`    | `client.files.retrieve()` |
| `client.file.delete()` | `client.files.delete()`   |
| `client.file.upload()` | `client.files.upload()`   |

---

## Need Help?

If you encounter any issues while migrating, please contact our support team at [support@extend.app](mailto:support@extend.app).

---

## Migration Guides

| Guide                            | Migrating From           | Migrating To                            |
| -------------------------------- | ------------------------ | --------------------------------------- |
| [Overview](./overview)           | —                        | What's new and how to upgrade           |
| [Extract Runs](./extract)        | `/processor_runs`        | `/extract_runs` + `/extract`            |
| [Classify Runs](./classify)      | `/processor_runs`        | `/classify_runs` + `/classify`          |
| [Split Runs](./split)            | `/processor_runs`        | `/split_runs` + `/split`                |
| [Parse Runs](./parse)            | `/parse`, `/parse/async` | `/parse_runs` + `/parse`                |
| [Edit Runs](./edit)              | `/edit`, `/edit/async`   | `/edit_runs` + `/edit`                  |
| [Extractors](./extractors)       | `/processors`            | `/extractors`                           |
| [Classifiers](./classifiers)     | `/processors`            | `/classifiers`                          |
| [Splitters](./splitters)         | `/processors`            | `/splitters`                            |
| [Files](./files)                 | `/files`                 | `/files` (breaking changes)             |
| [Evaluation Sets](./evaluation)  | evaluation endpoints     | Updated evaluation endpoints            |
| [Workflow Runs](./workflow-runs) | `/workflow_runs`         | `/workflow_runs` (breaking changes)     |
| [Webhooks](./webhooks)           | `processor_run.*` events | `extract_run.*`, `classify_run.*`, etc. |