docs(api): document Phase 2 endpoints and reindex flow#106
Conversation
…OCS-009)
api.md was stale at Phase 1. Adds the endpoints that shipped since, each with
scopes, a curl example and request/response schemas:
- reindex: POST /api/v1/reindex, GET /api/v1/reindex/{job_id}/status, plus the
end-to-end operator flow (trigger, poll, verify chunks_reindexed, switch
VEKTRA_ACTIVE_INDEX_VERSION, clean up the old version)
- conversations: GET and DELETE /api/v1/conversations/{id}
- feedback: response-level and citation-level
- analytics: GET /api/v1/traces, /api/v1/traces/{response_id}, /api/v1/metrics
- admin: GET /api/v1/admin/conversations/{id}/turns
- ingest: POST /api/v1/ingest/batch, DELETE /api/v1/documents/batch, and the
granular extract/chunk/embed endpoints
- GET /api/v1/health (vector store health, distinct from GET /health)
chunks_reindexed gets the emphasis it earned: before BUG-023 a reindex could
write zero chunks and still report "completed", so an operator polling status
alone could switch the active version to an empty index. The doc makes checking
it the gate before the switch.
The flow was verified against the dev stack rather than transcribed: a real
reindex of the default namespace reported 12 chunks reindexed, Qdrant showed 12
new points at version 2 with version 1 untouched, and live search kept serving
the old version throughout.
Corrects four doc/code discrepancies found while writing:
- GET /admin is a 308 redirect to a cookie-authenticated HTMX UI, not a
Bearer-authenticated dashboard
- GET /api/v1/stats accepts any scope, not query
- the API-key request body accepts expires_at
- reindex, conversations and admin turns return {"detail": ...}, not the REQ-010
envelope the doc presented as universal
Files DEBT-032 (no cleanup path for an old index version: reindex doubles
storage and the only way back is a hand-written store-level delete) and
DEBT-033 (the error-envelope gap).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 46 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe API reference adds health, ingestion, deletion, conversation, feedback, reindex, analytics, and admin endpoint documentation. It also updates API-key and statistics contracts and documents multiple error-response formats. ChangesAPI Reference Expansion
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the backlog and API reference documentation to mark the Phase 2 API endpoints documentation task (DOCS-009) as completed. It documents several new endpoints and flows, including the active vector store health check, batch ingestion and deletion, granular pipeline stages, conversation metadata and soft-deletion, feedback rating, reindexing, analytics traces and metrics, and decrypted conversation turns. It also documents known gaps such as the manual index cleanup process (DEBT-032) and endpoints bypassing the standard error envelope (DEBT-033). The reviewer suggested updating the JSON response example for the admin conversation turns endpoint to show null values for model, prompt_tokens, and completion_tokens to accurately reflect the current implementation.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
…eturns (review) The example populated model, prompt_tokens and completion_tokens while the note right below it said those three are always null (DEBT-012) — the example was the invented half. Confirmed against the dev stack: a real turn returns null for all three. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 participant
Summary
Closes DOCS-009.
docs/reference/api.mdwas stale at Phase 1: everything shipped since was missing, including the reindex endpoints, which are an operator-facing workflow with a manual index-version switch and were not documented at all.Documentation only. No code changes.
Endpoints added
Each with required scopes, a curl example, and request/response schemas.
POST /api/v1/reindex,GET /api/v1/reindex/{job_id}/status+ end-to-end operator flowGETandDELETE /api/v1/conversations/{id}POST /api/v1/feedback/{response_id},POST /api/v1/feedback/citation/{citation_id}GET /api/v1/traces,GET /api/v1/traces/{response_id},GET /api/v1/metricsGET /api/v1/admin/conversations/{id}/turnsPOST /api/v1/ingest/batch,DELETE /api/v1/documents/batch, granularextract/chunk/embedGET /api/v1/health(vector store health, distinct fromGET /health)The
/learn/*surface listed in the backlog entry turned out to be already documented.The part that matters:
chunks_reindexedBefore BUG-023, a reindex in Qdrant mode read chunks from an empty Postgres table, wrote nothing, and still reported
completed. An operator pollingstatusalone would have switchedVEKTRA_ACTIVE_INDEX_VERSIONto an empty index.The doc therefore makes
chunks_reindexedthe gate, not an afterthought: the flow is trigger → poll → verifychunks_reindexedagainst the chunk count you started with → switch → clean up. A completed job that reindexed 0 chunks over a non-empty namespace is documented as a bug, not a no-op.Verified, not transcribed
The reindex flow was run against the dev stack rather than read off the source:
defaultnamespace (3 docs / 12 chunks) to version 2 → job reportedchunks_reindexed: 12index_version=2, with the 12 at version 1 untouched/api/v1/statskept serving version 1 throughout (zero-downtime holds)The 400 (target == active version) and 404 (unknown job) responses in the doc are real responses, not guesses.
Discrepancies corrected
Found by checking the doc against the code:
GET /adminis a 308 redirect to a cookie-authenticated HTMX UI (ADR-0024). The doc described a Bearer-authenticated HTML dashboard and gave a curl for it.GET /api/v1/statsaccepts any valid scope (require_scope(None)), notquery.expires_at; it was undocumented.{"detail": "..."}, while the doc stated that all errors follow the REQ-010 envelope. Both shapes are now documented, with the bare form flagged as a gap rather than a contract.Gaps filed
reindex.py's docstring promises a cleanup trigger that does not exist. The doc ships the manual procedure with the warnings it needs; the procedure should not be manual.Quality gate
make lintclean (ruff, mypy, import-linter: 8 contracts kept)make test: 755 passed, 3 skipped🤖 Generated with Claude Code
Summary by CodeRabbit