Skip to content
@hosaka-fm/crate

Getting started

Prerequisites

Section titled “Prerequisites”
  • Node 18+ (the SDK uses the global fetch), or any runtime with a global fetch (Deno, Bun, Cloudflare Workers, Edge).
  • A crate API key. crate is key-first — every data endpoint requires one. Keys are invite-only today; see the crate docs. Only crate.index() works without one.

Install

Section titled “Install”
Terminal window
npm install @hosaka-fm/crate   # or: pnpm add / yarn add / bun add

Dual ESM + CJS, zero runtime dependencies, types bundled.

Your first call

Section titled “Your first call”
import { Crate } from '@hosaka-fm/crate';


const crate = new Crate({ apiKey: process.env.CRATE_API_KEY });


const artist = await crate.artist('Four Tet');
console.log(artist.display, '→', artist.resolved_via);

crate.artist(key) accepts a name, a slug, a 64-hex cluster_id, or a discogs:/mbid: locator. It returns a typed ArtistDossierContract. If you pass a locator that resolves to nothing it throws CrateNotFoundError — use crate.artistOrNull(key) to get null instead.

What you get back

Section titled “What you get back”

Responses are fully typed off crate’s OpenAPI spec — your editor autocompletes every field. A few high-traffic returns:

  • crate.resolve(q) → IdentityResolution (cluster_id, slug, display, locators, …)
  • crate.artist(key) → ArtistDossierContract (cluster-first: carries discography, bandcamp_emergence, bandcamp_tastemaker)
  • crate.label(key) → LabelDossierContract
  • crate.search(params) → SearchResponse

Next steps

Section titled “Next steps”