Syntha API

Read-only discovery for the MVP API contracts. Public-preview endpoints expose catalog and commerce intent state; write-capable endpoints stay guarded until live provisioning, legal review, and launch gates clear.

public-preview guarded writes

Machine index

GET /api returns the grouped endpoint contract as JSON.

System

`GET /api/health`

public available

Return operational status and catalog counts for monitoring.

Returns ok:true, status:operational, environment, and catalog item counts.

Catalog

`GET /api/catalog`

public available

Return the active artist, release, track, moderation, ledger, SHADOW, and takedown catalog.

Uses Supabase when public read credentials are configured; otherwise returns the seed catalog.

`GET /api/search`

public available

Return deterministic catalog search results with explicit filter and ranking signals.

Supports q, origin, rights, downloadable, support, shadow, featured, and sort filters; raw plays are not ranking input.

`GET /api/artists/:slug`

public available

Return one artist contract by slug.

Slug and UUID lookup are both supported by the repository.

`GET /api/releases/:slug`

public available

Return one release contract by slug.

Release tracks are available through the full catalog until a dedicated child route is needed.

`GET /api/tracks/:slug`

public available

Return one track contract with rights, AI disclosure, pricing, gate fields, and synthesized Trust Score.

Includes trustScore: { value (0–100), label, breakdown } derived from rights, AI disclosure, moderation, streaming, download, and support gates.

`GET /api/similar/:slug`

public available

Return up to 10 similar tracks ranked by genre, mood, origin, artist, and version-type overlap.

Uses deterministic scoring from computeSimilarTracks(): genre +40, each shared mood +15, origin +20, same artist +10, same versionType +5. Returns slug, title, artistName, genre, aiOrigin, mood, url per result.

`GET /api/genres`

public available

Return the canonical genre taxonomy with per-genre track counts and active origin intersections.

Genres are defined in TRACK_GENRES in domain.ts — pop, hip-hop, electronic, rock, r-n-b, ambient, experimental, soundtrack, other.

`GET /api/origins`

public available

Return the canonical AI-origin taxonomy with per-origin track counts and active genre intersections.

Origins are the five Syntha disclosure types: human, ai-assisted, synthetic, transformed, hybrid.

`GET /api/moods`

public available

Return the canonical mood taxonomy with per-mood track counts, active genre intersections, and active origin intersections.

Moods are defined in TRACK_MOODS in domain.ts — dark, euphoric, melancholic, energetic, chill, cinematic, dreamy, aggressive. A track can carry multiple moods.

`GET /api/oembed`

public available

oEmbed provider endpoint returning a rich-type payload for https://syntha.music/tracks/{slug} URLs.

Pass ?url={trackUrl}. The returned iframe points at /embed/{slug}, a disclosure-preserving compact player that keeps AI-origin, rights state, and disclosure visible wherever the track is embedded. 400 without url, 404 for non-track or unknown URLs.

Media And Commerce

`GET /api/stream/:trackId`

public setup-required

Serve an approved stream object or report why the track is gated.

Requires the BUCKET binding and an enabled track before bytes are returned.

`GET /api/download/:trackId`

public guarded

Serve an approved download object after a short-lived entitlement token is supplied.

Download access requires rights gates, download gates, BUCKET, and DOWNLOAD_TOKEN_SECRET.

`GET /api/support/checkout`

public setup-required

Create or describe a Stripe support Checkout intent for a track.

Creates a real Stripe Checkout Session when Stripe secrets and price IDs are configured.

`GET /api/download/checkout`

public setup-required

Create or describe a Stripe download Checkout intent for a track.

Download delivery still requires a later entitlement token before object access opens.

`POST /api/credits/purchase`

public setup-required

Create a dynamic Stripe Checkout Session for credit purchases.

Credits remain manually allocated until listener accounts and abuse controls are live.

Trust, Analytics, And Readiness

`POST /api/analytics/event`

public available

Accept a privacy-filtered allowlist of syntha_* analytics events.

Personal details and sensitive inferred properties are stripped before persistence.

`POST /api/artist-applications`

public setup-required

Accept controlled artist applications for manual review before upload access opens.

Validates rights confirmation and review flags; persistence requires Supabase service-role configuration.

`POST /api/stripe/webhook`

public setup-required

Verify Stripe webhook signatures and compute ledger/support transaction rows.

Persistence requires STRIPE_WEBHOOK_SECRET plus Supabase service-role configuration.

`POST /api/csp-report`

public available

Drain browser Content Security Policy violation reports without exposing user-facing telemetry.

Always returns 204 No Content for valid and malformed reports; console logging is best-effort and not a launch-readiness signal.

`GET /api/admin/readiness`

admin available

Return provider provisioning readiness groups and missing configuration.

Read-only contract; it does not reveal secret values.

`GET /api/admin/launch`

admin available

Return sanitized launch gate status, strict proof posture, and provider/legal evidence without secret values.

Launch remains blocked until strict readiness, strict live smoke, app-release-gate, and founder/legal gates all pass.

Guarded Admin Writes

`POST /api/admin/audio-upload/intent`

admin guarded

Validate upload metadata and mint a short-lived private object upload URL.

Requires ADMIN_TOKEN and DOWNLOAD_TOKEN_SECRET; object write also requires BUCKET.

`POST /api/admin/moderation/:id/:action`

admin guarded

Persist moderation approval, info request, monetization hold, download restriction, or unpublish action.

Supabase service-role configuration persists flags, track gate patches, and audit logs.

`POST /api/tracks/:id/rights`

admin guarded

Persist rights records and hold stream/download gates until review clears.

Used before public distribution or monetization opens.

`POST /api/tracks/:id/ai-disclosure`

admin guarded

Persist AI disclosure records and hold stream/download gates until review clears.

Supports human, AI-assisted, synthetic, transformed, and hybrid origin disclosure.

`POST /api/shadow/import-handoff`

admin guarded

Validate SHADOW handoff payloads and create draft catalog records when configured.

Drafts remain pending moderation with stream/download gates closed.

`POST /api/admin/takedowns`

admin guarded

Intake DMCA/takedown notices and open review evidence.

Revocation actions live under /api/admin/takedowns/:id/:action.