docs(api): document GET /v1/usage usage-metrics endpoint - #103
Merged
Merged
Conversation
Add the public usage-metrics endpoint to the Scalar-rendered OpenAPI spec and the quickstart guides: - openapi.json: /usage path with start_date/end_date/cursor/limit params, UsageReport/UsageRow/UsageTotals/UsageModelTotals/UsageAllTime schemas, worked example, inline 400 (window > 90 days never clamped, start>end, malformed dates, invalid cursor), 401 and 429 (Retry-After, 30 rpm budget) responses; 'Usage' tag; rate-limits note in info.description. - openapiSpec.test.ts: PUBLIC_SURFACE tripwire extended (10 -> 11 routes, /usage added) — updated first, observed RED against the unmodified spec, GREEN after. - getting-started.mdx (EN) and getting-started.mdx (ES): 'Usage metrics' section with a curl example, window cap and cursor pagination notes. openapiToText and resolveSpec needed no changes (generic renderer over paths/tags/params/schemas; canonicalParity test confirms the Discord bot text stays a fixed point). Validation: npx vitest run — 66 files / 1294 tests green; npm run build green.
Review-driven accuracy pass on the /usage documentation: - UsageReport: document the new top-level start_date/end_date (the EFFECTIVE served window after clamping) in schema and examples. - UsageAllTime: add api_requests. - cursor param: a MALFORMED cursor returns 400; a well-formed cursor only positions the page (previous text wrongly said 'unknown cursor returns 400'). - limit param: out-of-range values are server-clamped into 1-500 and non-numeric values fall back to 100. - start_date param: document future-date clamping to today. - 400 description quotes the new backend messages verbatim (window span + remedy, next_cursor hint); 404/409/500 responses documented in the file's existing style. - openapiSpec.test.ts: new contract tests pinning envelope order, all_time shape, param semantics, error wording and 404/409/500 (written first: 8 failed against the previous spec, then green). - getting-started guides (EN/ES): one parity sentence on the echoed effective window. Validation: vitest 66 files / 1303 tests green; npm run build green.
Request counts only exist from the usage-hook cutover (2026-09-02); older days report 0. Every api_requests description (row, window totals, per-model totals, all-time) now states this so tokens-per- request math in third-party tools does not silently lie for members active before the cutover. Also: 404 description now lists the actual identity resolution sources (API key, Discord link, handle); 400 description covers the malformed account identity case (param null); new spec test pins the caveat on all four api_requests fields.
6 tasks
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.
Tracking issue
#102
Summary
GET /v1/usageendpoint (shipped inhelmcode/nan-cloud-api) in the Scalar-rendered OpenAPI reference and the getting-started guides (EN/ES).PUBLIC_SURFACEtripwire test was extended FIRST (observed RED against the unmodified spec), then the spec was written to green; a dedicated/usage contractdescribe block pins envelope order, param semantics, error wording, and the api_requests cutover caveat field-by-field.Changes
src/data/openapi.json/usagepath: params (start_date/end_date/cursor/limit with clamping semantics), UsageReport/UsageRow/UsageTotals/UsageModelTotals/UsageAllTime schemas, worked example, 200/400/401/404/409/429/500 responses,Usagetag, rate-limits notesrc/lib/openapiSpec.test.ts/usage); new contract tests (echo window, api_requests caveat on all four schemas, malformed-cursor wording, limit clamping, verbatim error messages, 404/409/500)src/lib/apiDoc.tssrc/content/docs/getting-started.mdxsrc/content/docs-es/getting-started.mdxTest plan
npm test— 66 files / 1304 tests green (tripwire RED observed before the spec landed)npm run build— greencanonicalParity+docsNavsuites confirm the Discord bot text and docs navigation stay fixed points over the new specDeploy notes