docs: add API v2 reference and split api-reference into v1/v2 - #303
Open
sriramveeraghanta wants to merge 4 commits into
Open
docs: add API v2 reference and split api-reference into v1/v2#303sriramveeraghanta wants to merge 4 commits into
sriramveeraghanta wants to merge 4 commits into
Conversation
Adds the full Plane API v2 reference and restructures /api-reference/ into explicit version folders, with v2 positioned as the current, recommended API. Structure - Move the existing 270 v1 pages to docs/api-reference/v1/ (git-tracked renames) - Add docs/api-reference/v2/ with 115 pages: 88 endpoint pages covering every v2 operation, 19 resource overviews, and 8 concept guides - Nav becomes a version switcher: v2 (latest) / v1 (legacy) - Rewrite 284 internal links to the versioned paths Routing - /api-reference and /api-reference/introduction now land on v2 - Legacy deep links fall through to their v1 equivalents via a ((?!v1/|v2/).*) catch-all ordered after the specific legacy redirects, so previously indexed URLs keep working - docs/api-reference/index.md covers `pnpm dev`, where vercel.json redirects do not run - Widen the theme's api-page layout check so v2 prose guides keep the standard doc layout Coverage - Work items (incl. archive/unarchive and PROJ-123 identifier lookup), comments, states, labels, cycles, modules - Work item types, custom properties, property options and property contexts, at both project and workspace level, plus the mode-gating rules - Workspace features, members, audit logs, users/me - Concept guides: authentication and OAuth scopes, pagination, filtering and ordering, expanding relations, RFC 9457 errors, type modes, and a v1->v2 migration guide Pages were verified against the committed OpenAPI golden file for parameter names, types, enums, required flags, scopes and status codes, and against the api_v2 source where the schema under-describes actual behavior. Claude-Session: https://claude.ai/code/session_01J8k8wr7tWTXcAGKsprAYyq
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedToo many files! This PR contains 743 files, which is 643 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. Usage-priced reviews support at most 300 files. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (743)
You can disable this status message by setting the ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
The header "API Reference" link now goes straight to v2. Version switching lives at the top of the API reference sidebar, and selecting a version swaps the whole sidebar tree via the existing path-prefix keys. Implemented as two links rather than a <select>: Vue's SSR drops `selected` on options inside a bound select, so a dropdown renders the wrong version before hydration and does not work at all without JS. Links are correct on first paint and degrade cleanly. - Add ApiVersionSwitcher.vue, injected through the sidebar-nav-before slot; it hides itself outside /api-reference/ - Header nav: dropdown -> single link to /api-reference/v2/introduction - Drop the now-redundant version suffixes from sidebar group titles Claude-Session: https://claude.ai/code/session_01J8k8wr7tWTXcAGKsprAYyq
5 tasks
…contract, 295 endpoints
Brings the v2 reference up to date with the API v2 OpenAPI document. The PR's
original 88 pages were accurate for the 2026-07-24 surface; the spec has since
grown to 383 operations and the response/error contract was rebuilt.
Verified against the committed spec: 383/383 operations have a page with the
correct method badge and exact path, no orphans, no duplicate coverage.
Sparse fields (?fields=)
- new concept page: omit-not-null semantics, the `all` token, deferred_on_list
and detail_only, strict 400 with did-you-mean, orthogonality with ?expand=
- "Response shaping" section on the 69 existing pages where the spec declares
the parameter, each enumerating that operation's own requestable fields
- the 20 pages that legitimately lack it (APIViews, Lite serializers, bulk
envelopes) documented as exceptions rather than silently omitted
- custom_fields corrected: absent on collection rows, not null, and a 400 if
requested there; populated on every single-object response including the
archive verbs
Alias removal
Aliasing landed and was removed after this PR was opened, so nothing needed
deleting — but its replacements were undocumented:
- identity-filter matrix (?name= on 28 resources, ?key=, ?url=, ?value=,
?version=, ?title=, external_id/external_source)
- the three bare stable keys: workspace slug, project identifier on detail and
parent segments, work item PROJ-123
- warning that <scheme>: path segments now 404 as unknown ids
Error contract
- errors.md rewritten: {type, code, detail} + errors[]; status/title removed;
type is a closed 13-value category, not a URI; per-field code in errors[]
- code renames swept across the tree: resource_not_found -> not_found,
validation_error -> invalid_request, internal_error -> server_error
(84 JSON bodies, 193 inline references)
- 284 missing status rows added (402/406/413/415) from the spec's declared
responses, preserving every hand-written cause
- new 402 payment_required section for feature-gated surfaces
Other corrections found against the spec
- ?expand= was declared on 23 pages but documented on 3, and those 3 omitted
cycle and modules; expanding-relations claimed two resource families when it
is 15, and claimed the parameter was absent from the schema (it is enumerated)
- migrating-from-v1 said "There is no ?fields= in v2"
- authentication listed 27 of 97 OAuth scopes
- endpoint tables in the 7 pre-existing overviews were missing upsert/bulk rows
New coverage — 295 operations, 47 resource overviews
automations, releases, workflows, customers, estimates, initiatives, group
sync, templates, assets, pages, collections, projects, views, milestones,
webhooks, intake, invitations, stickies, teamspaces, relations, dependencies,
worklogs, attachments, links, activities, roles, permissions and more; sidebar
regenerated from the page tree (458 links, one per page).
Build
vitepress build now exceeds the default Node heap at 819 rendered pages, so the
build script pins --max-old-space-size=8192. check:types, check:format and
vitepress build (which fails on dead links) all pass.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…e committed spec
Running `check_v2_schema_drift --check` on preview reports additive drift: the
committed openapi/ document is missing the artifacts resource entirely. #8770
regenerated the spec at 17:56 on 2026-08-06, before the Applets commits (#8567,
#8758) were in its tree, so the regen never saw those routes. Nothing has
touched api_v2 since, so this is the only gap.
Real surface is 387 operations, not the 383 the committed spec describes.
Added (hand-written — this surface has enough quirks that generating it would
have been wrong):
- artifacts/overview.md, create, get, update (append a version), publish
- workspaces.artifacts:read / :write in authentication.md (97 -> 99 scopes)
- artifacts noted in the sparse-fields APIView exclusion list
- sidebar entry under Workspace & Admin
Coverage against the regenerated spec: 387/387 operations, 99/99 scopes, no
orphans. check:types, check:format and vitepress build all pass.
Documented with the constraints stated plainly, because this is not a general
integration surface: the view docstring scopes it as a POC for Plane
Intelligence's generate-then-host flow, it is gated behind FeatureFlag.APPLETS
(402 when off), and AppletPermissions restricts it to workspace admin/owner for
reads as well as writes. There is no list, no delete, no older-version read and
no unpublish, and each page says so.
Three code/schema mismatches found while writing these, documented as the code
behaves and flagged for the API team rather than papered over:
1. create returns 201, the schema declares 200 (`@extend_schema(responses=...)`
with no explicit status defaults drf-spectacular to 200)
2. publish returns 201 likewise, including on a repeat call where get_or_create
created nothing
3. the html-missing and data_mode-invalid failures return a bare
`{"detail": "..."}` via `Response(...)` rather than problem+json, bypassing
`problem_exception_handler` — so `problem.code` is absent on those 400s
even though the schema declares ValidationProblemDetail
The spec regen itself is a backend change and is deliberately NOT in this
commit; plane-ee needs its own PR running `check_v2_schema_drift --write`.
Note the drift gate is not wired into CI, so this went unnoticed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.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
2 participants
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.
Adds the full Plane API v2 reference and restructures
/api-reference/into explicit version folders, with v2 positioned as the current, recommended API.What changed
Structure
docs/api-reference/v1/— git-tracked as renames, so history is preserveddocs/api-reference/v2/with 115 pages: 88 endpoint pages (every v2 operation), 19 resource overviews, 8 concept guides<select>: Vue's SSR dropsselectedon options inside a bound select, so a dropdown would render the wrong version before hydration and wouldn't work at all without JSRouting — the unversioned entry point lands on v2, and no previously indexed URL 404s:
/api-reference/api-reference/v2/introduction/api-reference/introduction/api-reference/v2/introduction/api-reference/issue/overview(legacy deep link)/api-reference/v1/issue/overviewThe legacy catch-all is
/api-reference/:path((?!v1/|v2/).*), ordered after the specificcycle-issue/module-issueredirects so those still win.docs/api-reference/index.mdcoverspnpm dev, wherevercel.jsonredirects don't run.Coverage
PROJ-123identifier lookup), comments, states, labels, cycles, modulesusers/meHow accuracy was established
The OpenAPI golden file (
openapi-v2.json) was resolved into per-operation specs, and every page checked against them for parameter names, types, enums, required flags, scopes and status codes. A verification pass then re-checked each page adversarially. Automated check: 88/88 operations have a page with the correct method badge and exact path; sidebar and disk agree at 115 ↔ 115 with no orphans.check:types,check:format, andvitepress buildall pass, with no dead links.Follow-ups for the API team (not addressed here)
The schema under-describes actual behavior in four places. The docs follow the source; the schema is what needs fixing:
?expand=is implemented (core/views.py_expand()) but declared on no operation. Only work items (state,type,parent,assignees,labels) and members (member) support it.?cursor=is a real parameter (core/views.py:192) but undeclared.200/401/403/404/429, yet genuinely return400for invalid filter enums andordering_not_cursor_eligible.AuditLog.project_idis nullable in the model but the schema omitsnullable: true.Also worth noting for anyone reading the source docs:
order_byandpaginateare not validated — an unknown value silently falls back (OrderingSpec.resolve(),views.py:192) — while filter enums backed by aChoiceFilter(choices=…)genuinely do return400. The pages distinguish these two cases per resource. Separately,docs/api_v2/API_USAGE.mdinplane-eehas a stale endpoint catalog (no types, properties, features, or audit logs).Review notes
Two judgment calls worth a look:
/api-reference/introductionsends readers to v2 rather than v1, treating it as the versionless front door. Easy to flip if you'd rather it stay on v1.?expand=is documented despite its absence from the schema, since the code supports it.https://claude.ai/code/session_01J8k8wr7tWTXcAGKsprAYyq