# crate — the cluster-first music-data API

crate is a music-data gateway that resolves any artist name, link, or third-party
identifier to a single canonical cluster_id, then returns the whole fleet's data
(discography, bookings, press, emergence signals) in one call.

Built by hosaka (https://hosaka.fm). Handmade, opinionated, made with intent.

---

## Cold-start recipe (3 calls)

### 1. Resolve a name or link to a cluster_id (keyed — X-API-Key required; for a keyless taste use /api/v2/preview/artist)
```
# Note: /api/v2/resolve requires an API key (X-API-Key header).
# Use /api/v2/preview/artist for a keyless taste (see below).
curl 'https://crate.hosaka.fm/api/v2/resolve?q=Four+Tet' \
  -H 'X-API-Key: YOUR_KEY'
```

### 2. Read the full artist dossier
```
curl 'https://crate.hosaka.fm/api/v2/artist/{cluster_id}' \
  -H 'X-API-Key: YOUR_KEY'
```

### 3. (Optional) Trim to specific facets
```
curl 'https://crate.hosaka.fm/api/v2/artist/{cluster_id}?fields=identity,discography' \
  -H 'X-API-Key: YOUR_KEY'
```

---

## Resolve grammar (beyond ?q=)

`/api/v2/resolve` takes ONE of: `?q=<name>` · `?url=<link>` · `?cluster=<64-hex>` ·
`?discogs=<int>` · `?mbid=<uuid>` · `?isrc=<12-char code>` · `?artist=<name>&track=<title>`.
The `isrc=` and `artist=&track=` arms bind a recording to its performing-artist cluster
(the lever for SoundCloud/Spotify/Apple/Bandcamp exports). Off-master / distributed-catalogue
artists that aren't on a Discogs master still resolve — the cluster is name-minted deterministically
(`matched_on: name_mint`), so you get a cluster_id, not a bare slug.

## Track search — who has a track called X

```
# title-first: exact, or ?fuzzy=true for substring (>=3 chars)
curl 'https://crate.hosaka.fm/api/v2/tracks?title=Angel+Echoes' -H 'X-API-Key: YOUR_KEY'
# ?source=mb (default, Discogs/MB tracklists) | bandcamp (underground/self-released) | all (merged)
curl 'https://crate.hosaka.fm/api/v2/tracks?title=Woman+Thank+You&source=bandcamp' -H 'X-API-Key: YOUR_KEY'
```
Returns artist clusters that have a recording of the title (ranked by release ubiquity), each
with onward `/artist` links. Pair with `resolve?artist=&track=` when you know the artist.

---

## Keyless endpoints

Two surfaces require no API key:

1. `GET /api/v2/preview/artist?q={name}` — a capped, render-ready artist dossier
   subset (display, emergence tier, short timeline arc, press count).
   Rate-limited: 100 requests/hour per IP. Fails closed (503) under load.
   Not for production builds — use a keyed key for products.

2. `GET /api/v2/openapi.json` — the full OpenAPI spec (v2=2.47.0). Public.

Example:
```
curl 'https://crate.hosaka.fm/api/v2/preview/artist?q=four+tet'
```

---

## OpenAPI spec + generate your own types

Spec URL: https://crate.hosaka.fm/api/v2/openapi.json

Generate TypeScript types in one command (no SDK required):
```
npx openapi-typescript https://crate.hosaka.fm/api/v2/openapi.json -o crate-api.d.ts
```

---

## Tiers (ranges only — see /pricing for full details)

Free $0 · Indie $49/mo · Studio $149/mo · Scale $499/mo · Sync $2,000/mo
Billed on successful (2xx) responses only. Errors and 429s are never billed.
Full ladder: https://crate.hosaka.fm/pricing

---

## Teaching errors

Catalogued error codes (those in the ERROR_CATALOG — e.g. `invalid_locator`,
`missing_locator`) carry machine-readable enrichment fields:
- `error`: the error code — the only field guaranteed on every error body
- `hint`: plain-English description of what went wrong (catalogued codes)
- `doc_url`: deep link to the error's documentation entry (catalogued codes)
- `param`: which parameter triggered the error (only when the code declares one)
- `next`: a copy-pasteable corrected call (only when the handler can build one)

Auth errors (e.g. `missing_api_key`) are returned bare — `error` only:
```
curl 'https://crate.hosaka.fm/api/v2/artist/anything'
# → {"error":"missing_api_key"}
```

Branch on `error`, never on HTTP status alone. Several codes share a status code.

Unresolved lookups return HTTP 200 with `present: false` / `state: "honest_gap"`,
never a 404. Agents should never parse error pages — crate won't send one.

---

## SDK + CLI

SDK (TypeScript): `npm install @hosaka-fm/crate` (v1.16.0)
Docs: https://crate-sdk.hosaka.fm

CLI: `npm install -g @hosaka-fm/crate-cli` (v0.3.7)
Keyless preview: `crate preview <artist name>`
Machine contract: `crate robot-docs` (exit dictionary + capabilities)
Agent triage: `crate triage`

---

## Machine contract door

Full agent documentation (self-describing index, rate limits, exit dictionary):
https://crate.hosaka.fm/agents

Sitemap: https://crate.hosaka.fm/sitemap.xml

---

## Contact

Email: hello@hosaka.fm
GitHub: https://github.com/hosaka-fm

Umbrella: https://hosaka.fm