> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Week of 2026-05-05 — Files-and-Bindings unified model

> Files-and-Bindings narrow lands its public-API contract change: /api/v2/files now returns Id&lt;files&gt;.

**2026-05-05**

Files-and-Bindings narrow lands its public-API contract change: /api/v2/files now returns Id\<files>.

Last updated 2026-11-11

·
applies to 2026-05-05

·
main

## Summary

The unified Files-and-Bindings narrow continues to land in incremental PRs. PR-8e is the public-contract step: every wire path for `/api/v2/files` now returns and accepts an `Id<"files">`, replacing the legacy `Id<"workerFiles">`. The old shape is no longer accepted; integrators consuming the REST surface directly should re-upload any in-flight files.

## What changed

Breaking — REST wire shape

`POST /api/v2/files` returns a `fileId` whose string format is now an `Id<"files">` (the IDs differ from the legacy `workerFiles` format). `GET /api/v2/files/content?id=<fileId>` resolves IDs against the new `files` table; the legacy ID format no longer resolves.

The fallback path that accepts a raw Convex `_storage` ID (used by workflow output IDs surfaced via `runs.get`) is unchanged — workflow output download flows continue to work.

* **SDK**: `@tangogroup/forge-sdk@2.3.0` published to communicate the wire-shape break. The SDK does not yet expose typed `files.upload` / `files.content` clients; the version bump exists so integrators who pin on semver pick up the contract change.
* **Internal**: the file reads and writes migrated. `getProvenanceForArtifact` accepts `Id<"files">` now and walks the `fileBindings` row to recover run/node lineage.
* **Internal**: the External App file purge was renamed `purgeAppWorkerFiles → purgeAppFiles`. App-isolation for files (the legacy `principalExternalApplicationId` index) is being re-implemented on the unified schema; the deactivation cascade is structurally preserved but currently a no-op for files until the follow-up wires app-ownership onto `files` or `fileBindings`.

## Migration

Direct REST consumers:

1. Bump `@tangogroup/forge-sdk` to `2.3.0` (or update version pins on direct REST consumers).
2. Re-upload any in-flight files; legacy `workerFiles` IDs are no longer resolvable.
3. Workflow output download flows that pass a raw `_storage` ID from `runs.get` are unaffected — that fallback path still works.

## What's next

PR-8f (knowledge ingestion migration) and PR-8h (legacy table drop) close out the Files-and-Bindings narrow. App-isolation for files lands in a follow-up once the new schema carries an app-ownership column.

***

*See also: [HTTP API — Files](https://docs.gloo.com/forge/reference/http-api/files) | SDK CHANGELOG | Files-and-Bindings spec*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.