The API

Start here

Create a key in the app under Settings, then API keys. Keys start with nwf_live_ or nwf_test_.

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

Or with the client, which has no dependencies:

npm install @northwestfalls/sdk

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

const nw = new NorthwestFalls({ token: process.env.NORTHWEST_TOKEN });

const { tracks } = await nw.tracks({ limit: 20 });
for (const track of tracks) console.log(track.title, track.duration);

Keys and scopes

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

Revoking a key takes effect within about thirty seconds. Creating and removing keys and webhook endpoints is done 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.

Marked copies, and finding a leak

Give each person their own address and their own copy of the audio, carrying a code only they have.

const { link } = await nw.createLink({ target_type: 'track', target_id: trackId });

await nw.addRecipients(link.slug, ['Anna at XL', 'Ben at 4AD']);
await nw.enableWatermark(link.slug);

const { recipients } = await nw.recipients(link.slug);
for (const person of recipients) console.log(person.name, person.url);

When a file turns up somewhere it should not:

const hit = await nw.trace('a1b2c3d4e5f6');
console.log(hit.recipient.name, hit.activity.plays);

You can also upload the file itself in the app and it will recover the code for you. The mark is a quiet tone under the music and survives being re-encoded.

Webhooks

Add an endpoint in the app under Settings, then Webhooks. We call it when something happens instead of you asking on a timer.

Check the signature before you trust the body

Every call carries X-NW-Signature: t=<unix>,v1=<hash>. Sign the timestamp, a full stop, then the raw body you received. Not a re-serialised object.

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

app.post('/hooks/northwest', express.raw({ type: 'application/json' }), async (req, res) => {
  const raw = req.body.toString('utf8');

  const good = await verifyWebhook(
    process.env.NORTHWEST_WEBHOOK_SECRET,
    req.header('X-NW-Signature'),
    raw
  );

  if (!good) return res.sendStatus(400);

  res.sendStatus(200);
  await handle(JSON.parse(raw));
});

Answer with any 2xx as soon as you have stored the event, then do the slow work. We retry eight times over about a day: 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours, then 24. Twenty failures in a row and we turn the endpoint off and tell you.

Deliveries can arrive more than once and can arrive out of order. Use the id field to make your handler idempotent, and do not infer sequence from arrival.

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>

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.

If you would rather draw it yourself, the same data is JSON at https://northlink.cc/api/embed/<slug>: title, artist, artwork, duration, a stream URL and a waveform URL.

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 { "ok": false, "error": "<slug>" } with a human message beside it. The slug is part of the contract and will not be renamed. The message may be reworded at any time, so branch on the slug.

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