feat(files): serve Anthropic's GA Files API shape and refuse the files beta header

[peteski22]

Description

#1366 made Otari's files API answer Anthropic's SDK in Anthropic's own shape. That shape was Anthropic's files-api-2025-04-14 beta, and Anthropic's Files API is now generally available with a different one. This PR moves the Anthropic flavor to the GA shape before it ships in a release:

• A listing is {data, next_page}. Pass next_page back as page for the next page, or name up to 100 files with ids[] to read them in one page. With Anthropic's SDK, client.files.list() now pages past the first page.
• Every file object carries expires_at, which is null when the file does not expire.
• A files request whose anthropic-beta header includes files-api-2025-04-14 gets a 400 that says to send it without that beta. This is stricter than Anthropic, which still honors the beta, so that Otari keeps one Anthropic contract. The cost: client.beta.files on Anthropic's Python SDK before 1.2.0, which includes the version in our lock file, gets the 400. client.files works.

The OpenAI flavor does not change. The code-execution demo and the files guide now use client.files.

For review: the listing query stays in the route, which is on the architecture baseline, because #1483 moves the whole files domain into repositories and a service. A NUL character in the OpenAI after cursor or in a file ID path still gives a 500; that was there before this PR, and this PR only guards the two new inputs.

How to test it locally

• uv run pytest tests/integration/test_files_endpoint.py (needs Docker for PostgreSQL). test_anthropic_sdk_files_client_pages_and_reads_expires_at drives Anthropic's own SDK through the app: it lists past the first page, reads expires_at, and gets the 400 from client.beta.files. The other new tests cover the page token, ids[], the refused after_id and before_id, and the 400 on all five routes.
• By hand, against a running gateway with an API key:
  • curl -H "x-api-key: <key>" -H "anthropic-version: 2023-06-01" "http://localhost:8000/api/v1/files?limit=1" answers {"data": [...], "next_page": ...}.
  • The same call with -H "anthropic-beta: files-api-2025-04-14" answers 400.
  • Without anthropic-version, the answer is the OpenAI list, as before.
• make lint, make typecheck, make openapi-check and make postman-check pass, and the dashboard client matches the spec. I did not run demo/code-exec/plot_with_anthropic_sdk.py, which needs provider credentials; the two calls it changed to are the ones the SDK test runs.

PR Type

• New Feature
• Bug Fix
• Refactor
• Documentation
• Infrastructure / CI

Relevant issues

Fixes #1473. Part of #1470.

Checklist

• I understand the code I am submitting.
• I have added or updated tests that cover my change (tests/unit, tests/integration).
• I ran the Definition of Done checks locally (make lint, make typecheck, make test).
• Documentation was updated where necessary.
• If the API contract changed, I regenerated the OpenAPI spec (uv run python scripts/generate_openapi.py).
• If this changes a rule in ARCHITECTURE.md or scripts/check_architecture.py, the description names the rule and says why.

make test passes locally apart from failures that come from the local environment and not from this change: tests that read the gitignored .env, and test_mcp_dependency_ceiling, whose throwaway virtual environment cannot load its Python library on this machine.

AI Usage

• No AI was used.
• AI was used for drafting/refactoring.
• This is fully AI-generated.

AI Model/Tool used:

Claude Code (Claude Opus 5)

Any additional AI details you'd like to share:

The design comes from the issue. Claude Code wrote the tests first, then the code, the docs and the regenerated artifacts, and ran security, error-handling, state-machine and style checks over the diff, which found three input-handling bugs that are fixed here. Peter reviewed each commit before this PR was opened.

NOTE:
When responding to reviewer questions, please respond yourself rather than copy/pasting reviewer comments into an AI and pasting back its answer. We want to discuss with you, not your AI :)

• I am an AI Agent filling out this form (check box if true)

Summary

Otari now serves Anthropic’s GA Files API shape. Anthropic listings support page pagination and up to 100 ids[] values, and file metadata always includes expires_at.

Requests that use the legacy files-api-2025-04-14 beta header now return a clear 400 error. The OpenAI Files API remains unchanged.

The demo, documentation, client schema, Postman collection, OpenAPI artifacts, and integration coverage were updated. The demo now uses client.files.

Technical notes

• Anthropic responses use {data, next_page}.
• Anthropic rejects after_id, before_id, invalid page tokens, and incompatible page/ids[] or limit/ids[] combinations.
• Added coverage for SDK pagination, metadata retrieval, downloads, deletion, beta-header rejection, and OpenAI behavior.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Repository: mozilla-ai/otari/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 51e1cfc7-d4a1-4f01-8241-7d6528732b06

📥 Commits

Reviewing files that changed from the base of the PR and between e424d08 and f40ef1c.

⛔ Files ignored due to path filters (1)

• docs/public/openapi.json is excluded by !docs/public/openapi.json

📒 Files selected for processing (7)

• demo/code-exec/plot_with_anthropic_sdk.py
• docs/files.md
• docs/public/otari.postman_collection.json
• src/gateway/api/routes/files.py
• src/gateway/models/tools.py
• tests/integration/test_files_endpoint.py
• web/src/client/schema.ts

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

✨ Simplify code

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}