[Zach Dunn (zachdunn)]

Requested by Zach · project thread

Gets /.well-known/openapi.json ready to serve as the contract for a public TypeScript SDK, and makes every route explicitly public or internal.

Schema fixes (drifted from handlers)

• Usage: periodStart is YYYY-MM, not a date-time; added storageBudgetBasis and storage (mode, fallback lanes, health).
• FileHead / FilePut: added provenance, pageUrl (list), holdCheck: "pending".
• GalleryItem / FeedItem: added metadata, posterUrl, videoDimensions.
• Held list items: added area.
• Gallery references is now typed (ExternalReference).
• Added missing params: list metadata=0, search collapse=promoted.

Response schemas that were missing

files/sign (SignedUpload), usage/reconcile, usage/purge-expired, gallery items/order, external references list/add, GET /public/galleries/{id} (PublicGallery), GET /public/feeds/{id} (PublicFeed, incl. the github title/state block).

Newly documented public routes

• GET /public/files/{workspace}/{key} (and ?download=1)
• GET /public/feeds/{id}/items/{item}
• GET /public/galleries/{id}/items/{item}/download
• GET /v1/workspaces/{ws}/pulls, /repos, /scope/{owner}/{repo}/files (tag "Activity")
• POST /v1/workspaces/{ws}/github/comment (tag "GitHub"); this is the call agents make once they finish uploading

Public vs internal split

apps/api/src/openapi-contract.test.ts now covers every /v1/workspaces/* and /public/* route instead of four verticals. Each route has to be in the spec or listed in INTERNAL_PREFIXES with a reason:

• Internal (web app / account management): billing, comment/poster/classifier settings, members, invites, invite links, people, service tokens, storage, summary, file browser, workspace delete/restore/tokens.
• Internal (CLI plumbing): every github/* route except comment.
• /me, /admin, /internal, the legacy /v1/:workspace aliases and the other top-level families were already out of scope.

docs/api.md gains the new rows plus a short paragraph that names the spec as the public contract. The docs API reference picks up a "Pull requests" section and keeps /public/files under "Public reads".

Testing

• API: 3,503 tests pass. Web: 1,319 tests pass.
• redocly lint on the spec: valid.
• Response shapes were checked by hand against the handlers. Nothing validates real responses against the schemas yet, so that would be a possible follow-up.

---

Generated by Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 81d2427

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one): 2

• coderabbit:review
• review

🚫 Excluded labels (none allowed): 1

• wip

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 095b4303-285a-4028-8dc1-c07ab79080f2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}