Back in July, I told you the API was almost here. It ended up taking a bit little longer than I expected, which may sound familiar to all the developers out there. In the end, I think it worked out well, as I'd rather ship something solid than ship something on time. So... it's here. The /src namespace is live, and I want to walk you through it, including what things were built along the way that weren't originally on the roadmap. In addition, I'll also mention what's still catching up behind the scenes.

What's Actually Live

/src is exactly what it always was meant to be: a complete, faithful mirror of speedrun.com's public data. There's endpoints for games, categories, levels, runs, users, leaderboards, all of it. If you've been building against speedrun.com's own API and hitting inconsistent responses, missing expected functionality, or the occasional 500, this is your drop-in. Same shapes, same fields, none of the flakiness.

Anonymous requests work today, no account required. Account registration with bearer token support is being prepared for the /v1 namespace launch this fall.

Things We Didn't Plan On Building

Every project picks up a few detours along the way. A few of ours turned into real improvements, which I'd like to take a minute to touch upon:

A Full Query-Layer Rebuild

The original plan for serving filtered/sorted list endpoints turned out not to scale the way we needed, with poor support for combining filters and a rebuild process that meant real downtime. We repointed the whole query layer at ClickHouse instead: every filterable field indexed, no offline rebuilds, glued back with records from Aerospike to ensure millisecond latency at scale.

An Open Bruno Collection

While building out the endpoint documentation, we put together a full request collection in Bruno, validated against real live data for every entity type. We're publishing it on GitHub so anyone building against /src has a working starting point instead of reading spec files cold. We also made sure that none of our examples return 404s.

A Mirrored vs. Generated Signal

Most of /src is a direct mirror. A few endpoints, such as leaderboards, are assembled by us rather than pulled verbatim. Every response now carries a header telling you which one you're looking at, so you always know exactly how "official" any given piece of data is.

Leaderboards, Reimagined

Double digit response times, even for leaderboards with thousands of runs on them. This one took real work to get right. This one is not just a work-in-progress, but a focus for the future tools of speedrun.io. More on this in an upcoming post very soon.

The full endpoint reference lives at docs.speedrun.io, generated straight from the OpenAPI spec. These docs have been rewritten from scratch and are designed to actually match what the live handlers do, not what we thought they'd do six months ago.

What's Still Catching Up

We'd rather tell you where the rough edges are than have you find them yourself. Here's a comprehensive list of what's incomplete at launch, and roughly when to expect each item to resolve:

  • Final data mirroring is near completion of its first full pass. Leaderboard, run and user sync is a complex part of the mirroring process, and we will be providing a live preview /v1 endpoint to track this progress.
  • A handful of sub-resource relationship endpoints (category/level/variable) are registered but not yet live. Expect these shortly after launch.
  • Full historical completeness on a few fields is an ongoing process, not a day-one guarantee. The vast majority of data is there and correct; a small tail is still being backfilled through our discovery systems.

None of this should get in the way of building against /src today. One cool thing I'll mention is that we've built our API reporting layer to communicate directly with our sync system. Any endpoints, filter/sort fields or missing records we haven't yet synced are not only logged, but also queued for data collection or development review. We hope to anticipate your needs regardless of feature requests.

As to What's Next...

This recent update paves the way for /v1. The initial spec is nearly complete and the high performance query-layer is already in place thanks to the /src rework. Expect a leaner, flexible and far more comprehensive API. Additional data sources are being prepared that extend far outside the reach of what's available today, in anticipation of the reimagined leaderboard system that is in development. I'm excited to share that with you. The update is coming very soon, so please do keep a look out for updates!