Headless API · Use cases

What can I build with public artist data?

Start with an artist website, metadata-only discography, portfolio embed, static page, or public-data tool.

Headless fits when you own the frontend and need public artist identity or Catalog metadata. It does not provide media, lyrics, tour dates, analytics, fan data, private data, or playback.

Start with an artist website

Read /connor on your server, map only the public response fields, and render an explicit unavailable state.

export async function loadConnorPage() {
  const [artist, catalog] = await Promise.all([
    casset.getArtist("connor"),
    casset.getCatalog("connor"),
  ])

  return {
    title: artist.artist.displayName,
    bio: artist.artist.bio,
    profileUrl: artist.links.profile,
    tracks: catalog.tracks.map(({ title, kind, durationSec }) => ({
      title,
      kind,
      durationSec,
    })),
  }
}

Available: public bio, verified state, Profile World link, and metadata-only Track list.
Unavailable: cover art, streaming, raw audio, lyrics, social counts, fan identity, and commerce.

Fit matrix

Headless API integration fit
Use case	Fit today	What Casset v1 supplies	What you must supply	Why not a Native App?
Artist website	Good contract fit; evaluation only	Public name, handle, biography, verified state, and Track metadata	Layout, hosting, media, links, SEO, and deployment	The site owns its URL and application lifecycle outside Casset.
Tour microsite	Partial	Artist identity and Catalog context	Tour dates, venues, ticket links, media, and launch operations	The tour site is an external destination; a Native App belongs inside the Profile World.
Launch microsite	Partial	Public artist identity and active Track metadata	Release timing, campaign data, media, commerce, and launch state	The developer owns the launch URL and presentation outside Casset.
Interactive discography	Good metadata fit	Ordered active Track titles, ORIGINAL / GENERATION kind, and duration	Artwork, audio, release grouping, filters, and playback	Use Native Apps only when the experience must live inside Casset and observe its runtime.
Lyrics explorer	Unavailable from v1 alone	No lyric field	All lyric content, timing, rights, and playback	Headless is the right external model, but the current contract is insufficient. Native App status does not make Headless lyrics exist.
Fan dashboard	Unavailable	No fan identity or engagement data	Fans, accounts, events, metrics, and authorization	A dashboard is external, but Casset deliberately does not expose the required private data.
Internal dashboard	Limited public-data fit	Public identity and Catalog metadata only	Private operations, account data, moderation, or analytics	Use Headless only for a public-data review tool; product-internal routes are not a supported external API.
Analytics dashboard	Unavailable	No analytics or event metrics	All measurement data and calculations	Neither Headless access nor Native App installation grants analytics data.
AI agent	Limited read-only fit	Public artist identity and Catalog metadata	Agent orchestration, storage, decisions, citations, and any private authorization	An external agent is not an installed Profile World experience. The private operator Agent API is not a developer credential.
Portfolio embed	Good metadata fit	Artist identity and Track list	Embed shell, responsive layout, media, and host-site policy	The portfolio owns the embedding page outside Casset.
Static site	Good contract fit; unsupported alpha	Deterministic public JSON for build-time rendering	Build pipeline, caching, hosting, and fallback data	Static output has no Artist Runtime and should not pretend to be a native App.

Interactive discography

v1 can drive sorting or presentation over one bounded list, but it exposes no filter API and no release grouping. With at most 500 Tracks, any client-side filtering is your application behavior, not a Headless query feature.

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

const originals = catalog.tracks.filter((track) => track.kind === "ORIGINAL")
const generations = catalog.tracks.filter((track) => track.kind === "GENERATION")

Static site or portfolio embed

The contract is deterministic enough for build-time rendering, but the deployed alpha endpoint is not supported for production use and may return the intentional fail-closed 503 state. Use exact mocks for evaluation. Do not design a production cache around availability Casset does not currently promise.

Tour or launch microsite

Use Headless only for the artist and Catalog portion. Keep schedules, ticket links, release dates, campaign state, artwork, and media in a separate source you control. Never label those fields as Casset data.

Internal public-data tool

A read-only QA or catalog browser can use Headless. An admin dashboard cannot: Studio, commerce, room, and product-internal routes are cookie-authenticated implementation details, not third-party contracts.

AI agent

