docs(sandbox): add POST /api/sandbox + GET /api/sandbox/status reference

[sweetmantech]

Summary

Adds the OpenAPI spec and reference pages for the two session-scoped sandbox endpoints needed to drive chat's "loading sandbox..." UX on session entry: POST /api/sandbox (provision or resume) and GET /api/sandbox/status (poll readiness).

This is the docs half of the next route-by-route port from open-agents into api — sequel to PR #185 (GET /api/sessions/{sessionId}) and PR #186 (POST /api/sessions). The matching api PR will follow once this lands.

Why these two endpoints first

The chat product wants the open-agents UX where a new session lands on a page that shows "loading sandbox..." until a sandbox is bound and ready (restored from a per-org snapshot when one exists, freshly provisioned otherwise). That UX needs exactly two backend calls:

1. POST /api/sandbox — trigger provision/restore on session entry
2. GET /api/sandbox/status — poll until status === "active"

POST /api/sessions (already shipped) only creates the session row + initial chat — it does not spawn a sandbox. So without these two endpoints, chat cannot drive the loading state.

Scope: deliberately partial

The full open-agents /api/sandbox/* namespace also includes extend, activity, reconnect, and snapshot. Those are deferred to a follow-up docs PR alongside their api handlers — matching the lesson from PR #187 (don't document fields/endpoints api can't deliver yet). Each of the deferred routes is small and reuses the same session-scoped sandbox handle pattern, so adding them later is mechanical.

Provenance

Response and request shapes captured directly from open-agents production handlers:

• apps/web/lib/sandbox/create-sandbox-handler.ts (POST handler)
• apps/web/app/api/sandbox/status/route.ts (GET handler, including the SandboxStatusResponse type literal)

The lifecycle state enum mirrors the one already in Session schema in sessions.json (provisioning / active / hibernating / hibernated / restoring / archived / failed) so clients can reuse the same type across endpoints.

File layout

File	Purpose
api-reference/openapi/sandbox.json	OpenAPI 3.1 spec for the two endpoints + their schemas
api-reference/sandbox/create.mdx	Frontmatter-only reference for POST /api/sandbox
api-reference/sandbox/status.mdx	Frontmatter-only reference for GET /api/sandbox/status
docs.json	New "Session Sandboxes" group under "Agents & Sandboxes" tab

Singular sandbox/ deliberately distinguishes these from the legacy account-scoped plural /api/sandboxes routes that already live at api-reference/sandboxes/. The two namespaces will coexist during the migration window.

Error envelope

Uses { status: "error", error } to match the api convention established by PR #185/#186 (Sessions). The open-agents handlers themselves emit just { error } — the api port will normalize to the api shape, which is what this docs spec describes.

Test plan

• npx mintlify@latest dev renders without errors
• New "Session Sandboxes" group appears under "Agents & Sandboxes" tab
• "Create or restore session sandbox" page renders POST request body + 200/400/401/403/404/502 responses
• "Get session sandbox status" page renders the sessionId query param + lifecycle envelope schema

What follows this PR

1. api PR — handler under apps/api/app/api/sandbox/, Privy Bearer via validateAuthContext, Supabase via lib/supabase/sessions/* reusing the abstraction merged in #507
2. open-agents PR — point UI at RECOUPABLE_API_BASE_URL + Privy Bearer for these two routes, delete the local handlers once preview is green
3. Follow-up docs PR — extend / activity / reconnect / snapshot

🤖 Generated with Claude Code

---

Summary by cubic

Adds docs for the session-scoped sandbox APIs that power chat’s “loading sandbox…” flow on session entry: POST /api/sandbox (create or resume) and GET /api/sandbox/status (poll readiness). Includes an OpenAPI 3.1 spec and reference pages scoped to these two routes.

• New Features
  • Added OpenAPI 3.1 spec for POST /api/sandbox and GET /api/sandbox/status.
  • Added reference pages: Create or restore session sandbox, Get session sandbox status.
  • Introduced a “Session Sandboxes” group in the Agents & Sandboxes docs.
  • Standardized error envelope to { status: "error", error } to match Sessions API.
  • Clearly separated singular session-scoped sandbox/ from legacy account-scoped /api/sandboxes; other routes (extend, activity, reconnect, snapshot) will follow later.
  • Made prose provider-agnostic; kept literal mode: "vercel" enum to document current response payload.

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

[coderabbitai]

Warning

Rate limit exceeded

@sweetmantech has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 9 minutes and 2 seconds before requesting another review.

To continue reviewing without waiting, purchase usage credits in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 607dbd18-cc89-480d-90ab-3940f659854a

📥 Commits

Reviewing files that changed from the base of the PR and between 8cdd415 and 4049169.

📒 Files selected for processing (4)

• api-reference/openapi/sandbox.json
• api-reference/sandbox/create.mdx
• api-reference/sandbox/status.mdx
• docs.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/sandbox-loading

---

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]

1 issue found across 4 files

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/sandbox.json">

<violation number="1" location="api-reference/openapi/sandbox.json:300">
P2: OpenAPI 3.1 schema uses `nullable`, which should be replaced with `type` unions including `"null"`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: OpenAPI 3.1 schema uses nullable, which should be replaced with type unions including "null".

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/sandbox.json, line 300:

<comment>OpenAPI 3.1 schema uses `nullable`, which should be replaced with `type` unions including `"null"`.</comment>

<file context>
@@ -0,0 +1,356 @@
+              },
+              "state": {
+                "type": "string",
+                "nullable": true,
+                "enum": [
+                  "provisioning",
</file context>

[sweetmantech]

Pushed 4049169 addressing the review feedback:

Applied your two suggestions verbatim — dropped "Vercel Sandbox" → "Sandbox" in both flagged spots. Also caught one more "Vercel Sandbox" mention in the 502 response description (line 91) and applied the same intent there.

Kept the literal "vercel" enum value for mode (line 239) and its description (line 241) — that's the actual response payload the server returns today (mode: "vercel" in create-sandbox-handler.ts). Removing it would misrepresent the API contract. Happy to revisit if/when the server stops emitting that literal.

Skipped the cubic-dev-ai P2 about nullable → type: ["string", "null"]. The merged sessions.json uses nullable: true consistently, so matching that convention is more valuable than chasing the spec on this PR. If we want to migrate, it's a clean follow-up across both files.