docs: document POST /api/sandboxes/staged-files

[arpitgupta1214]

Summary

Documents the new sandbox staged-files token-handshake endpoint that pairs with api#541. Adds an OpenAPI entry under content.json, a frontmatter-only MDX page, and the sandboxes nav slot in docs.json.

Test plan

• python3 -m json.tool clean on api-reference/openapi/content.json and docs.json
• npx mintlify@latest dev — verify the new "Stage Files" page renders under Sandboxes

---

Summary by cubic

Documents POST /api/sandboxes/staged-file for the Vercel Blob client-upload handshake.

OpenAPI notes @vercel/blob/client usage, adds a 100MB limit and 401/500 responses, adds a Stage File page (stage-file.mdx), renames Upload→Upload Files and File→Get File, and updates the Sandboxes nav.

^{Written for commit 9d79852. Summary will update on new commits.}

Summary by CodeRabbit

• New Features
  • Added a new API endpoint for staging files with direct browser uploads to Vercel Blob using a two-step handshake process.
  • Added documentation page for the file staging endpoint.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dbe3ba27-4785-428e-9c30-a44f132d1a1e

📥 Commits

Reviewing files that changed from the base of the PR and between 4820191 and 9d79852.

📒 Files selected for processing (5)

• api-reference/openapi/content.json
• api-reference/sandboxes/get-file.mdx
• api-reference/sandboxes/stage-file.mdx
• api-reference/sandboxes/upload-files.mdx
• docs.json

---

📝 Walkthrough

Walkthrough

This PR adds documentation for a new POST /api/sandboxes/staged-file endpoint that implements a two-step handshake for browser direct uploads to Vercel Blob storage. The OpenAPI specification, MDX documentation page, and navigation routing configuration are introduced.

Changes

Sandboxes File Staging Endpoint

Layer / File(s)	Summary
OpenAPI Specification api-reference/openapi/content.json	New POST /api/sandboxes/staged-file endpoint defined with generic object request/response schemas for Vercel Blob client passthrough and 401, 500 error responses documented.
Documentation Page api-reference/sandboxes/stage-file.mdx	MDX page created with frontmatter linking to the new OpenAPI endpoint specification.
Navigation Configuration docs.json	Sandboxes section routes updated from file and upload to get-file, stage-file, and upload-files.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• recoupable/docs#84: Both PRs modify the sandboxes file-upload flow in the OpenAPI spec: this PR adds a new POST /api/sandboxes/staged-file handshake for direct browser uploads to blob storage while the related PR switches POST /api/sandboxes/files to accept blob URLs — they target complementary parts of the same blob-based upload workflow.

Suggested reviewers

• sweetmantech

Poem

🐰 A handshake so neat, two steps to complete,
Blob uploads now sweet, browser uploads so fleet,
Docs staged and in place, routes find their grace,
The file staging race is won with this pace! 📤

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title references '/api/sandboxes/staged-files' (plural) but the actual endpoint and documentation added is for '/api/sandboxes/staged-file' (singular).	Update the PR title to 'docs: document POST /api/sandboxes/staged-file' to match the actual endpoint name in the changeset.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/sandbox-staged-files

---

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 and usage tips.}

[cubic-dev-ai]

No issues found across 3 files

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/content.json">
<violation number="1" location="api-reference/openapi/content.json:361">
P1: The endpoint path appears mistyped as `/api/sandboxes/stage-files`; this should remain `/api/sandboxes/staged-files` to match the API being documented.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.}

[cubic-dev-ai]

You're iterating quickly on this pull request. To help protect your rate limits, cubic has paused automatic reviews on new pushes for now—when you're ready for another review, comment @cubic-dev-ai review.