An agent may summarize only the returned public identity and Track metadata. It cannot infer usage rights, private releases, fan data, provenance beyond the Track kind, or permission to play, download, remix, train on, or publish media.

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

const publicContext = {
  artist: artist.artist,
  tracks: catalog.tracks,
  source: artist.links.profile,
}

// Give the agent publicContext only.
// Do not add credentials, internal records, or inferred permissions.

When to stop

Stop if the product requires private or unpublished artist data.
Stop if it needs audio, artwork URLs, lyrics, fans, analytics, commerce, or playback.
Stop if it requires production credentials or durable production webhooks.
Choose a Native App only when the intended surface is inside Casset and the reviewed host contract supplies the needed context.

Start with an artist website

Read /connor on your server, map only the public response fields, and render an explicit unavailable state.

export async function loadConnorPage() { const [artist, catalog] = await Promise.all([ casset.getArtist("connor"), casset.getCatalog("connor"), ]) return { title: artist.artist.displayName, bio: artist.artist.bio, profileUrl: artist.links.profile, tracks: catalog.tracks.map(({ title, kind, durationSec }) => ({ title, kind, durationSec, })), } }

Available: public bio, verified state, Profile World link, and metadata-only Track list.

Unavailable: cover art, streaming, raw audio, lyrics, social counts, fan identity, and commerce.

Fit matrix

Headless API integration fit
Use case	Fit today	What Casset v1 supplies	What you must supply	Why not a Native App?
Artist website	Good contract fit; evaluation only	Public name, handle, biography, verified state, and Track metadata	Layout, hosting, media, links, SEO, and deployment	The site owns its URL and application lifecycle outside Casset.
Tour microsite	Partial	Artist identity and Catalog context	Tour dates, venues, ticket links, media, and launch operations	The tour site is an external destination; a Native App belongs inside the Profile World.
Launch microsite	Partial	Public artist identity and active Track metadata	Release timing, campaign data, media, commerce, and launch state	The developer owns the launch URL and presentation outside Casset.
Interactive discography	Good metadata fit	Ordered active Track titles, ORIGINAL / GENERATION kind, and duration	Artwork, audio, release grouping, filters, and playback	Use Native Apps only when the experience must live inside Casset and observe its runtime.
Lyrics explorer	Unavailable from v1 alone	No lyric field	All lyric content, timing, rights, and playback	Headless is the right external model, but the current contract is insufficient. Native App status does not make Headless lyrics exist.
Fan dashboard	Unavailable	No fan identity or engagement data	Fans, accounts, events, metrics, and authorization	A dashboard is external, but Casset deliberately does not expose the required private data.
Internal dashboard	Limited public-data fit	Public identity and Catalog metadata only	Private operations, account data, moderation, or analytics	Use Headless only for a public-data review tool; product-internal routes are not a supported external API.
Analytics dashboard	Unavailable	No analytics or event metrics	All measurement data and calculations	Neither Headless access nor Native App installation grants analytics data.
AI agent	Limited read-only fit	Public artist identity and Catalog metadata	Agent orchestration, storage, decisions, citations, and any private authorization	An external agent is not an installed Profile World experience. The private operator Agent API is not a developer credential.
Portfolio embed	Good metadata fit	Artist identity and Track list	Embed shell, responsive layout, media, and host-site policy	The portfolio owns the embedding page outside Casset.
Static site	Good contract fit; unsupported alpha	Deterministic public JSON for build-time rendering	Build pipeline, caching, hosting, and fallback data	Static output has no Artist Runtime and should not pretend to be a native App.

Interactive discography

const catalog = await casset.getCatalog("connor") const originals = catalog.tracks.filter((track) => track.kind === "ORIGINAL") const generations = catalog.tracks.filter((track) => track.kind === "GENERATION")

Static site or portfolio embed

AI agent

const artist = await casset.getArtist("connor") const catalog = await casset.getCatalog("connor") const publicContext = { artist: artist.artist, tracks: catalog.tracks, source: artist.links.profile, } // Give the agent publicContext only. // Do not add credentials, internal records, or inferred permissions.

When to stop

Stop if the product requires private or unpublished artist data.

Stop if it needs audio, artwork URLs, lyrics, fans, analytics, commerce, or playback.

Stop if it requires production credentials or durable production webhooks.

Choose a Native App only when the intended surface is inside Casset and the reviewed host contract supplies the needed context.