V3 Migration

V3 cleans up the function and routing primitives that grew up across V1 and V2. The mental model didn't change — bem still runs functions inside workflows — but a handful of names and endpoints did. Existing integrations keep working. Legacy types remain readable and callable; you only need to migrate when you create a new function or add a new endpoint.

What renamed

What's the same

• Functions are still versioned. Updates create new versions; old versions remain immutable and addressable.
• outputSchema still uses standard JSON Schema.
• Authentication is still an x-api-key header.
• Webhooks still use the bem-signature header (t={timestamp},v1={hex_hmac_sha256}).
• Cursor pagination still uses startingAfter and endingBefore.
• File inputType values (csv, docx, email, heic, heif, html, jpeg, json, m4a, mp3, pdf, png, text, wav, webp, xls, xlsx, xml) carry over unchanged.

Endpoint mapping

The /v3 surface replaces a few legacy entry points. Where you used to call the legacy URL on the left, call the V3 URL on the right.

Subscriptions are available at /v3/subscriptions. The legacy /v1-alpha/subscriptions endpoint still works for backward compatibility and routes to the same handler. See Webhooks for the end-to-end flow.

Migration checklist

1. Create new functions as extract or classify. Don't reach for transform/analyze/route — those types are read-only on V3.
2. Wrap existing functions in workflows if you're calling them directly. A one-node workflow has no edges and behaves identically:

   {
     "name": "invoice-extractor-wrapper",
     "mainNodeName": "invoice-extractor",
     "nodes": [
       { "name": "invoice-extractor", "function": { "name": "invoice-extractor" } }
     ]
   }

   Adding nodes later produces a new workflow version without breaking existing callers.
3. Update branching keys. When you build a workflow off a Classify function, the edge field is destinationName and it matches classifications[].name. (In legacy, this was routes[].name on route functions.)
4. Re-point your polling URL if you read call status: legacy GET /v2/calls/{id} → V3 GET /v3/calls/{callID}.
5. Switch collections endpoints from /v2/collections (with Authorization: Bearer) to /v3/collections (with x-api-key), and update item bodies to use data instead of content + metadata.

You don't need to migrate a function just to use the new APIs around it: V3 endpoints accept legacy function types for reads and (for extract-equivalent operations) calls. The only hard line is creates and updates — those are V3 types only.

What's still legacy

Legacy reference pages remain available under API Reference → Legacy for endpoints that don't have a V3 successor yet. Most function-calls, events, pipelines, connectors, actions, and subscriptions endpoints are accessible there. Each legacy page that does have a V3 successor carries a deprecation callout linking to it.