docs: add Elementary Public API (beta) reference - #2329
Merged
Conversation
Adds a new "API Reference" tab to the docs site covering the beta Elementary Public API: - Guides: introduction, authentication, pagination, incremental sync, rate limits, errors, versioning. - Endpoints: auto-rendered from a committed OpenAPI snapshot (api-reference/beta/openapi.json) — Environments, Assets (incl. typed table/BI endpoints and asset lineage), Columns (incl. column lineage). The OpenAPI snapshot is a one-time manual copy from elementary-internal (generated by apps/api/scripts/generate_external_openapi.py). A follow-up will automate keeping it in sync via a cross-repo bot PR gated on the beta API deploy. Co-authored-by: Cursor <cursoragent@cursor.com>
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Comment |
The API Reference tab bound the OpenAPI spec at the tab level
("openapi": ...), which makes Mintlify auto-generate a page per
operation (grouped by tag) *in addition to* the curated stub pages —
so every endpoint showed up twice in the nav.
Remove the tab-level binding and instead resolve each endpoint from its
MDX stub's frontmatter, qualified with the spec file path
(openapi: api-reference/beta/openapi.json <method> <path>). This keeps
the curated structure (asset lineage under Assets, column lineage under
Columns) with no auto-generated duplicates.
Co-authored-by: Cursor <cursoragent@cursor.com>
The root .gitignore's `env*/` rule (for Python virtualenvs) also matched docs/api/reference/environments/, so list-environments.mdx was silently excluded from the commits even though docs.json references it — the page would 404 on deploy. Force-add the file so it ships with the PR. Co-authored-by: Cursor <cursoragent@cursor.com>
The intro only had a soft note ("shape may change") and the versioning
page actively encouraged building against beta. Neither said the API is
in active development and not meant for production.
- Intro: promote the beta note to a Warning stating the API is in active
development, not intended for production, may have breaking changes,
and has no availability/stability/support guarantees.
- Versioning: reword the recommendation to frame beta as pre-production
rather than nudging production adoption.
Co-authored-by: Cursor <cursoragent@cursor.com>
The base URL advertised the web-app host (app.elementary-data.com/api), but the API is served by the FastAPI backend at prod.api.elementary-data.com (verified: every dataset returns 200 at https://prod.api.elementary-data.com/public/beta). Fix the OpenAPI `servers` snapshot and the guide URLs (introduction + authentication). Co-authored-by: Cursor <cursoragent@cursor.com>
The auth page said personal/account tokens are "accepted" but never explained how to create one or the difference between them. Add a "Creating a token" section linking to User → Personal Tokens and Account → Account Tokens, describing the scope of each and the show-once / secret-handling guidance. Co-authored-by: Cursor <cursoragent@cursor.com>
The token cards described each type's scope but the "when to choose" tradeoff was only implicit. Add a short section contrasting personal tokens (interactive, tied to your account lifecycle) with account tokens (long-lived/shared, survive team changes) so the API docs are self-sufficient. Co-authored-by: Cursor <cursoragent@cursor.com>
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.
Summary
Adds an API Reference tab to the docs site for the beta Elementary Public API, rendered from a committed OpenAPI snapshot.
docs/api/*.mdx): introduction, authentication, pagination, incremental sync, rate limits, errors, versioning.docs/api/reference/**, bound todocs/api-reference/beta/openapi.json):docs/docs.json): one new tab inserted between Python SDK and Elementary OSS (49-line insertion, no other changes). Branding (pink#FF20B8,minttheme) is inherited automatically.How it was produced
The OpenAPI snapshot is a one-time manual copy from
elementary-internal, generated byapps/api/scripts/generate_external_openapi.py. Verified byte-identical to a fresh regeneration from the API branch tip (11 operations, title "Elementary Public API", version "beta").Follow-up (not in this PR)
Automate keeping the snapshot fresh: an
elementary-internalCI job regeneratesopenapi.jsonand opens a cross-repo bot PR into this repo, gated on the beta API deploy so beta docs go live only when the API ships. Until then the snapshot must be regenerated manually when the beta surface changes (a--checkdrift guard already exists on the API side).Validation
mint openapi-check/ pre-commit Mintlify validate: spec valid ✔docs.jsonparses; tab order correct ✔Test plan
cd docs && mint dev— confirm the API Reference tab renders, guides load, and endpoint pages populate (not just titles)mint broken-links)Made with Cursor