Quickstart

Get a working call against the live API in under 60 seconds.

1. Explore the API (no key needed)

The API is keyed — every data endpoint needs an X-API-Key. Two surfaces stay public so you can orient before you have a key: the self-describing root index (cold-start recipe + every resource with its auth tier + how to get a key) and the OpenAPI spec.

curl 'https://crate.0xhoneyjar.xyz/api/v1' | jq          # the root index
curl 'https://crate.0xhoneyjar.xyz/api/v1/openapi.json'  # the machine-readable contract

Everything else needs a key (step 2). With one, your first data call — say a search — looks like:

curl 'https://crate.0xhoneyjar.xyz/api/v1/search?q=aphex&limit=3' \
  -H 'X-API-Key: ck_live_YOUR_KEY' | jq

You should see something like:

{
  "query": { "q": "aphex", "filters": [] },
  "pagination": { "page": 1, "total_pages": 20, "total_results": 1000, "total_results_mode": "approximate_50k_sample" },
  "results": [
    { "master_id": 12345, "title": "Selected Ambient Works 85-92", "artist": "Aphex Twin", "year": 1992, "cube_quadrant": "101", "owner_count": 4321, "dj_count": 12, "critic_count": 8, "formats": ["Vinyl", "CD"], "link_to_cube": "https://..." },
    ...
  ],
  "freshness": { "ridden_lag_s": 18, "mirror_lag_s": 18 }
}

That's the dub plate cut — every authenticated endpoint returns variations of this shape with consistent fields.

2. Get an API key

Every data endpoint needs an API key (only the root index + the spec above are public). Two paths to get one:

Self-serve ($49 / $99 / $299/mo):

1. Visit crate.0xhoneyjar.xyz/api/signup (when public)
2. Pick a tier; Stripe Checkout flow
3. Your key arrives by email + appears once in your dashboard
4. Store it in a secret manager (1Password / AWS Secrets Manager / etc.)

Sync tier ($2k/mo) — for sync agencies + clearance research workflows:

1. Email jani@hosaka.fm with your use case + expected volume
2. Manual contract; key issued via the admin route
3. Personal Slack channel for support

See authentication for the full key lifecycle (rotation, revocation, env vs live).

3. Make your first authenticated call

curl 'https://crate.0xhoneyjar.xyz/api/v1/masters/12345' \
  -H 'X-API-Key: ck_live_YOUR_KEY_HERE'

Response:

{
  "master_id": 12345,
  "title": "Selected Ambient Works 85-92",
  "artist": "Aphex Twin",
  "year": 1992,
  "cube_quadrant": "101",
  "owner_count": 4321,
  "dj_count": 12,
  "critic_count": 8,
  "formats": ["Vinyl", "CD"],
  "freshness": { "ridden_lag_s": 18, "mirror_lag_s": 18 },
  "link_to_cube": "https://...",
  "insert_links": null
}

The insert_links field is reserved for the insert cross-source-links feature shipping in v1.1. v1.0 always returns null.

4. Batch enrichment (Sync tier flagship)

If you have a list of master IDs (sync brief, clearance shortlist), batch them:

curl -X POST 'https://crate.0xhoneyjar.xyz/api/v1/masters/batch' \
  -H 'X-API-Key: ck_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"ids": [12345, 67890, 11223]}'

Response preserves input order; missing IDs flow into not_found:

{
  "results": [
    { "master_id": 12345, "title": "...", ... },
    { "master_id": 67890, "title": "...", ... },
    { "master_id": 11223, "title": "...", ... }
  ],
  "not_found": []
}

Sync tier limit: 500 IDs per call (raised from 100 in carrefour#55). Self-serve tiers: 100 per call. Counts as ONE rate-limit unit per request, not N.

What next

• API reference — every endpoint + parameter + response shape
• Use cases — worked examples (clearance research, mood-aware search, top-K per genre)
• Error codes — what 400 / 401 / 402 / 429 / 503 / 504 actually mean