Migration Guides2026-02-09

Files Migration

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 EndpointNew EndpointChange TypeDescription
GET /filesGET /filesBreakingReturns FileSummary[] instead of File[], no success field
GET /files/{id}GET /files/{id}BreakingQuery params removed, no contents field, SDK method renamed
DELETE /files/{id}DELETE /files/{id}BreakingResponse simplified to { id }
POST /files/uploadPOST /files/uploadBreakingReturns File (with presignedUrl: null), no success field
POST /files—RemovedDeprecated endpoint removed entirely

SDK Changes

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

Before (2025-04-21)
1const files = await client.file.list();
2const file = await client.file.get("file_abc123");
3await client.file.delete("file_abc123");
4const uploaded = await client.file.upload(fileData);
After (2026-02-09)
1const files = await client.files.list();
2const file = await client.files.retrieve("file_abc123");
3await client.files.delete("file_abc123");
4const 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.

PropertyOld (File)New (File)Change
objectRequired "file"Required "file"No change
idRequired stringRequired stringNo change
nameRequired stringRequired stringNo change
typeOptional FileType enumRequired FileType | nullNow required but nullable
presignedUrlOptional stringRequired string | nullNow required but nullable (only non-null on GET /files/{id})
parentFileIdOptional stringRequired string | nullNow required but nullable
contentsOptional object—Removed (use Parse endpoints)
metadataRequired objectRequired FileMetadataSchema changed (only contains parentSplit)
createdAtRequired stringRequired stringNo change
updatedAtRequired stringRequired stringNo change

Response Example

1// Before (2025-04-21)
2{
3  "success": true,
4  "file": {
5    "object": "file",
6    "id": "file_abc123",
7    "name": "invoice.pdf",
8    "type": "PDF",
9    "presignedUrl": "https://storage.example.com/...",
10    "parentFileId": "file_parent123",
11    "contents": {
12      "rawText": "Invoice #12345...",
13      "markdown": "# Invoice\n\n...",
14      "pages": [
15        {
16          "pageNumber": 1,
17          "pageHeight": 792,
18          "pageWidth": 612,
19          "rawText": "Invoice #12345...",
20          "markdown": "# Invoice\n\n..."
21        }
22      ],
23      "sheets": null
24    },
25    "metadata": {
26      "pageCount": 5,
27      "parentSplit": null
28    },
29    "createdAt": "2025-01-01T00:00:00Z",
30    "updatedAt": "2025-01-01T00:00:00Z"
31  }
32}
33
34// After (2026-02-09) - derivative file (has parent)
35{
36  "object": "file",
37  "id": "file_abc123",
38  "name": "invoice.pdf",
39  "type": "PDF",
40  "presignedUrl": "https://storage.example.com/...",
41  "parentFileId": "file_parent123",
42  "metadata": {
43    "parentSplit": {
44      "id": "split_xyz",
45      "type": "Invoice",
46      "identifier": "invoice_1",
47      "startPage": 1,
48      "endPage": 3
49    }
50  },
51  "createdAt": "2025-01-01T00:00:00Z",
52  "updatedAt": "2025-01-01T00:00:00Z"
53}
54
55// After (2026-02-09) - regular file (no parent)
56{
57  "object": "file",
58  "id": "file_abc123",
59  "name": "invoice.pdf",
60  "type": "PDF",
61  "presignedUrl": "https://storage.example.com/...",
62  "parentFileId": null,
63  "metadata": {},
64  "createdAt": "2025-01-01T00:00:00Z",
65  "updatedAt": "2025-01-01T00:00:00Z"
66}

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.

PropertyOld (File)New (FileSummary)Change
objectRequired "file"Required "file"No change
idRequired stringRequired stringNo change
nameRequired stringRequired stringNo change
typeOptional FileType enumRequired FileType | nullNow required but nullable
presignedUrlOptional string—Not included
parentFileIdOptional stringRequired string | nullNow required but nullable
contentsOptional object—Not included
metadataRequired objectRequired FileMetadataSchema changed (only contains parentSplit)
createdAtRequired stringRequired stringNo change
updatedAtRequired stringRequired stringNo change

FileSummary Example

1// After (2026-02-09) - FileSummary object (regular file)
2{
3  "object": "file",
4  "id": "file_abc123",
5  "name": "invoice.pdf",
6  "type": "PDF",
7  "parentFileId": null,
8  "metadata": {},
9  "createdAt": "2025-01-01T00:00:00Z",
10  "updatedAt": "2025-01-01T00:00:00Z"
11}
12
13// After (2026-02-09) - FileSummary object (derivative file)
14{
15  "object": "file",
16  "id": "file_split456",
17  "name": "invoice_page1.pdf",
18  "type": "PDF",
19  "parentFileId": "file_abc123",
20  "metadata": {
21    "parentSplit": {
22      "id": "split_xyz",
23      "type": "Invoice",
24      "identifier": "invoice_1",
25      "startPage": 1,
26      "endPage": 3
27    }
28  },
29  "createdAt": "2025-01-01T00:00:00Z",
30  "updatedAt": "2025-01-01T00:00:00Z"
31}

