Repository navigation
Spec is missing live Data API endpoints and params #2
Description
Summary
openapi/data-api.yaml (and .json) does not describe everything api.seranking.com serves today. Every path in the spec is live. But several live Data API endpoints are missing, and so is one pair of query params on an endpoint that is in the spec.
I compared the spec on main (a40f856, after #1) with the routes the Gateway serves in production, and with the public Postman "Data API" collection. Checked on 2026-10-14.
1. Missing, and customers call them
| Endpoint | In Postman? | What it is |
|---|---|---|
GET /v1/account/credits |
no | The full credit picture: access status, credit_expire_at, subscription / add-on / wallet totals and buckets (DAT-527). It replaces /v1/account/subscription and /v1/account/credit-balance, which are the only two /v1/account/* endpoints in the spec. It is one of the most-called endpoints. |
GET /v1/ai-search/overview/aggregated/current |
yes | AI Search overview, aggregated across engines, current period |
GET /v1/ai-search/overview/by-engine/current |
yes | AI Search overview per engine, current period |
The spec has the two …/time-series siblings, but not these two …/current endpoints.
2. Missing query params
GET /v1/domain/keywords has no year and month params in the spec. Postman has them. They return the domain's keywords for a past month, and customers use them.
3. Shipped recently, not added to the spec
| Endpoint | Ticket | Note |
|---|---|---|
GET /v1/site-audit/audits/resources |
DAT-835 | Live since late September. Same audit_id pattern as /audits/pages. |
POST /v1/serp/geo/prompts |
— | "Generate prompts". In Postman since 2026-09-15. |
4. Decide: document them, or keep them out on purpose
| Endpoint | Question |
|---|---|
GET /v1/account/info, GET /v1/account/usage |
Registered and called. Are they meant for customers? |
GET /v1/account/wallet, GET /v1/account/wallet-transactions |
Older wallet reads, replaced by /v1/account/credits. Document them with deprecated: true, or leave them out? |
POST /v1/domain/keywords/history |
The Gateway sends a past-month GET /v1/domain/keywords here. A client can also call it directly. Document it, or treat it as internal? |
Other /v1/serp/geo/* methods |
Add them when they are released. |
5. Probably fine to leave out (older endpoints and aliases)
Leave these out, or add them with deprecated: true so client generators warn about them:
GET /v1/serp/tasks,POST /v1/serp/tasks,GET /v1/serp/tasks/status: the older SERP API, replaced by/v1/serp/classic/*. Some clients still call them.GET /v1/domain/overview: replaced by/overview/dband/overview/worldwide.GET /v1/ai-search/overview: an alias of/overview/by-engine/time-series.HEAD /v1/serp/classic/tasks/html.
6. Retired, so correctly not in the spec
/v1/domain/aio/overview,/keywords-by-targetand/keywords-by-brandnow return410 Gone, which names the/v1/ai-search/*method that replaces each one (DAT-898).GET /v1/ai-search/overview/aggregated(without/currentor/time-series) now returns 404 (DAT-898).
7. Out of scope for this file
The Project API (/v1/project-management/*), Local Marketing (/v1/local-marketing/*) and SE Visible (/v1/se-visible/*, which has its own reference) are separate products. They could each get their own spec file later.
Suggested next steps
- Add the endpoints in sections 1 and 3 and the params in section 2. Update both YAML and JSON, because CI checks that they match.
- Decide the rows in section 4. Then either document each one or note why it stays out.
- When a ticket adds or changes a public
/v1/*endpoint, update this spec in the same piece of work.audits/resources(DAT-835) shipped without a spec change.
🤖 Co-authored with Opus 5.5 via Claude Code
Activity