docs(api): use /api/v2 in docs and examples, demote v1 to legacy - #370
Merged
Conversation
1.2.0 introduced /api/v2 as the canonical, cloud-aligned prefix and mounted every business router twice, but the user-facing entry points (README, README.zh-CN, QUICKSTART, the docs/ set, the Langfuse example) still taught /api/v1 — so new users were pointed at the compatibility alias while docs/api.md already declared v2 canonical. - Switch every EverOS endpoint reference in docs, examples, and `everos demo --live` to /api/v2, plus the matching CLI test expectations. - Describe /api/v1 as a legacy compatibility alias that may be removed in a future major release, rather than a permanent one. Nothing changes at runtime: both prefixes still resolve to the same handlers and the v1/v2 parity test is untouched. - Add a short note in README / README.zh-CN / QUICKSTART so existing v1 integrations know they keep working. - Fix the five dead endpoint anchors in the docs/api.md table of contents, which still pointed at the pre-1.2.0 #post-apiv1... slugs. Left on v1 deliberately: docs/migration-to-1.0.0.md (historical record), CHANGELOG history, tests/** (v1 must stay covered), and the use-cases/claude-code-plugin + openher READMEs, which document a different cloud API. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
dani1005
force-pushed
the
docs/promote-v2-prefix
branch
from
July 29, 2026 02:42
b634a34 to
68bedae
Compare
cyfyifanchen
approved these changes
Jul 29, 2026
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.
Why
1.2.0 made
/api/v2the canonical, cloud-aligned prefix and mounts every business router under both prefixes. But the pages a new user actually reads — README, README.zh-CN, QUICKSTART, most ofdocs/, the Langfuse example — still taught/api/v1, whiledocs/api.mdalready declared v2 canonical. The repo was pointing newcomers at the compatibility alias.What
/api/v2: README, README.zh-CN, QUICKSTART,docs/{api,knowledge,multimodal,reflection,everos-demo,how-memory-works}.md,examples/langfuse/{README.md,demo.py},.claude/rules/module-docstring.md.everos demo --live→/api/v2(cli/commands/demo.py+ its unit test), so the flow README describes matches what the CLI calls.docs/api.md, theapp.pymounting comment, the versioning test docstring, and the 1.2.0 changelog entry.docs/api.mdTOC still pointed at pre-1.2.0#post-apiv1…slugs after the headings moved to v2 — all five links were dead.Runtime impact
None. Both prefixes still mount the same routers;
test_api_versioning(the v1/v2 parity guard) is unchanged and passing.docs/openapi.jsonalready carries both prefixes and needs no regeneration.Deliberately left on v1
docs/migration-to-1.0.0.mdand the CHANGELOG history (historical records),tests/**(v1 must stay covered while the alias exists), anduse-cases/claude-code-plugin+use-cases/openherREADMEs, which document a different cloud API (/api/v1/memories/*).Verification
ruff check/ruff format --check— cleanpytest tests/unit/test_entrypoints/test_api/test_api_versioning.py tests/unit/test_entrypoints/test_cli/test_demo_command.py— 10 passedscripts/check_docs.py,check_deprecated_names.py,check_repo_assets.py— passscripts/dump_openapi.py --check— no path drift (only a localversion: 1.2.0.dev1string from the dev install)🤖 Generated with Claude Code