Authentication headers
Authorization: Bearer CUSTOMER_ACCESS_TOKEN X-Cascacore-Request-Id: STABLE_REQUEST_UUID
Reference.
A stable additive contract for catalog, discovery, markers, profiles, social activity, availability, events, and billing.
| Method | Path | Purpose | Credits |
|---|---|---|---|
| POST | /oauth/device/authorize | Start a customer-owned application connection | 0 |
| POST | /oauth/device/token | Poll for the approved one-time bearer credential | 0 |
| GET | /api/v1/account/credits | Get wallet balance | 0 |
| GET | /api/v1/account/usage | List usage receipts | 0 |
| GET | /api/v1/billing/rates | List the active credit tariff | 0 |
| GET | /api/v1/artwork/{sha256}/download | Download paid-account artwork for local caching | 1 |
| POST | /api/v1/catalog/search | Search the normalized media catalog | 2 / 25 |
| POST | /api/v1/catalog/identify | Identify a music track from a local acoustic fingerprint | 2 / 25 |
| GET | /api/v1/catalog/items/{cascacore_id} | Get one catalog item | 1 / 25 |
| GET | /api/v1/catalog/items/{cascacore_id}/episodes | List a show's canonical episodes | 1 / 25 |
| POST | /api/v1/catalog/candidates/{candidate_id}/select | Select an ambiguous ebook or audiobook candidate | 1 |
| GET | /api/v1/catalog/collections/{cascacore_collection_id} | Get one media collection | 1 / 25 |
| POST | /api/v1/catalog/resolve | Resolve an external media identity | 2 / 25 / 50 forced refresh |
| POST | /api/v1/catalog/upsert | Submit catalog metadata | 1 |
| GET | /api/v1/discovery/lists | List discovery feeds | 1 |
| GET | /api/v1/discovery/lists/{list_key} | Get a discovery feed | 1 / 25 |
| POST | /api/v1/events | Record a playback or library event | 1 |
| POST | /api/v1/media/markers/lookup | Look up start and end-credit markers | 1 / 25 |
| POST | /api/v1/media/markers | Submit or correct media markers | 10 |
| POST | /api/v1/profiles | Create a viewer profile | 1 |
| GET | /api/v1/profiles/{profile_id} | Get a viewer profile | 1 |
| PATCH | /api/v1/profiles/{profile_id} | Update profile identity | 1 |
| PATCH | /api/v1/profiles/{profile_id}/privacy | Update profile privacy | 1 |
| GET | /api/v1/profiles/{profile_id}/report | Get a profile media report | 1 |
| POST | /api/v1/social/friend-requests | Create a friend request | 1 |
| GET | /api/v1/social/friend-requests | List pending friend requests | 1 |
| POST | /api/v1/social/friend-requests/{request_id}/accept | Accept a friend request | 1 |
| POST | /api/v1/social/friend-requests/{request_id}/decline | Decline a friend request | 1 |
| POST | /api/v1/social/friend-requests/{request_id}/cancel | Cancel an outgoing friend request | 1 |
| POST | /api/v1/social/blocks | Block a profile | 1 |
| POST | /api/v1/social/reports | Report a profile | 1 |
| GET | /api/v1/social/friends | List friends | 1 |
| GET | /api/v1/catalog/items/{cascacore_id}/social-summary | Get social context for a catalog item | 1 |
| POST | /api/v1/availability/observations | Submit regional availability metadata | 1 |
Credit-safe retries
Reuse the same request ID for the same logical operation. HTTP 402 means the customer's wallet needs credits; local playback and library access should continue.
Read the integration guide →