Files Migration | Extend Documentation

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.*

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

Python

Java

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)

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);

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

// 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

// 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

The pageCount property has been removed from the File object. To get page count information, use the Parse endpoints which include pageCount in the output metadata.

GET /files (List Files)

Endpoint Path

# Path unchanged
GET /files

Query Parameter Changes

No breaking changes to query parameters.

Response Changes

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 for details.

The response now returns FileSummary objects instead of File objects:

// 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

# Path unchanged
GET /files/{id}

Query Parameter Changes

Removed query parameters:

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

To get parsed content from files (raw text, markdown, HTML), use the Parse endpoints instead.

// 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

// 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

# Path unchanged
DELETE /files/{id}

Response Changes

The response has been significantly simplified:

// 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

# 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:

// 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

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:

# 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:

// 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.

Migration Guides

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