# Intervals-icu-sdk: TypeScript SDK generated from the official OpenAPI spec (open source, unofficial)

**URL:** <https://forum.intervals.icu/t/intervals-icu-sdk-typescript-sdk-generated-from-the-official-openapi-spec-open-source-unofficial/130850>\
**Category:** External Projects\
**Created:** [31 July 2026 21:27 UTC](https://forum.intervals.icu/t/intervals-icu-sdk-typescript-sdk-generated-from-the-official-openapi-spec-open-source-unofficial/130850 "2026-07-31T21:27:35Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![Robin\_Curbelo](https://forum.intervals.icu/user_avatar/forum.intervals.icu/robin_curbelo/32/87917_2.png) [@Robin\_Curbelo](https://forum.intervals.icu/u/Robin_Curbelo)\
**Post date:** [31 July 2026 21:27 UTC](https://forum.intervals.icu/t/intervals-icu-sdk-typescript-sdk-generated-from-the-official-openapi-spec-open-source-unofficial/130850/1 "2026-07-31T21:27:35Z")

</div>

Hi all,

I am training for my first Olympic distance triathlon (April 2027) and I run everything through Intervals.icu: Garmin syncs in, wellness and activities flow out through the API into a small self-hosted coach pipeline, and planned workouts get pushed back to the calendar so they land on my watch. After hand-writing the same fetch wrappers and TypeScript types for the third time, I gave up and generated a proper client from the official OpenAPI spec. Sharing it in case it saves someone else the same work.

> **[GitHub - jcurbelo/intervals-icu-sdk: Unofficial TypeScript SDK for the Intervals.icu...](https://github.com/jcurbelo/intervals-icu-sdk)**
>
> Unofficial TypeScript SDK for the Intervals.icu API. Fully typed, zero dependencies, generated from the official OpenAPI spec.

Install with `npm install intervals-icu-sdk` ([npm page](https://www.npmjs.com/package/intervals-icu-sdk)).

**What it is**

- All 148 endpoints of the v1 API, with request and response types generated from the [official OpenAPI spec](https://intervals.icu/api/v1/docs)

- Zero runtime dependencies, works on Node 18+, Bun, and Deno

- Function names match the API operation ids (`listActivities`, `updateWellness`, `createEvent`…), so the official [api-docs page](https://intervals.icu/api-docs.html) doubles as the SDK reference

- API key and OAuth bearer auth both supported

- MIT licensed

**A quick taste**

```ts

import { configureIntervals, listWellnessRecords } from "intervals-icu-sdk";

configureIntervals(); // reads INTERVALS_API_KEY

const { data } = await listWellnessRecords({

  path: { id: "0" },

  query: { oldest: "2026-07-01", newest: "2026-07-31" },

});

```

**Design choices**

- JSON only: the CSV variants of the list endpoints are stripped, on the theory that a typed client wants JSON and curl already does CSV well. Workout downloads keep their format parameter (zwo, mrc, erg, fit).

- A CI job re-fetches the spec every Monday and fails loudly if the API changed, so the package should never silently drift out of date.

**Prior art**

There are existing community clients, notably Fernando Paladini’s [intervals-icu client announced here](https://forum.intervals.icu/t/intervals-icu-a-complete-typescript-client-for-the-intervals-icu-api/123768) a few months back. This one takes a different approach: everything is generated from the spec, so coverage is complete by construction and API changes are caught by CI instead of by hand. Use whichever fits; more tooling around this API is good for everyone.

**Not official**

No affiliation with Intervals.icu. Huge thanks to David for the platform and for publishing a clean OpenAPI spec at all, which is the only reason this was possible. And mind the API rate limits when building on it.

Bug reports, feedback and PRs very welcome.