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`

public available

Return the compact machine-readable endpoint index generated from apiGroups.

This is the route contract index consumed by agents before choosing specific REST endpoints.

`GET /api/openapi.json`

public available

Return the OpenAPI 3.0 document generated from apiGroups and openApiSchemas.

The document is generated from the same contract source as /docs/api and /api.

`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.

`POST /api/credits/allocate`

admin guarded

Allocate listener credits to a track after abuse checks and admin authorization.

Requires ADMIN_TOKEN; persistence requires Supabase service-role configuration.

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`

admin guarded

Validate upload metadata, suggest AI disclosure posture, and persist upload review evidence.

Requires ADMIN_TOKEN; persistence requires Supabase service-role configuration.

`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/download-entitlement`

admin guarded

Issue a short-lived gated download URL for an approved track.

Requires ADMIN_TOKEN, DOWNLOAD_TOKEN_SECRET, an enabled download gate, and BUCKET-backed media.

`POST /api/admin/audio-upload/object/:key`

admin guarded

Write private original audio bytes to the R2 originals lane using a short-lived upload token.

Requires the upload token minted by /api/admin/audio-upload/intent, matching content-type, and BUCKET.

`GET /api/admin/auth-status`

admin available

Report read-only admin mode without exposing credentials.

Used by operator pages to explain whether guarded writes are configured.

`POST /api/admin/artists`

admin guarded

Create a draft artist record for review.

Requires ADMIN_TOKEN; persistence requires Supabase service-role configuration.

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

admin guarded

Suspend, feature, or activate an artist with audit evidence.

Supported actions are suspend, feature, and activate.

`POST /api/admin/releases`

admin guarded

Create a draft release record for a reviewed artist.

Requires ADMIN_TOKEN; persistence requires Supabase service-role configuration.

`POST /api/admin/tracks`

admin guarded

Create a draft track record with gates closed until rights, disclosure, and moderation clear.

Requires ADMIN_TOKEN; persistence requires Supabase service-role configuration.

`GET /api/admin/moderation`

admin available

Return current moderation cases for operator review.

Read-only queue view; write actions live under /api/admin/moderation/:id/:action.

`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.

`GET /api/admin/payout-ledger`

admin available

Return payout ledger entries for operator reconciliation.

Read-only queue view; payment state changes require guarded POST actions.

`POST /api/admin/payout-ledger/:id/mark-paid`

admin guarded

Mark a payout ledger entry paid with timestamp and operator note.

Requires ADMIN_TOKEN; persistence requires Supabase service-role configuration.

`POST /api/admin/fraud/payout-hold`

admin guarded

Apply a payout hold when play, credit, or support signals require fraud review.

Requires ADMIN_TOKEN and a concrete reason; persistence requires Supabase service-role configuration.

`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.

`GET /api/admin/takedowns`

admin available

Return takedown cases for operator review.

Read-only queue view; write actions live under /api/admin/takedowns and /api/admin/takedowns/:id/:action.

`POST /api/admin/takedowns`

admin guarded

Intake DMCA/takedown notices and open review evidence.

Requires ADMIN_TOKEN; revocation actions live under /api/admin/takedowns/:id/:action.

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

admin guarded

Unpublish or resolve a takedown case with retained evidence.

Requires ADMIN_TOKEN; supported actions are unpublish and resolve.

`POST /api/admin/takedowns/:id/counter-notice`

admin guarded

Record a DMCA counter-notice payload for legal review.

Requires ADMIN_TOKEN and all required counter-notice fields.