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.

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/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, and gate fields.

The track contract is the canonical read model for listener/player surfaces.

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

`GET /api/admin/readiness`

admin available

Return provider provisioning readiness groups and missing configuration.

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

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.