## 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>
The LangSmith Platform OpenAPI spec mixes v1 and v2 endpoints in one
file. Surface the newer v2 endpoints (runs, traces, threads, datasets,
public share) in a dedicated "New v2 endpoints" sidebar group so readers
notice them, and rename the reference group to "LangSmith REST API".
https://langchain.slack.com/archives/C0ACCE0N6F5/p1783520873705849
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Lauren Hirata Singh