The boundary, without the fine-print hunt.
Short answers to the architectural and availability questions a senior engineer should resolve before integrating.
The shortest answer: Native Apps build inside Casset. Headless builds beyond Casset. Reviewed first-party Native Apps use a Production / private runtime. Public Headless v1 is deployed as two unauthenticated GET routes, but it is not available for supported production use and may intentionally fail closed with 503 ResourceUnavailable.
Product model
Why Headless?
To let a developer-owned website, tool, service, or agent read public artist identity and Catalog metadata without embedding Casset's UI or inheriting the Artist Runtime. It is the external read boundary, not a second version of the native App system.
Why separate Native Apps from Headless?
They have different owners. Casset owns a Native App's frame, permissions, lifecycle, safe areas, and playback context inside a Profile World. The developer owns a Headless application's frontend, hosting, URL, and lifecycle outside Casset. Combining them would blur security and product expectations.
Why not GraphQL?
v1 has two bounded read shapes. REST keeps route versioning, caching, rate limiting, privacy review, exact mocks, and strict response parsing obvious. Casset is not claiming that GraphQL is categorically wrong; it is unnecessary for the implemented surface.
Why can't Headless control playback?
Playback has one canonical owner inside Casset. Headless receives no media URL, audio token, playback clock, transport function, or MediaFooter control. This preserves deterministic playback and prevents a public data read from becoming a media entitlement.
Authentication and data
Does public v1 require a credential?
No. /api/v1 is an unauthenticated public read boundary. A Bearer credential is used only by the matching loopback-only /api/sandbox/v1 routes during local development.
Why are credentials sandbox-only?
Durable production developer identity, issuance, grants, persistence, revocation, and audit history do not exist. The local sandbox can prove one-time reveal and immediate process-local revocation without pretending to be that production system.
Can Headless read private artists or unreleased tracks?
No. Database selection requires a published, non-private artist. Unknown, private, and unpublished handles all return the same 404, and active public Track metadata is the only Catalog data selected.
Can I fetch audio, artwork, lyrics, analytics, or fans?
No. None of those fields exist in v1. The API also omits tour dates, release campaign state, commerce, raw theme data, internal IDs, and storage links.
Packages and runtime
Why aren't the packages published to npm?
They are private repository-local alpha packages. A public registry release would require compiled artifacts, an external compatibility policy, isolated runtime expectations, and a public distribution process. The current package names do not imply that those have shipped.
How do I use the packages outside this repository?
Download the generated Headless React ZIP. It vendors the exact@casset/apps and @casset/react source as local file dependencies. Do not replace them with registry ranges.
Why is React separate from the core SDK?
HTTP contracts, parsers, retries, errors, and mocks do not require React. The separate adapter adds providers and query hooks while preserving a framework-neutral core and one transport behavior.
Why no arbitrary App execution?
The current native runtime is for reviewed first-party Apps. External submission, arbitrary bundle isolation, signing, admission, and production review infrastructure are unavailable. A downloadable starter is a local development artifact, not permission to execute code inside Casset.
Operations
Are webhooks production-ready?
No. The local sandbox rehearses HMAC signing, transient retries, one-time secrets, immutable event replay, and duplicate suppression. Its state resets with the process. Durable production webhook delivery is unavailable.
Can I use the deployed base URL in production?
No. casset.fm/api/v1 is deployed, but it must not be treated as a supported production integration. Requests may intentionally fail closed with 503 ResourceUnavailable, and Casset offers no uptime, availability, or production-use commitment during this alpha. The two public GET routes require no credential; production developer credentials remain unavailable.
What is the private Operator Agent API?
It is an existing deployment-wide operator key for selected automation routes. It is Production / private and is not a developer credential, public Headless contract, or path to private artist access.