Headless API v1 reference.

These routes are deployed, but they are not currently available for supported production use. Requests may intentionally fail closed with 503 ResourceUnavailable. No uptime, availability, or production-use commitment is offered.

Endpoints

GET /api/v1/artists/{handle}
GET /api/v1/artists/{handle}/catalog

Before you call the API

Get public artist

GET /api/v1/artists/{handle}

Returns bounded public identity for one published, non-private Profile World. It never returns an internal artist or user ID.

curl

curl --include \
  --header "Accept: application/json" \
  --header "X-Request-Id: reference-artist-001" \
  http://127.0.0.1:3000/api/v1/artists/connor

TypeScript

const artist = await casset.getArtist("connor", {
  requestId: "reference-artist-001",
})

console.log(artist.artist.displayName)
console.log(artist.links.catalog)

200 response

HTTP/1.1 200 OK
Cache-Control: public, max-age=0, must-revalidate
Content-Type: application/json
X-Request-Id: reference-artist-001

{
  "schema": "casset.public-artist.v1",
  "artist": {
    "handle": "connor",
    "displayName": "Connor James",
    "bio": "Multi-instrumentalist, singer/songwriter, and producer.",
    "verified": true
  },
  "links": {
    "profile": "http://127.0.0.1:3000/connor",
    "catalog": "http://127.0.0.1:3000/api/v1/artists/connor/catalog"
  }
}

Empty response

Fields

Get public Catalog

GET /api/v1/artists/{handle}/catalog

Returns one bounded page of active public Track metadata. It contains no cursor, filter, audio, artwork, lyric, storage, or playback field.

curl

curl --include \
  --header "Accept: application/json" \
  --header "X-Request-Id: reference-catalog-001" \
  http://127.0.0.1:3000/api/v1/artists/connor/catalog

TypeScript

const catalog = await casset.getCatalog("connor", {
  requestId: "reference-catalog-001",
})

for (const track of catalog.tracks) {
  console.log(track.title, track.kind, track.durationSec)
}

200 response

HTTP/1.1 200 OK
Cache-Control: public, max-age=0, must-revalidate
Content-Type: application/json
X-Request-Id: reference-catalog-001

{
  "schema": "casset.public-catalog.v1",
  "artist": {
    "handle": "connor",
    "displayName": "Connor James"
  },
  "tracks": [
    {
      "title": "Baby Blue",
      "kind": "ORIGINAL",
      "durationSec": 213
    }
  ],
  "page": { "count": 1 }
}

Empty 200 response

HTTP/1.1 200 OK
Cache-Control: public, max-age=0, must-revalidate
Content-Type: application/json
X-Request-Id: reference-catalog-empty-001

{
  "schema": "casset.public-catalog.v1",
  "artist": {
    "handle": "connor",
    "displayName": "Connor James"
  },
  "tracks": [],
  "page": { "count": 0 }
}

Fields

Failure matrix for both endpoints

The following responses apply to both public paths. Their sandbox read counterparts add credential failure and return the same error schema; ownership failures belong to the separate sandbox console.

400 — invalid handle

HTTP/1.1 400 Bad Request
Cache-Control: private, no-store
Content-Type: application/json
X-Request-Id: reference-invalid-001

{
  "schema": "casset.error.v1",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "A valid artist handle is required.",
    "requestId": "reference-invalid-001",
    "retryable": false
  }
}

404 — unknown, private, or unpublished

HTTP/1.1 404 Not Found
Cache-Control: private, no-store
Content-Type: application/json
X-Request-Id: reference-not-found-001

{
  "schema": "casset.error.v1",
  "error": {
    "code": "RESOURCE_UNAVAILABLE",
    "message": "Artist not found.",
    "requestId": "reference-not-found-001",
    "retryable": false
  }
}

401 — local sandbox only

HTTP/1.1 401 Unauthorized
Cache-Control: no-store, private
Content-Type: application/json
X-Request-Id: sandbox-auth-001

{
  "schema": "casset.error.v1",
  "error": {
    "code": "INVALID_CREDENTIAL",
    "message": "A valid Bearer sandbox credential is required.",
    "requestId": "sandbox-auth-001",
    "retryable": false
  }
}

403 — local sandbox console permission failure only

HTTP/1.1 403 Forbidden
Cache-Control: no-store, private
Content-Type: application/json
X-Request-Id: sandbox-permission-001

{
  "schema": "casset.error.v1",
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "The app belongs to a different sandbox developer.",
    "requestId": "sandbox-permission-001",
    "retryable": false
  }
}

429 — public rate limit

HTTP/1.1 429 Too Many Requests
Cache-Control: private, no-store
Content-Type: application/json
Retry-After: 17
X-Request-Id: reference-rate-001

{
  "schema": "casset.error.v1",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Try again after the retry window.",
    "requestId": "reference-rate-001",
    "retryable": true
  }
}

503 — public service failure

HTTP/1.1 503 Service Unavailable
Cache-Control: private, no-store
Content-Type: application/json
X-Request-Id: reference-service-001

{
  "schema": "casset.error.v1",
  "error": {
    "code": "INTEGRATION_FAILURE",
    "message": "The public catalog service is temporarily unavailable.",
    "requestId": "reference-service-001",
    "retryable": true
  }
}

Public media and Hooks · local extension

Enable CASSET_PUBLIC_MEDIA_ENABLED=true only in your reviewed local server process. This independent, default-off flag does not enable audio playback. The extension reads existing public assets and selected Hook visuals; it creates no upload, storage, rendering or SDK system. The full contract is in docs/api/public-media.md.

GET /api/v1/artists/{handle}/media?source=profile&limit=25
GET /api/v1/artists/{handle}/media?source=bonus&type=IMAGE
GET /api/v1/artists/{handle}/track/media?title=...&kind=...&order=...
GET /api/v1/artists/{handle}/track/hooks?title=...&kind=...&order=...
GET /api/v1/artists/{handle}/hook?title=...&kind=...&order=...

Use exact public title, provenance kind and stored sequence order from the existing playback selector. Artist and Track IDs remain server-side. Casset stores one canonical Hook window per Track; follow the Hook’s returnedhref for detail. Renames/reorders invalidate old links.

const response = await fetch(cassetOrigin + "/api/v1/artists/connor/media?category=BTS", {
  credentials: "omit", cache: "no-store"
});
if (!response.ok) throw new Error("Casset media: " + response.status);
const page = await response.json();
// Use media.url directly in <img> / <video>; thumbnailUrl is the saved poster.
// Continue with page.nextOffset until null.

Send an approved Origin (browsers supply it automatically), without cookies or credentials. Local inspection found no published Starlight visual: Track media correctly returns an empty list and visualizer is null. No example asset is presented as production data. This extension has not been deployed by this work.

Privacy behavior

• Private, unpublished, and unknown artists are indistinguishable at the HTTP boundary.
• Catalog reads select only active Track title, kind, and duration.
• Strict SDK parsers reject unknown response fields instead of silently accepting data expansion.
• Error responses use private, no-store; sandbox responses use no-store, private.

Read Errors for the full typed-error matrix and Retries before implementing custom transport behavior.