Built by agents. Legible to agents.

The hosaka fleet is agent-built. Every interface — API, CLI, sitemap, .md mirrors — is designed to be consumed without a browser.

Run the curl Read the robot contract

Why

hosaka is built by one operator with an AI-agent fleet — every tool in this document is a direct output of that practice.

Agent-legibility is a first-class constraint, not an afterthought. Stdout is data. Stderr is diagnostics. Exit codes are contracts. The keyless endpoint fails closed — 503 when the substrate is busy — so your agent handles it explicitly rather than silently swallowing an error page.

For the full data model behind what the API returns, see how hosaka knows.

30-second start

No API key. No sign-up. 100 req/hour/IP. CORS *. Fails closed on 503 (substrate busy) — handle it explicitly.

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

Response keys: object · present · display · cluster_id (nullable — not all artists resolve to a Discogs or MB ID) · resolved_via · emergence_tier · arc[≤6] · arc_truncated · booked_with[≤3] · press_count · note · generated_at

cluster_id is nullable: artists without a Discogs or MusicBrainz anchor return null. Your code must handle that case — it is not an error.

crate-cli robot contract

Source: github.com/hosaka-fm/crate-cli — public repo, tagged release. There is no package registry entry; build it from source.

stdout = untransformed API JSON. stderr = diagnostics. These channels never mix. Pipe stdout to jq, redirect stderr to a log — they will never cross.

Exit code dictionary
Code	Meaning	Notes
0	ok	success — including honest-gap (present:false) bodies; never exit 1 for "no results"
1	usage error	bad args/flags; the error names the corrected invocation
2	auth error	missing/invalid API key (HTTP 401/402)
3	invalid input	the API rejected the input (HTTP 400); its hint is passed through
4	rate-limited	HTTP 429 — Retry-After surfaced on stderr; the CLI never auto-retries, the agent decides
5	server error	upstream server error (HTTP 5xx)
6	network error	DNS failure, timeout, connection refused
7	config error	config file unreadable or corrupt

crate robot-docs — paste-ready agent handbook for pasting into a system prompt. crate capabilities — machine contract JSON listing every available command and flag. crate triage — auth check + substrate health + suggested next commands. crate preview <name> — keyless single-artist query.

# Confirm auth and substrate health before a batch run
crate triage

# Pull the robot handbook into a system prompt
crate robot-docs

# Query without a key
crate preview 'four tet'

# Machine-readable capability list
crate capabilities

All four agent-oriented commands. stdout = JSON. stderr = human-readable diagnostics.

SDK

TypeScript SDK — generated types, every https://crate.hosaka.fm endpoint. Source: github.com/hosaka-fm/crate-sdk — public repo, tagged release. There is no package registry entry; build it from source.

SDK docs and generated types. For production access beyond the keyless tier, see hosaka for developers.

Machine-readable surfaces

This site publishes a set of machine-readable surfaces designed for agent consumption:

/llms.txt — site one-liner, page index, endpoint facts
/<page>.md — prose mirror for every route (same content, zero drift — generated from the same source module)
/sitemap.xml — canonical page list with real lastModified dates
OpenAPI spec via the SDK docs at crate-sdk.hosaka.fm

llms.txt is a convenience index for language models, not a ranking claim or SEO artefact.

Etiquette

Rate limit: 100 req/hour/IP on the keyless endpoint. Cached responses carry s-maxage=300 — respect it. Identify your bot via User-Agent (e.g. MyBot/1.0 (github.com/you/repo)).

If you need higher volume or a keyed tier, see hosaka for developers.