Hosaka for Developers

as of 2026-08-13 (fleet re-measure)

CORRECTED 2026-08-25: figures on this page were updated to the fleet re-measure of 2026-08-13, and claims that could not be reproduced were removed or restated at their measured grain. This page therefore no longer matches its upstream source document, which has not yet been corrected.

canonical source: hosaka-fm/seen docs/hosaka/external/for-developers.md

web version: dev.hosaka.fm/developers/

Hosaka is a music-emergence detection substrate: it fuses independent signals — radio play, press, DJ sets, festival bookings, retail sell-through, SoundCloud reposts, and more — onto a single identity primitive, so you can query "who's emerging" instead of stitching that answer together yourself from a dozen incompatible sources.

This page covers what you're integrating against: the identity key, the API, how contracts work, and where pricing stands today.

The identity primitive: `cluster_id`

Every artist, label, and song in hosaka is a cluster, keyed by cluster_id — a bytea hash produced by pe-norm-v1. It is the sole identity key across every table, gate, and product in the system.

MusicBrainz IDs, Discogs IDs, and other external identifiers are nullable annotations on a cluster, never the key. You can join out to them when you have them. You should not build logic that assumes they exist, and you should never treat them as the spine.

That's not a compliance footnote — it's the point. Requiring an external ID before an artist "counts" filters out exactly the artists you'd want a detection system for: the ones an external catalogue hasn't caught up to yet. The unresolved tail — clusters with no MusicBrainz or Discogs ID — is where the freshest talent lives. Our own genre lens is built cluster-native for this reason: 4,334,514 rows across 845,889 clusters, resolved with no dependency on MB or Discogs.

If you're integrating: resolve to cluster_id first, treat every external ID field as optional enrichment, and don't gate on ID presence.

What a dossier draws on

A cluster's dossier is built from convergence across independent source kinds — currently 16: MusicBrainz releases, radio airplay, press, editorial mentions, DJ sets, RA bookings, underground retail, Bandcamp, festivals, SoundCloud reposts, RA reviews, general retail, RA podcasts, Shazam, live-demand signals, and RA recommended. No single source kind drives a verdict; the signal is in how many, and which, independent kinds line up on the same cluster.

We also carry a detection-time ledger — a bitemporal record of not just what we know about a cluster but when we came to know it (3,161,405 rows). This is what lets a dossier answer "was this visible early" rather than only "is this true now," and it's why we anchor everything to publish/observation dates rather than our own ingest timestamps — ingest timing is a crawler-ops artifact, not a signal about the artist.

The API: `/api/v2/aura`

Crate — the consumer-facing product in the hosaka fleet — exposes cluster-keyed dossiers through /api/v2/aura. You request an artist or label by cluster_id and get back the merged view: the convergent signals behind it, the detection-time trail, and the identifiers we've been able to resolve out to (MB, Discogs, etc., where they exist).

How consumption works

Hosaka runs on a producer-publishes, consumer-integrates contract model: each repo owns its own schema, and no repo writes into another repo's tables. If you're building against hosaka data, you read from a published surface — you don't get, and don't need, write access into the producer.

Published surfaces are pinned in contracts/published.yaml, one entry per table, each carrying its primary key, columns, and any invariants the producer guarantees. There are 67 published surfaces today. Pin your integration against the contract file's version, not against inferred schema — the contract is the source of truth, and changes to a published table land in the same PR as the contract update, so drift is visible at review time instead of at your integration's runtime.

Metered tiers

Metering is built into Crate's API layer, and billing is scaffolded on top of it. We're not publishing price tiers yet — that's still being finalized, not a detail we're withholding for effect. If you need production access ahead of published pricing, talk to us directly rather than assuming a rate card exists.

Where this stands

The substrate side of this is deep and live: ~2.2M distinct artist clusters on the appearance spine, drawn from the 16 source kinds above, with a working convergence signal — within the 119,095-cluster emergence cohort, multi-source overlap runs from 13,352 clusters at 2 independent source kinds through 1,733 at 3 and 257 at 4, down to 40 at 5+ — the highest-conviction cases. That part is not a prototype.

The commercial side — metered API access, billing, pricing tiers — is earlier: built and scaffolded, not yet running at repeatable revenue. If you're evaluating hosaka as an integration target, evaluate the data; ask us directly about commercial terms.