API
The stable legacy API, canonical v2 resources, OpenAPI contracts, and generated client reference.
StatsHub serves two contracts from the same Go service:
the stable legacy /api routes and the redesigned /api/v2 resources. Existing
integrations can remain on /api; new integrations should start with v2.
Legacy API
The stable /api compatibility surface, with its own explorer, schema, and endpoint reference.
API v2
Canonical /api/v2 resources, with a separate explorer, schema, and endpoint reference.
OpenAPI contracts
Combined, legacy-only, and v2-only OpenAPI 3.1 documents for SDK generation and review.
Parity stack
Running both implementations against one database to compare them.
Go against the Next.js routes
Both stacks loaded to 2,048 connections on one box. 39× on requests that miss the database, identical on requests that hit it.
Base URL
| Contract | Base URL |
|---|---|
| Legacy compatibility API | https://statshub.com/api |
| Canonical API v2 | https://statshub.com/api/v2 |
Locally, replace https://statshub.com with http://localhost:8080 after
running pnpm dev:api.
Authentication
Most read endpoints are open. Protected operations resolve a Supabase bearer
token or session through internal/auth. Each version's endpoint reference
marks the requirement: legacy and
v2.
Administrative and webhook authentication
Administrative operations require a configured production superadmin. The
Telegram webhook validates X-Telegram-Bot-Api-Secret-Token and fails closed
when production has no configured secret. Those deliberate security upgrades
are represented in the generated reference.
Responses
On /api, response bodies remain byte-compatible with the legacy routes. On
/api/v2, successful resources use a consistent data envelope and failures
use RFC 9457 Problem Details. API v2 documents pagination and
the concrete envelope shapes.
Treat any non-2xx as a failure and log both the status code and the body before retrying.
Machine-readable
https://statshub.com/api/openapi.json served by the API
https://statshub.com/api/openapi-v2.json focused v2 contract
/openapi.json combined copy published by this site
/openapi-v1.json legacy-only copy published by this site
/openapi-v2.json v2-only copy published by this site
/statshub.postman_collection.json a Postman collection