FileMetadata Schema Changes

The metadata object structure has changed:

PropertyOld (metadata)New (FileMetadata)Change
pageCountOptional number—Removed
parentSplitOptional objectOptional ParentSplitNo 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:

1// Before (2025-04-21)
2{
3  "success": true,
4  "files": [
5    {
6      "object": "file",
7      "id": "file_abc123",
8      "name": "invoice.pdf",
9      "type": "PDF",
10      "presignedUrl": "https://...",
11      "parentFileId": null,
12      "contents": {
13        "rawText": null,
14        "markdown": null,
15        "pages": null,
16        "sheets": null
17      },
18      "metadata": {
19        "pageCount": 5,
20        "parentSplit": null
21      },
22      "createdAt": "2025-01-01T00:00:00Z",
23      "updatedAt": "2025-01-01T00:00:00Z"
24    }
25  ],
26  "nextPageToken": "..."
27}
28
29// After (2026-02-09)
30{
31  "object": "list",
32  "data": [
33    {
34      "object": "file",
35      "id": "file_abc123",
36      "name": "invoice.pdf",
37      "type": "PDF",
38      "parentFileId": null,
39      "metadata": {},
40      "createdAt": "2025-01-01T00:00:00Z",
41      "updatedAt": "2025-01-01T00:00:00Z"
42    }
43  ],
44  "nextPageToken": "..."
45}

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 ParameterNew ParameterChange
rawText—Removed
markdown—Removed
html—Removed

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

1// Before (2025-04-21) - Getting markdown content
2GET /files/file_abc123?markdown=true
3
4// After (2026-02-09) - Use Parse endpoint instead
5POST /parse_runs
6{
7  "file": { "id": "file_abc123" },
8  "config": { "outputTypes": ["markdown"] }
9}

Response Changes

1// Before (2025-04-21)
2{
3  "success": true,
4  "file": {
5    "object": "file",
6    "id": "file_abc123",
7    "name": "invoice.pdf",
8    "type": "PDF",
9    "presignedUrl": "https://...",
10    "parentFileId": "file_parent123",
11    "contents": {
12      "rawText": "...",
13      "markdown": "...",
14      "pages": [...],
15      "sheets": [...]
16    },
17    "metadata": {
18      "pageCount": 5,
19      "parentSplit": null
20    },
21    "createdAt": "2025-01-01T00:00:00Z",
22    "updatedAt": "2025-01-01T00:00:00Z"
23  }
24}
25
26// After (2026-02-09) - derivative file example
27{
28  "object": "file",
29  "id": "file_abc123",
30  "name": "invoice.pdf",
31  "type": "PDF",
32  "presignedUrl": "https://...",
33  "parentFileId": "file_parent123",
34  "metadata": {
35    "parentSplit": {
36      "id": "split_xyz",
37      "type": "Invoice",
38      "identifier": "invoice_1",
39      "startPage": 1,
40      "endPage": 3
41    }
42  },
43  "createdAt": "2025-01-01T00:00:00Z",
44  "updatedAt": "2025-01-01T00:00:00Z"
45}

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:

1// Before (2025-04-21)
2{
3  "success": true,
4  "fileId": "file_abc123",
5  "message": "File data has been successfully deleted."
6}
7
8// After (2026-02-09)
9{
10  "id": "file_abc123"
11}

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:

1// Before (2025-04-21)
2{
3  "success": true,
4  "file": {
5    "object": "file",
6    "id": "file_abc123",
7    "name": "invoice.pdf",
8    "type": "PDF",
9    "presignedUrl": null,
10    "parentFileId": null,
11    "contents": {
12      "rawText": null,
13      "markdown": null,
14      "pages": null,
15      "sheets": null
16    },
17    "metadata": {
18      "pageCount": null,
19      "parentSplit": null
20    },
21    "createdAt": "2025-01-01T00:00:00Z",
22    "updatedAt": "2025-01-01T00:00:00Z"
23  }
24}
25
26// After (2026-02-09)
27{
28  "object": "file",
29  "id": "file_abc123",
30  "name": "invoice.pdf",
31  "type": "PDF",
32  "presignedUrl": null,
33  "parentFileId": null,
34  "metadata": {},
35  "createdAt": "2025-01-01T00:00:00Z",
36  "updatedAt": "2025-01-01T00:00:00Z"
37}

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:

1// Process a file by URL without uploading first
2POST /extract_runs
3{
4  "file": {
5    "url": "https://example.com/invoice.pdf",
6    "name": "invoice.pdf"
7  },
8  "extractor": { "id": "ex_abc123" }
9}

SDK Method Reference

Old SDK MethodNew 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

GuideMigrating FromMigrating 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 Setsevaluation endpointsUpdated evaluation endpoints
Workflow Runs/workflow_runs/workflow_runs (breaking changes)
Webhooksprocessor_run.* eventsextract_run.*, classify_run.*, etc.