Migrating to API Version 2026-02-09

Welcome to the New API

The 2026-02-09 API version is a significant improvement designed to make your integration cleaner, more type-safe, and easier to maintain. We’ve listened to developer feedback and restructured the API around clearer resource types and better SDK support.

Why Migrate?

Here’s what you’ll get with the new API version:

Dedicated Endpoints with Typed Responses

The unified /processors and /processor_runs endpoints have been split into dedicated endpoints for each resource type:

This means fully typed SDK responses—no more checking type fields or casting outputs:

1
const run = await client.processorRun.create({
2
  processorId: "dp_abc123",
3
  file: { fileUrl: "https://..." }
4
  sync: true,
5
});
6
if (run.processorRun.type === "EXTRACT") {
7
  const output = run.processorRun.output as ExtractOutput; // Manual cast
8
}

1
const result = await client.extract({
2
  extractor: { id: "ex_abc123" },
3
  file: { url: "https://..." }
4
});
5
console.log(result.output?.value); // Typed as ExtractOutput

1
import { ExtendClient, extendDate, extendCurrency } from "extend-ai";
2
import { z } from "zod";
3
4
const client = new ExtendClient({ token: "your-api-key" });
5
6
const result = await client.extract({
7
  config: {
8
    schema: z.object({
9
      invoice_number: z.string().nullable(),
10
      invoice_date: extendDate(),
11
      total: extendCurrency(),
12
    }),
13
  },
14
  file: { url: "https://..." }
15
});
16
17
// TypeScript knows the exact shape!
18
const output = result.output?.value;
19
console.log(output.invoice_number);      // string | null
20
console.log(output.invoice_date);        // string | null (ISO date)
21
console.log(output.total.amount);        // number | null
22
console.log(output.total.iso_4217_currency_code); // string | null

Run Without Pre-Creating a Resource

Previously, you had to create and manage an extractor, classifier, or splitter resource before running. Now you can pass your config inline—perfect for managing schemas entirely in code.

1
const processor = await client.processor.create({
2
  name: "Invoice Extractor",
3
  type: "EXTRACT",
4
  config: { 
5
    type: "EXTRACT", 
6
    schema: { type: "object", properties: { vendor: { type: "string" } } }
7
  }
8
});
9
const run = await client.processorRun.create({
10
  processorId: processor.processor.id,
11
  file: { fileUrl: "https://..." }
12
});

1
const run = await client.extractRuns.create({
2
  config: { 
3
    schema: { type: "object", properties: { vendor: { type: "string" } } }
4
  },
5
  file: { url: "https://..." }
6
});

Synchronous Endpoints

New synchronous endpoints let you process a file and get the result in a single request—no polling or webhooks needed. These are ideal for onboarding, testing, and low-volume use cases:

1
// Sync — returns the completed result directly
2
const result = await client.extract({
3
  extractor: { id: "ex_abc123" },
4
  file: { url: "https://..." }
5
});
6
console.log(result.output?.value);

Polling Helpers

The async *_runs endpoints are the recommended approach for production. The SDK provides createAndPoll / create_and_poll methods that handle polling with exponential backoff:

1
const result = await client.extractRuns.createAndPoll({
2
  extractor: { id: "ex_abc123" },
3
  file: { url: "https://..." }
4
});
5
// Returns when status is PROCESSED or FAILED
6
console.log(result.output?.value);

Available for all run types: extractRuns, classifyRuns, splitRuns, parseRuns, editRuns, workflowRuns.

Batch Endpoints

For high-volume use cases, dedicated batch endpoints process many files in a single request. Each returns a batchId you can use to track progress and fetch individual run results.

To retrieve individual run results from a batch, use the corresponding list endpoint filtered by batchId (e.g., GET /extract_runs?batchId={id}).

Simplified Response Shapes

API responses are now cleaner and more consistent:

Single object responses are unwrapped. Instead of { "extractRun": { ... }, "success": true }, the API now returns the object directly:

1
{
2
  "success": true,
3
  "processorRun": {
4
    "id": "dpr_abc123",
5
    "status": "PROCESSED",
6
    "output": { ... }
7
  }
8
}

1
{
2
  "id": "exr_abc123",
3
  "status": "PROCESSED",
4
  "output": { ... }
5
}

List responses use a standardized format. All list endpoints now return { "object": "list", "data": [...] }:

1
{
2
  "success": true,
3
  "processorRuns": [ ... ],
4
  "nextPageToken": "..."
5
}

1
{
2
  "object": "list",
3
  "data": [ ... ],
4
  "nextPageToken": "..."
5
}

SDK Webhook Helpers

For event-driven processing, the SDK includes utilities for verifying signatures and parsing events with type-safe payloads:

1
const event = client.webhooks.verifyAndParse(body, headers, secret);
2
3
if (event.eventType === "extract_run.processed") {
4
  console.log(event.payload.output); // Typed as ExtractRun
5
}

See the Webhooks Migration guide for full details and examples in all languages.

How to Upgrade

Step 1: Update to the New API Version

$
npm install extend-ai@latest
$
# or
$
yarn add extend-ai@latest

Step 2: Migrate Endpoint by Endpoint

You don’t have to migrate everything at once. Start with the endpoints you use most and work through the detailed guides:

Processing Runs:

• Extract Runs Migration — /processor_runs → /extract_runs (+ new sync /extract)
• Classify Runs Migration — /processor_runs → /classify_runs (+ new sync /classify)
• Split Runs Migration — /processor_runs → /split_runs (+ new sync /split)
• Parse Runs Migration — /parse_runs (+ sync /parse)
• Edit Runs Migration — /edit_runs (+ sync /edit)

Resource Management:

• Extractors Migration — /processors → /extractors
• Classifiers Migration — /processors → /classifiers
• Splitters Migration — /processors → /splitters

Other Endpoints:

• Files Migration — Changes to /files endpoints
• Evaluation Sets Migration — Changes to evaluation sets and evaluation set runs
• Workflow Runs Migration — Breaking changes to /workflow_runs request/response shapes

Step 3: Migrate Webhooks

If you use webhooks, follow the Webhooks Migration guide to update your webhook handlers. This includes:

• New event type names (e.g., processor_run.processed → extract_run.processed)
• New payload structures with typed responses
• New SDK helpers for signature verification
• Webhook endpoints can now be managed via API (POST /webhook_endpoints, POST /webhook_subscriptions) in addition to the dashboard

Need Help?

• Questions? Contact our support team at support@extend.app
• Found a bug? Let us know and we’ll fix it ASAP
• Feedback on the new API? We’d love to hear it—reach out on Slack!

Migration Guides

Jump to the specific guide for the endpoints you use: