The API

Start here

Make a key in the app under Developers, then ask who it belongs to. If this returns your account, everything else on this page will work.

curl https://api-dev1.northwestfalls.com/v1/whoami \
  -H "Authorization: Bearer $NORTHWEST_API_KEY"

import { Northwest } from '@northwestfalls/sdk';

const nw = new Northwest(process.env.NORTHWEST_API_KEY);

const me = await nw.whoami();
console.log(me.account.plan, me.key.scopes);

const res = await fetch('https://api-dev1.northwestfalls.com/v1/whoami', {
  headers: { Authorization: `Bearer ${process.env.NORTHWEST_API_KEY}` },
});

const me = await res.json();

Which answers:

{
  "ok": true,
  "key": { "id": "…", "environment": "live", "scopes": ["catalog:read"] },
  "account": { "id": "…", "plan": "studio", "status": "active" }
}

Keys and scopes

Every request carries Authorization: Bearer <key>. Keys start with nwf_live_ or nwf_test_. A key does only what its scopes allow, so give each integration the narrowest set that works.

Revoking a key takes effect within about thirty seconds. Making and removing keys happens in the app, never with a key: a leaked key must not be able to grant itself a successor.

Test keys

A nwf_test_ key has a smaller monthly allowance. It currently reaches the same catalogue as a live key, so treat anything you do with it as real.

Limits

Numbers, not judgement calls.

Every response carries X-Quota-Limit, X-Quota-Used and X-Quota-Reset. A 429 carries Retry-After and means wait, not stop. The month is the UTC calendar month.

Endpoints

All under https://api-dev1.northwestfalls.com/v1. Open any one for a real response.

{
  "ok": true,
  "cursor": "eyJpZCI6…",
  "tracks": [
    {
      "id": "xnxfargpdbzq",
      "title": "nostalgia.exe",
      "duration": 153,
      "bpm": 92,
      "key": "F# minor",
      "version_count": 3,
      "artwork_url": "https://img.northwestfalls.com/…/card.jpg",
      "release": { "id": "rl_8fk2", "title": "Half Light", "type": "ep" },
      "created_at": "2026-07-14T09:12:44Z"
    }
  ]
}

{
  "target_type": "track",
  "target_id": "xnxfargpdbzq",
  "quality": "standard",
  "expires_in_days": 30
}

{
  "ok": true,
  "link": {
    "slug": "quiet-hours",
    "url": "https://northlink.cc/t/quiet-hours",
    "target_type": "track",
    "quality": "standard",
    "allow_download": false,
    "has_passcode": false,
    "expires_at": "2026-09-05T00:00:00Z"
  }
}

Paging

/tracks answers with a cursor. Pass it back to get the next page, and stop when it comes back null.

for await (const track of nw.eachTrack()) {
  console.log(track.title);
}

Embedding a player

No key, and safe in a browser. One script tag and an element:

<script type="module" src="https://assets.northwestfalls.com/assets/js/embed.js"></script>
<northwest-player link="your-link-slug"></northwest-player>

Which gives you this:

▶

nostalgia.exe

Your artist name

0:41 / 2:33

It renders in a shadow root, so your CSS cannot collide with ours and ours cannot leak into your page. Style it with custom properties (--nwp-bg, --nwp-fg, --nwp-accent, --nwp-radius) or reach individual pieces with ::part(play), ::part(title), ::part(waveform). It emits nwp:play, nwp:ended and nwp:error.

<northwest-player
  link="your-link-slug"
  theme="light"
  style="--nwp-accent: #c98f5a; --nwp-radius: 20px"></northwest-player>

Drawing it yourself

The same data is JSON, no key needed, and it is what the component reads:

curl https://northlink.cc/api/embed/your-link-slug

{
  "ok": true,
  "title": "nostalgia.exe",
  "artist": "Your artist name",
  "artwork_url": "https://northlink.cc/asset/…/full.jpg",
  "duration": 153,
  "stream_url": "https://northlink.cc/stream/your-link-slug",
  "peaks_url": "https://northlink.cc/peaks/your-link-slug",
  "state": "ready"
}

A link behind a passcode or an email gate cannot be embedded. Both surfaces answer with the address to send the listener to instead.

Errors

Every failure is the same shape. The slug is part of the contract and will not be renamed. The message beside it may be reworded at any time, so branch on the slug.

{
  "ok": false,
  "error": "insufficient_scope",
  "message": "This key does not have the links:write scope.",
  "required_scope": "links:write"
}

A 500 carries a random ref. Quote it and we can find the exact request.

Retrying

Retry a 429 and a 5xx, honouring Retry-After. Do not retry a 4xx: a failed write should not be repeated behind your back. The Node client already does exactly this.