mirror of
https://github.com/langchain-ai/docs.git
synced 2026-07-18 16:04:43 -04:00
Lauren Hirata Singh
e64690f7ff
## Why The LangSmith Platform OpenAPI spec mixes v1 and v2 endpoints in one file, and the backend already tags v2 operations by resource (`runs`, `datasets`, `threads`). This reworks how the reference presents them so a v2 endpoint sits with its v1 sibling and is easy to spot, and cleans up inconsistent endpoint titles across the whole reference. All changes are driven by `scripts/process_langsmith_openapi.py` (which runs on every spec sync), so they re-derive automatically and need no manual upkeep. ## What changed - **Group v2 by resource.** Stop collecting v2 endpoints in a separate bucket; let their backend resource tags place them alongside v1 (e.g. runs → Tracing), each marked `(v2)`. - **Match v1/v2 wording.** Paired endpoints now read identically via canonical-title overrides: "Query runs" / "Query runs (v2)", "Read run" / "Read run (v2)", "Share run" / "Share run (v2)". - **Sentence-case every title,** preserving an acronym/proper-noun allowlist (`API`, `AWS`, `SCIM`, `TTL`, `OAuth2`, `URL`, `WebSocket`, …). - **Normalize markers:** `[Beta] X` becomes `X (Beta)`, and trailing `X V2` becomes `X (v2)`. - **Threads** moved into its own group. ## Relationship to `main` This **supersedes the earlier "v2 endpoints" bucket approach** already on main — an intentional flip to resource-based grouping after reviewing how v2 actually spreads across resources. ## Please review carefully - **`V2_TITLE_OVERRIDES`** in the script — the three canonical titles are explicit, because the v1/v2 equivalence is semantic and even crosses HTTP methods (POST "Share a run" ≈ PUT "Share Run"), so it cannot be auto-inferred. New matching pairs get added here. - **`TITLE_PRESERVE`** acronym allowlist — anything missing gets lowercased; anything wrong gets over-preserved. - The large `langsmith-platform-openapi.json` diff is fully generated output; the script is the source of truth. ## Known limitation Within a resource group the v2 endpoints cluster together rather than each sitting directly beside its v1 twin. Mintlify sorts endpoints within a group by path, which cannot be overridden through the spec. Literal adjacency would require script-generated navigation, deferred by decision. ## AI involvement Authored with Claude Code (investigation, script changes, and spec regeneration); reviewed by @lnhsingh. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>