feat: API versioning and migration docs (runs endpoint v1 to v2) - #1
Open
ericdong-langchain wants to merge 1 commit into
Open
feat: API versioning and migration docs (runs endpoint v1 to v2)#1ericdong-langchain wants to merge 1 commit into
ericdong-langchain wants to merge 1 commit into
Conversation
- Add API versioning and support policy (endpoint-deprecation) - Add API v1 vs v2 overview (api-v1-v2-overview) - Add step-by-step migration guide (endpoint-migration) - Update docs.json with API versioning group and nav
| | **Get run** | `GET /api/v1/runs/{run_id}` (optional query params) | `GET /v2/runs/{run_id}` | Add **required** query params: `session_id`, `start_time`. Map v1 exclude/include to v2 `select` (allowlist). `session_id` and `start_time` required in v2; response field renames (e.g. `extra`→`metadata`, `error`→`error_preview` when using select). | | ||
| | **Query runs** | `POST /api/v1/runs/query` | `POST /v2/runs/query` | Rename body: `start_time`→`min_start_time`, `end_time`→`max_start_time`. Keep `session` (required). No `cursors.prev` in v2; cursor format is predicate-style; `select`/`order` UPPERCASE; `trace_min_max_start_time` and `feedback_stats` not supported. | | ||
| | **Get trace runs** | `GET /api/v1/traces/{trace_id}/runs` | `GET /v2/traces/{trace_id}/runs` | Add **required** query params: `session_id`, `min_start_time`, `max_start_time`. Same select/response renames as query runs. | | ||
| | **Delete runs** | `POST /api/v1/runs/delete` (metadata or session_id + trace_ids) | `POST /v2/runs/delete` | Send only `session_id` and `trace_ids` in body. Metadata-based delete is not supported in v2; resolve to (session_id, trace_ids) via a query if needed. | |
There was a problem hiding this comment.
user's shouldn't call v2/runs/delete endpoint directly as it does not handle clickhouse deletes
Owner
Author
There was a problem hiding this comment.
Will remove, potentially add later
| You can see which API version your project uses by: | ||
|
|
||
| 1. **API request logs**: Review your application logs or API monitoring tools for the endpoint paths and version prefixes in your requests. | ||
| 2. **Code review**: Search your codebase for versioned endpoint paths (`/api/v1/` or `/v2/`). |
There was a problem hiding this comment.
for ingest no changes are needed, all routing is handled at the API layer, the user shouldn't have to think about which api to call
|
|
||
| Only certain SDK versions support the runs API in the `/v2` namespace. Use a v2-capable version to call v2 endpoints; older versions use v1 only. | ||
|
|
||
| | SDK | Minimum version for v2 | |
There was a problem hiding this comment.
i think this is the main point worth fleshing out, what sdks are compatible. Generally all users should strive to use the most up to date sdk anyways, but they shouldn't have to think about what API to call
|
|
||
| ## List Pagination | ||
|
|
||
| List-style responses (for example, from `POST /runs/query`) use cursors for pagination. v1 and v2 differ in how cursors are returned, how they are formatted, and what request options are available. |
There was a problem hiding this comment.
query is probably the only real api change here worth noting, for ingest we can just say we will deprecate sdk versions 0.x.x after x date
angus-langchain
approved these changes
Feb 12, 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.
Overview
Type of change
Type: [Replace with: New documentation page / Update existing documentation / Fix typo/bug/link/formatting / Remove outdated content / Other]
Related issues/PRs
Checklist
docs devsrc/docs.jsonif needed(Internal team members only / optional): Create a preview deployment as necessary using the Create Preview Branch workflow
Additional notes