Music-as-a-Service
for your app.

Why MuzikA

The only background-music platform with a real public API, multi-tenancy, and per-stream playback reporting baked in.

Quickstart

Stream your first track in under five minutes.

1. Install the SDK

npm install @muzika/sdk

pnpm add @muzika/sdk

yarn add @muzika/sdk

2. Create an API key

Go to the operator console → API keys → New key. Save the secret — we show it once.

3. Play a track

import { MuzikaClient } from '@muzika/sdk';

const muzika = new MuzikaClient({ apiKey: process.env.MUZIKA_KEY });

// Browse the catalog
const { data: tracks } = await muzika.catalog.listTracks({ genre: 'Greek Hits', limit: 10 });

// Mint a signed URL (5 min TTL)
const { url } = await muzika.stream.getUrl({ track_id: tracks[0].id });

// Play in browser
const audio = new Audio(url);
audio.play();

4. Log playback events

await muzika.events.logPlayback({
  store_token: 'store_token_xxx',
  events: [{
    type: 'play_start',
    track_id: tracks[0].id,
    track_title: tracks[0].title,
    track_artist: tracks[0].artist,
    client_ts: new Date().toISOString(),
  }],
});

API reference

All endpoints are versioned at /v1 and protected by Bearer API key auth.

Want the full OpenAPI 3.1 spec? Request API access → · use it with openapi-typescript for typed clients in any language.

Official SDKs

Use a typed wrapper instead of writing fetch calls by hand.

import { MuzikaClient } from '@muzika/sdk';
const muzika = new MuzikaClient({ apiKey: 'mk_live_…' });

// .catalog .stream .stores .events .sync .webhooks .operators

Webhooks

Push delivery of events to your endpoint. Replaces polling. HMAC-signed payloads.

Events

• store.online — a streamer connected
• store.offline — streamer quiet > 5 min
• store.dual_use_blocked — duplicate device detected
• playback.event_batch — track play_start (batched)
• sync.completed — offline pre-cache filled
• quota.warning — 80% of rate-limit reached

Verify a signature (Node)

import { verifyWebhookSignature } from '@muzika/sdk';

app.post('/webhook', async (req, res) => {
  const body = await req.text();
  const ok = await verifyWebhookSignature({
    body,
    signatureHeader: req.headers.get('X-Muzika-Signature'),
    timestampHeader: req.headers.get('X-Muzika-Timestamp'),
    secret: process.env.MUZIKA_WEBHOOK_SECRET,
  });
  if (!ok) return res.status(401).end();
  // ... process the event
});

Want the webhook guide (retry semantics + idempotency)? Ask us →

Authentication

All requests use a Bearer API key. Keys are tenant-scoped — they only see their own operator's data.

Authorization: Bearer mk_live_4f2a8c1b.x7Y3Q…long-secret…
X-End-User-Id: cafe-elmara-tlv   # optional — passed through to audit

Generate keys in the console. Rotate via POST /v1/operators/me/api-keys/:id/rotate — old key invalidated, new returned in one round-trip.

Rate limits

Per-operator quotas. Soft warning headers fire at 80%; 429 with Retry-After at the cap.