Intervals-icu: A complete TypeScript client for the Intervals.icu API

External Projects
1

Hey everyone!

I’m a developer and amateur runner based in Florianópolis, Brazil. Being part of a vibrant endurance community here, I’ve seen firsthand that for anyone serious about training, Intervals.icu is hands-down one of the best platforms for performance analysis.

The problem? I found myself rewriting the same API integration code across multiple personal projects and automation scripts (I’m a big fan of automating everything from GitHub backups to n8n workflows). I finally decided to build a solid, open-source client library to handle the heavy lifting.

The result is intervals-icu. You can find the details below:

You can install it via:

npm install intervals-icu

Real-world usage: Weather Adjusted Pace (WAP)

I’m already dogfooding this library for a new free tool I’m developing: Weather Adjusted Pace (WAP). I’m using intervals-icu to seamlessly pull activity data and push adjusted metrics back into the platform. I’ll be sharing more updates on WAP with the community very soon!

What’s under the hood of the library:

I built this to be the most robust way to interact with Intervals.icu using Node.js/TypeScript:

  • Full Type Safety: Over 100 methods across 16 services (Activities, Wellness, Workouts, etc.) with strict interfaces. No more guessing what the API response looks like.
  • Dual Auth: Support for both API Keys (personal scripts) and OAuth 2.0 (for apps acting on behalf of other athletes).
  • Production-Ready Resilience: It has built-in exponential backoff for 429 (rate limit) and 5xx errors. It just works, even when the API is busy.
  • File Handling: Simplified uploads for .fit, .tcx, and .gpx files.
  • Modern & Lean: Zero bloat—just axios, optimized for Node 18+.

Why I’m sharing this

I’m a big believer in automating the boring stuff and in the open-source community. I’d love to get your feedback, hear about your use cases, or see your PRs on GitHub.

Let’s build better tools for the endurance community. Happy training!

3 Likes