PRODUCT DOCUMENTATION
Get started with api & open-source development.
Choose your deployment
The standalone core uses one account and PostgreSQL schema. Configure the account identity, database, administrator credential, and private storage, then run core migrations. Start the API, dashboard, and storage worker with their documented environment settings.
Inspect the running API
Open /docs/ on the core API for Swagger, or retrieve /openapi.json. Management resources live under /v1. Use the schemas from your running version when constructing requests and handling validation errors.
Use typed management requests
The shared contracts define request and response shapes, and packages/api-client validates responses. Authenticate management requests with the account credential. Create locations, playlists, schedules, or messages through the same core operations used by the dashboard.
Build a player integration separately
Follow the OAuth device flow to obtain a player token. Discover and verify sync v1 snapshots, then implement local file verification, scheduling, audio rendering, durable progress, and reporting against the documented conformance cases.
How it works.
Account boundaries
Core routes are account-local. Standalone deployments provide a fixed account context; hosted deployments resolve it through the private control service. Account identity remains persistent when a display name, domain, or credential changes.
Contracts and replacement writes
Programming PUT routes replace a complete calendar, audience list, or schedule list transactionally. Read the current state before editing a subset. Management calendars use 0–6 weekdays and millisecond lateness; compiled sync uses ISO weekdays and seconds.
Open-source scope
The core API, dashboard, website, storage worker, and shared packages use the MIT license. The control service for hosted provisioning and orchestration is proprietary and is not required by a standalone installation.
Work through the API.
The same workflow is available through the core HTTP API. Paths below are relative to your core API origin. Your installation serves the full request and response schemas at /docs/ and /openapi.json.
| Method | Endpoint | Purpose |
|---|---|---|
GET | /openapi.json | Read the deployed core API’s machine-readable specification. |
GET | /v1/account | Inspect account identity, audio defaults, and playback settings. |
GET | /v1/search | Search management resources using the documented query schema. |
GET | /v1/sync/{syncId} | Retrieve an issued snapshot with the authorized player token. |
Things to know.
- Self-hosting requires operating PostgreSQL, private object storage, the API, dashboard, and worker. Zonecast Cloud provides the managed option with multiple accounts.
- Platform playback engines and catalog transport remain future work. Passing API tests verifies the server contract, not audible playback on a device.