Reference

BookSounds API

Machine-readable spec: /api/openapi.json. Protected routes take Authorization: Bearer <access-token>; responses expose GUIDs and slugs, never numeric ids.

Auth

Register, sign in, rotate tokens, recover passwords, manage sessions. Access tokens are Bearer JWTs (15 min); refresh tokens rotate in HttpOnly cookies.

Method	Path	Description
POST	/api/auth/register	Create an account (rate limited 5/h/IP)
POST	/api/auth/login	Sign in (rate limited 10/15m/IP)
POST	/api/auth/refresh	Rotate refresh cookie, issue new access token (reuse revokes the session family)
POST	/api/auth/logout 🔒	Revoke current session
POST	/api/auth/logout-all 🔒	Revoke every session
GET	/api/auth/me 🔒	Current user, plan + limits, accessible creators (owned + team)
POST	/api/auth/forgot-password	Request a one-time reset link (always generic response)
POST	/api/auth/reset-password	Consume reset token, set new password, revoke sessions
POST	/api/auth/verify-email	Consume verification token
POST	/api/auth/resend-verification 🔒	Resend verification email (3/h)
POST	/api/auth/change-password 🔒	Change password (current session survives)
POST	/api/auth/change-email 🔒	Step 1 of email change: sends confirmation link to the new address
POST	/api/auth/confirm-email	Step 2 of email change: consume token, swap email, revoke sessions
GET	/api/auth/sessions 🔒	List active sessions (current flagged)
DELETE	/api/auth/sessions/{guid} 🔒	Revoke one session

Public

No authentication. GUIDs or slugs accepted. Numeric ids never appear.

Method	Path	Description
GET	/api/public/creators/{guid}	Public creator profile (GUID or slug)
GET	/api/public/creators/{guid}/series	Creator's active series
GET	/api/public/creators/{guid}/works	Creator's published works (paginated: page, per_page ≤ 50)
GET	/api/public/series/{guid}	Public series (GUID or slug)
GET	/api/public/series/{guid}/works	Works in a series (paginated)
GET	/api/public/works/{guid}	Work detail with credits and destinations (GUID or slug)
GET	/api/public/works/{guid}/destinations	Active destinations for a work
GET	/api/public/search	Search profiles and works (?q=, 60/min)
POST	/api/public/analytics/events	Analytics ingestion (120/min)
GET	/api/health	Liveness probe

Creators

Creator profiles — the public page and its settings. Plan-limited.

Method	Path	Description
GET	/api/creators 🔒	List my creators
POST	/api/creators 🔒	Create creator (plan-limited)
GET	/api/creators/{guid} 🔒	Creator (admin view, includes your_role)
PATCH	/api/creators/{guid} 🔒	Update creator (edit access)
DELETE	/api/creators/{guid} 🔒	Soft-delete creator (owner only)

Series

Book series, podcasts, and collections under a creator.

Method	Path	Description
GET	/api/series 🔒	List series for a creator (?creator_guid=, paginated)
POST	/api/series 🔒	Create series (edit access)
GET	/api/series/{guid} 🔒	Series (admin view)
PATCH	/api/series/{guid} 🔒	Update series
DELETE	/api/series/{guid} 🔒	Soft-delete series

Works

Books, audiobooks, episodes, playlists. Plan-limited per profile.

Method	Path	Description
GET	/api/works 🔒	List works for a creator (?creator_guid=, paginated)
POST	/api/works 🔒	Create work (plan-limited)
GET	/api/works/{guid} 🔒	Work (admin view with creator/series/destinations)
PATCH	/api/works/{guid} 🔒	Update work
DELETE	/api/works/{guid} 🔒	Soft-delete work

Destinations

Platform links attached to works (Spotify, Audible, Amazon…).

Method	Path	Description
GET	/api/works/{guid}/destinations 🔒	List destinations (view access)
POST	/api/works/{guid}/destinations 🔒	Add destination (edit access)
PATCH	/api/destinations/{guid} 🔒	Update destination / toggle active
DELETE	/api/destinations/{guid} 🔒	Remove destination

Credits

Collaborator credits with roles; the credited creator verifies their own credit.

Method	Path	Description
GET	/api/works/{guid}/credits 🔒	List credits on a work
POST	/api/works/{guid}/credits 🔒	Add credit (creator_guid or creator_ref = slug/URL)
GET	/api/credits 🔒	Credits received by my creator (?creator_guid=) — verification inbox
PATCH	/api/credits/{guid} 🔒	Edit role/order (work editor) or toggle verified (credited creator)
DELETE	/api/credits/{guid} 🔒	Remove credit (work editor)

Team

Invite members by email with admin/editor/viewer roles.

Method	Path	Description
GET	/api/creators/{guid}/memberships 🔒	List team (manage access)
POST	/api/creators/{guid}/memberships 🔒	Add member by email (owner only)
PATCH	/api/memberships/{guid} 🔒	Change member role (owner only)
DELETE	/api/memberships/{guid} 🔒	Remove member (owner) or leave (self)

Account

Uploads, data export, and account deletion.

Method	Path	Description
POST	/api/uploads 🔒	Upload an image (multipart "file", ≤ 5 MB, 30/h)
GET	/api/account/export 🔒	Download full JSON export of your data
POST	/api/account/delete 🔒	Delete account (password required; anonymizes + revokes everything)

Billing

Stripe checkout and portal (503 until configured).

Method	Path	Description
POST	/api/billing/checkout 🔒	Create Stripe checkout session (503 until configured)
POST	/api/billing/portal 🔒	Open Stripe billing portal

Admin

Platform administration (users.is_admin required).

Method	Path	Description
GET	/api/admin/overview 🔒	Platform counts + recents (admins only)
GET	/api/admin/users 🔒	List users
PATCH	/api/admin/users/{guid} 🔒	Suspend / disable / reactivate a user (revokes sessions)
GET	/api/admin/creators 🔒	All creator profiles with owners
PATCH	/api/admin/creators/{guid} 🔒	Moderate a profile (hide/restore/delete)
GET	/api/admin/audit-logs 🔒	Security audit log (?limit= ≤ 500)

Webhooks

Inbound provider events, signature-verified.

Method	Path	Description
POST	/api/webhooks/stripe	Stripe events (signature-verified)