Worked examples

Five common workflows, end-to-end, with runnable curl. Each example uses the live API + assumes a $KEY env var set to your ck_live_* key.

1. Clearance research (Sync agency flagship)

You have a music supervisor brief: "find me 50 candidate masters for an ad campaign — uplifting, mid-tempo, US-charting, post-2010, no Aphex Twin." Batch enrich your shortlist:

# Step 1: discover candidates with faceted search
curl 'https://crate.0xhoneyjar.xyz/api/v1/search?genre=Electronic&style=House&year_from=2010&country=US&limit=100' \
  -H "X-API-Key: $KEY" | jq '.results[].master_id' > shortlist.txt

# Step 2: batch enrich for cube quadrant + DJ count + critic count
curl -X POST 'https://crate.0xhoneyjar.xyz/api/v1/masters/batch' \
  -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"ids\": $(cat shortlist.txt | jq -s '. | map(tonumber)')}" | jq

# Step 3: filter for the cube position you want + exclude Aphex Twin
curl 'https://crate.0xhoneyjar.xyz/api/v1/search?genre=Electronic&style=House&year_from=2010&country=US&cube_quadrant=110&exclude_artist=Aphex+Twin&dj_count_min=3&limit=50' \
  -H "X-API-Key: $KEY" | jq

Sync tier: 500 IDs per batch call; 1000/min burst; 10 in-flight concurrent. A 500-master brief lands in 1 call.

2. Mood-aware search (AI music app)

You're building a recommendation engine where users describe a vibe and you surface matching catalogue. Use cube quadrant + dj_count_min as proxies for "actively played by DJs" + "critically valued":

# "Underground techno that's getting played in clubs but isn't on critic radar"
curl 'https://crate.0xhoneyjar.xyz/api/v1/search?style=Techno&cube_quadrant=001&dj_count_min=5&limit=20' \
  -H "X-API-Key: $KEY" | jq '.results[] | {title, artist, dj_count, critic_count, cube_quadrant}'

Cube quadrant codes are 3-bit [critic][collector][dj]:

  • 001 = high DJ activity, low critic / collector signal (underground, currently being played)
  • 110 = critic + collector validated, low DJ activity (canonical, not currently spinning)
  • 111 = all three high (the hits — Aphex Twin, Burial, Daft Punk)
  • 000 = no signal across any axis (unranked, often deep cuts)

3. Top-K per genre

You want the most-owned masters in a specific genre + style for a "best of" feature:

curl 'https://crate.0xhoneyjar.xyz/api/v1/search?genre=Hip+Hop&style=Boom+Bap&year_from=1990&year_to=1999&limit=20' \
  -H "X-API-Key: $KEY" | jq '.results[] | {title, artist, owner_count}'

Default result ordering is owner_count DESC NULLS LAST, year DESC — so the top results are the most-collected masters in the slice.

4. Facet exploration

Before running a heavy search, discover what's actually in the catalogue for a slice:

# What styles exist within Genre=Electronic, narrowed to BE+NL?
curl 'https://crate.0xhoneyjar.xyz/api/v1/facets?genre=Electronic&country=BE&country=NL' \
  -H "X-API-Key: $KEY" | jq

Facet response shape mirrors what's embedded in /api/v1/search responses' facets field — same structure, just without the result list. Useful for building UI dropdowns that reflect actual catalogue distribution.

5. Monthly usage + plan management

# Where am I against my quota?
curl 'https://crate.0xhoneyjar.xyz/api/v1/usage' \
  -H "X-API-Key: $KEY" | jq

# Output:
# {
#   "tier": "studio",
#   "month": "2026-05",
#   "calls_this_month": 4321,
#   "quota_monthly": 100000,
#   "remaining_this_month": 95679,
#   "burst_limit_per_minute": 300,
#   "tier_metadata": { "endpoints_available": [...] }
# }

Bump tier or manage billing via the Stripe Customer Portal link in your dashboard.

Common patterns

  • Always check freshness.ridden_lag_s before trusting the data for time-sensitive workflows. Typical lag under 2 minutes; bursty under producer load.
  • Respect X-RateLimit-Remaining headers — pace your own throughput when remaining drops below ~10% of the burst limit.
  • Use the batch endpoint when you have ≥3 master_ids — it's 1 rate-limit unit per call regardless of size.
  • Set Accept: application/json explicitly — we don't currently negotiate other content types, but the explicit header future-proofs your client.