SDKs / JavaScript

javascript Official SDK · TypeScript-first

Coming Soon

WorkoutX JavaScript & Node.js SDK

Q: How do I install the WorkoutX JavaScript SDK?

Run npm install @workoutx/sdk. It works in Node.js 18+ and modern browsers and ships with TypeScript types.

Q: Does it work in the browser as well as Node.js?

Yes. The SDK uses the native fetch API, so it runs in Node.js 18+, Deno, Bun, edge runtimes, and browsers without polyfills.

Q: How does authentication work for the Body Scan API?

Body Scan uses a logged-in user's JWT. Pass scan: { token }, or scan: { email, password } to let the SDK log in automatically.

The official JavaScript / TypeScript client for the WorkoutX API. Access 1,400+ exercises with GIF animations, the AI Workout Generator, supplements, and the Body Scan API — from a single, fully-typed client that runs in Node.js and the browser. Zero runtime dependencies.

npm install @workoutx/sdk

📦 Publishing to npm shortly — not yet installable. Get your key now and you'll be ready the moment it lands.

Get your free API key Full API reference

Quick start

One client covers both products — the Exercise API (API-key auth) and the Body Scan API (user JWT). The SDK attaches the right credential automatically.

import { WorkoutX } from "@workoutx/sdk";

const wx = new WorkoutX({
  apiKey: "wx_your_key_here",        // exercises / gifs / workout / supplements
  scan: { token: "eyJ..." },         // body scan (optional)
});

// Exercises
const page    = await wx.exercises.list({ limit: 20 });
const lunges  = await wx.exercises.byName("lunges");
const similar = await wx.exercises.similar("0001");

// Exercise GIF (binary) or a ready <img> URL
const bytes = await wx.gifs.get("0001");
const src   = wx.gifUrl("0001");

// AI Workout Generator & supplements
const workout = await wx.workout.generate({ goal: "hypertrophy", days: 4 });

// Body Scan
const credits = await wx.scan.credits();

bolt

Fully typed

TypeScript types for every endpoint and response. Autocomplete in your editor means no more guessing field names or URLs.

shield

Resilient by default

Automatic retries with backoff on rate limits (429) and 5xx, honoring Retry-After. Structured WorkoutXError with status, code and tips.

dataset

Both products, one client

Exercises, GIFs, workouts, supplements and Body Scan — all under wx.*. Auth handled transparently per product.

Look up an exercise by name or ID — safely

Exercise IDs are not sequential, so passing a human name to get() returns a 404. The find() helper tries an ID first, then falls back to a name search — so you never hit that mistake.

const ex = await wx.exercises.find("lunges"); // Exercise | null

Frequently asked questions

How do I install the WorkoutX JavaScript SDK?

Run npm install @workoutx/sdk (or pnpm/yarn). It works in Node.js 18+ and modern browsers and ships with TypeScript types.

Does it work in the browser as well as Node.js?

Yes. The SDK uses the native fetch API, so it runs in Node.js 18+, Deno, Bun, edge runtimes, and browsers without polyfills.

How do I get an API key?

Create a free account in the Developer Portal and copy your wx_... key. Pass it as apiKey when constructing the client.

How does authentication work for the Body Scan API?

Body Scan uses a logged-in user's JWT. Pass scan: { token }, or scan: { email, password } to let the SDK log in automatically and cache the token.

Security & API keys

vpn_key

Keep keys server-side

In public frontend code, anyone can read your API key. For browser apps, proxy requests through your own backend instead of shipping the key to the client.

image

GIF URLs carry the key

gifUrl() puts the key in the query string so <img> can load it. Since URLs can leak via logs and referrers, use a separate, restricted key for GIFs where possible.

lock

Credentials stay on the server

The Body Scan email/password auto-login should only run server-side. In clients, pass a short-lived scan.token obtained from your backend instead.