docs(usage-api): add Usage API reference via remote spec (blocked on dashboard#8050)#1403
docs(usage-api): add Usage API reference via remote spec (blocked on dashboard#8050)#1403lohnim wants to merge 3 commits into
Conversation
Vendors the Usage API OpenAPI spec (GET /v1/usage/summary,
POST /v1/usage/time-series) into src/openapi/usage-api and wires it into the
Admin API nav section as "Usage API Endpoints", mirroring how the Admin API
("Apps API") endpoints are surfaced.
The spec is vendored locally for now because usage-api.alchemy.com is not yet
serving its /openapi.yaml publicly; once it is, this can switch to a
content/remote-specs.json entry (like admin-api) for auto-sync.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🔗 Preview Mode
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eb40c4989c
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
The Usage API is path-routed (`/v1/usage*`) through the Apps API ALB at admin-api.alchemy.com (see terraform aws_alb_listener_rule.admin_api_usage), not served directly at usage-api.alchemy.com. Match the public host (and the sibling admin-api spec's server) so the reference shows the correct base URL. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
| - api: Usage API Endpoints | ||
| api-name: usage-api | ||
| flattened: true |
There was a problem hiding this comment.
Should this actually be under Admin API? I thought it was a separate API entirely
There was a problem hiding this comment.
The Usage API is served under admin-api.alchemy.com (path-routed through the Apps API ALB via /v1/usage*), so nesting it beneath the Admin API in docs.yml matches where it actually lives operationally — even though it's a logically distinct product surface. If we'd rather present it as its own top-level API in the docs nav, that's an easy reshuffle into a separate section. Deferring to your preference on the nav structure; happy to split it out if you'd like.
Per the sync-docs-as-code pattern, register the Usage API spec as a remote entry (served at https://admin-api.alchemy.com/v1/usage/openapi.json) and remove the vendored src/openapi/usage-api/ copy. content/docs.yml already references api-name: usage-api; the remote entry now supplies it. Blocked: merge only after the dashboard change serving the spec at that URL deploys (OMGWINNING/dashboard#8050) — CI lints the live URL. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
lohnim
changed the title
3 participants
Summary
Adds the Usage API reference under the Admin API section, using a remote spec (the
sync-docs-as-codepattern) — not a vendored copy.content/remote-specs.json: registersusage-api→https://admin-api.alchemy.com/v1/usage/openapi.json(the Usage API is path-routed through admin-api; spec served by the service itself).content/docs.yml:Admin APIsection now includes "Usage API Endpoints" (api-name: usage-api), alongside "Admin API Endpoints".src/openapi/usage-api/copy — single source of truth is the generated, hosted spec.The spec URL goes live only after the dashboard change serving it deploys: OMGWINNING/dashboard#8050 (
feat(usage-api): docs enablement (CORS + public OpenAPI spec route)). The docs build lints the live URL, so this PR's CI will fail until that ships. Merge after #8050 is deployed.Verified now:
validate:docs-yml✅ (theusage-apiapi-nameresolves to the remote entry),remote-specs.jsonis valid JSON.Follow-up
Wire a
repository_dispatch(remote-spec-updated) into dashboard CI so docs auto-refresh when the spec changes — needs theSYNC_DOCS_AS_CODEapp secrets from the DX team.🤖 Generated with Claude Code