Document Sites API and MCP tools

[sidneyswift]

Document Sites HTTP endpoints and all eight MCP tools, including authentication, workspace ownership, private draft generation, revision conflicts, uploads, explicit publishing, and public signup behavior. Add Sites to navigation.

Validated JSON navigation, page reference, and diff whitespace. Release after the Sites API implementation and coordinate with app PR recoupable/app#2091.

---

Summary by cubic

Adds API reference documentation for the Sites HTTP endpoints and all eight MCP tools, and adds the page to the docs navigation. The page documents authentication, workspace ownership, private draft generation, revision conflicts, uploads, explicit publishing, and public signup behavior, noting that sites start as private drafts and generation never publishes automatically. Merge after the Sites API implementation is live.

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

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: ab9af919-f74f-4e2b-b646-099f0e3b9e49

---

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

[cubic-dev-ai]

4 issues found across 2 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="docs.json">

<violation number="1" location="docs.json:433">
P2: The new Sites tab links only overview.mdx, which is a hand-written prose page, while every other API-reference tab links frontmatter-only pages that Mintlify auto-generates from an OpenAPI spec. There is no Sites spec anywhere in api-reference/openapi/, so the eight HTTP endpoints documented in the PR will not render as API-reference operations with parameter and response schemas, and this page departs from the repo's binding rule that api-reference pages be frontmatter-only. Add the Sites endpoints to a spec file under api-reference/openapi/ and expose them via frontmatter-only pages instead of burying the contract in prose.</violation>
</file>

<file name="api-reference/sites/overview.mdx">

<violation number="1" location="api-reference/sites/overview.mdx:10">
P3: This page names the Privy token placeholder `YOUR_PRIVY_ACCESS_TOKEN`, but `authentication.mdx` (the canonical auth page) uses `YOUR_PRIVY_JWT` for the identical header. Align the placeholder so readers searching for the token name get one spelling.</violation>

<violation number="2" location="api-reference/sites/overview.mdx:25">
P3: The `GET /api/sites/{id}/signups` row caps results at 10,000 but never says what happens beyond that. A site with more signups returns incomplete data, and readers cannot tell whether the response is silently truncated, ordered, or paginated. State the cutoff behavior (e.g., which 10,000 are returned and whether pagination exists) so consumers do not silently export a partial list.</violation>

<violation number="3" location="api-reference/sites/overview.mdx:48">
P3: The text above this body says to "Read the returned `site.id` and `site.revision`", then the example hardcodes `revision: 0`. A reader who follows the instruction gets a revision that may not be 0, which makes the example look stale. Use a placeholder consistent with the publish example's `CURRENT_REVISION`.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The new Sites tab links only overview.mdx, which is a hand-written prose page, while every other API-reference tab links frontmatter-only pages that Mintlify auto-generates from an OpenAPI spec. There is no Sites spec anywhere in api-reference/openapi/, so the eight HTTP endpoints documented in the PR will not render as API-reference operations with parameter and response schemas, and this page departs from the repo's binding rule that api-reference pages be frontmatter-only. Add the Sites endpoints to a spec file under api-reference/openapi/ and expose them via frontmatter-only pages instead of burying the contract in prose.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs.json, line 433:

<comment>The new Sites tab links only overview.mdx, which is a hand-written prose page, while every other API-reference tab links frontmatter-only pages that Mintlify auto-generates from an OpenAPI spec. There is no Sites spec anywhere in api-reference/openapi/, so the eight HTTP endpoints documented in the PR will not render as API-reference operations with parameter and response schemas, and this page departs from the repo's binding rule that api-reference pages be frontmatter-only. Add the Sites endpoints to a spec file under api-reference/openapi/ and expose them via frontmatter-only pages instead of burying the contract in prose.</comment>

<file context>
@@ -423,6 +423,17 @@
+          {
+            "group": "Sites",
+            "pages": [
+              "api-reference/sites/overview"
+            ]
+          }
</file context>

[cubic-dev-ai]

P3: The GET /api/sites/{id}/signups row caps results at 10,000 but never says what happens beyond that. A site with more signups returns incomplete data, and readers cannot tell whether the response is silently truncated, ordered, or paginated. State the cutoff behavior (e.g., which 10,000 are returned and whether pagination exists) so consumers do not silently export a partial list.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/sites/overview.mdx, line 25:

<comment>The `GET /api/sites/{id}/signups` row caps results at 10,000 but never says what happens beyond that. A site with more signups returns incomplete data, and readers cannot tell whether the response is silently truncated, ordered, or paginated. State the cutoff behavior (e.g., which 10,000 are returned and whether pagination exists) so consumers do not silently export a partial list.</comment>

<file context>
@@ -0,0 +1,79 @@
+| `PATCH /api/sites/{id}` action `generate` | `generate_site` | Updated private draft |
+| `PATCH /api/sites/{id}` action `publish` | `publish_site` | Saved draft becomes public |
+| `PATCH /api/sites/{id}` action `unpublish` | `unpublish_site` | Public snapshot removed, draft retained |
+| `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 |
+| `POST /api/sites/assets` | `upload_site_asset` | `{ asset: { url, name, type } }` |
+
</file context>

Suggested change

	| `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 |
	| `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to the 10,000 most recent (no pagination) |

[cubic-dev-ai]

P3: The text above this body says to "Read the returned site.id and site.revision", then the example hardcodes revision: 0. A reader who follows the instruction gets a revision that may not be 0, which makes the example look stale. Use a placeholder consistent with the publish example's CURRENT_REVISION.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/sites/overview.mdx, line 48:

<comment>The text above this body says to "Read the returned `site.id` and `site.revision`", then the example hardcodes `revision: 0`. A reader who follows the instruction gets a revision that may not be 0, which makes the example look stale. Use a placeholder consistent with the publish example's `CURRENT_REVISION`.</comment>

<file context>
@@ -0,0 +1,79 @@
+```json
+{
+  "action": "generate",
+  "revision": 0,
+  "instruction": "Build a maze game with touch and keyboard controls."
+}
</file context>

[cubic-dev-ai]

P3: This page names the Privy token placeholder YOUR_PRIVY_ACCESS_TOKEN, but authentication.mdx (the canonical auth page) uses YOUR_PRIVY_JWT for the identical header. Align the placeholder so readers searching for the token name get one spelling.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/sites/overview.mdx, line 10:

<comment>This page names the Privy token placeholder `YOUR_PRIVY_ACCESS_TOKEN`, but `authentication.mdx` (the canonical auth page) uses `YOUR_PRIVY_JWT` for the identical header. Align the placeholder so readers searching for the token name get one spelling.</comment>

<file context>
@@ -0,0 +1,79 @@
+
+## Authentication
+
+Private HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`.
+MCP uses the existing authenticated `https://api.recoupable.dev/mcp` connection.
+
</file context>

Suggested change

	Private HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`.
	Private HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_JWT`.