Build with Casset artist data.

Use Headless when you own the website, tool, or service. It provides public artist identity and active Catalog metadata. If the experience should live inside an artist's Profile World, build a reviewed Casset App instead.

Choose your path

• I want public artist data. Download the mocked starter and get a page running.
• I want to build inside Casset. Start with the reviewed Casset Apps model.
• I need the full technical reference. See every field, status, header, and cache rule.

Get something working

The generated React starter opens against the exact built-in SDK mock. It needs no Casset account, credential, or production request.

curl -LO https://casset.fm/downloads/casset-api/casset-headless-react-v0.2.0-alpha.0.zip
unzip casset-headless-react-v0.2.0-alpha.0.zip
cd casset-headless-react
pnpm install
pnpm dev

Against a local Casset server, the same client reads the public/connor Artist and Catalog shapes:

import { createCassetClient } from "@casset/apps"

const casset = createCassetClient({
  baseUrl: "http://127.0.0.1:3000",
})

const artist = await casset.getArtist("connor")
const catalog = await casset.getCatalog("connor")

What works today

• GET /api/v1/artists/[handle] returns bounded public identity and canonical links.
• GET /api/v1/artists/[handle]/catalog returns up to 500 active Track titles, kinds, and durations in one page.
• @casset/apps provides strict parsing, a TypeScript client, request IDs, timeouts, bounded GET retries, typed errors, and exact mocks.
• @casset/react adds providers and query hooks when the frontend uses React.
• The generated React starter runs exact mocks by default and can proxy a local sandbox credential from its development server.

What can I build?

• Artist websites, metadata-only discographies, and portfolio embeds.
• Static pages and public-data tools built from artist identity and Track metadata.
• Read-only agent context that cites the artist's canonical Profile World.

What is unavailable?

Headless does not expose database IDs, private profiles, unreleased Tracks, fan identity, commerce state, artwork or audio URLs, credentials, raw theme data, playback state, lyrics, tour dates, analytics, or runtime functions. Unknown, private, and unpublished artists produce the same 404. Production credentials and production webhook delivery are unavailable.

How the pieces fit

                            Casset source of truth
                                      │
                 ┌────────────────────┴────────────────────┐
                 │                                         │
        Build inside Casset                       Build beyond Casset
                 │                                         │
          Native Casset App                       Headless API v1
                 │                                         │
          Artist Runtime                          @casset/apps
                 │                                         │
   Profile World + MediaFooter                    @casset/react (optional)
                 │                                         │
      Casset owns playback                    Developer application

Casset controls: publication, public data selection, privacy, schema validation
Developer controls: external UI, hosting, caching, application behavior
Authentication: Native host grants inside Casset · public v1 none · sandbox Bearer on loopback only
Availability: Native reviewed runtime is private production · Headless v1 is deployed but unsupported for production use
Never delegated: private artist data, raw media, playback clock, native App grants

The products are complementary, not a serial stack. Native Apps enter the Artist Runtime. Headless reads a separate public boundary. The React adapter sits over the framework-neutral client; it is optional and does not change the HTTP contract.

Headless API or Casset Apps?

Availability at a glance

Where to go next

• Examples — try the /connor Artist and Catalog states without a network request.
• Use cases — check whether the current public fields fit your idea.
• SDK and React adapter — connect the typed client.
• Errors, retries, and safe logging — design failure handling.
• Availability & limitations — read the complete alpha boundary.