How to Configure LoovaCast’s Scheduler API for Dynamic Radio Automation Across Multiple Shows

The three core endpoints you’ll use most often are:

• POST /v1/schedules – create a new schedule entry.
• GET /v1/schedules/{id} – retrieve details of an existing entry.
• PUT /v1/schedules/{id} – update timestamps, playlists, or fallback content.

Each request returns a JSON payload. A successful POST gives you an id, status, and the exact utc_start and utc_end you supplied. Errors follow the standard LoovaCast error schema, with a numeric code and a human‑readable message. Knowing the shape of these responses saves you hours of debugging later on.

With the basics under your belt, you’re ready to start building a reliable online radio setup that runs itself while you focus on content.

Setting Up Your First Show Schedule

Now that you have a token, let’s create a concrete schedule entry. The first API call you’ll make is POST /v1/schedules. In the body you’ll include a title, utc_start, utc_end, and a reference to the playlist or live source you want to play.

Here’s a sample JSON payload:

{
  "title": "Morning Chillout",
  "utc_start": "2026-04-01T07:00:00Z",
  "utc_end":   "2026-04-01T09:00:00Z",
  "playlist_id": "pl_abc123",
  "fallback_playlist_id": "pl_fallback456"
}

Notice the timestamps are in UTC. That’s intentional: LoovaCast stores everything in UTC to avoid daylight‑saving headaches. Once the schedule is saved, you’ll get an id you can reference later for updates.

When you attach a curated playlist, make sure the playlist items themselves have proper duration metadata. LoovaCast will automatically trim or loop tracks to match the exact utc_end you set, but mismatched durations can cause a silent gap or an abrupt cut‑off.

After the API confirms the schedule, you can verify it on the LoovaCast dashboard. The UI will show a visual timeline with your show highlighted in green, fallback content in gray, and any overlapping slots flagged in red. If you see a red warning, adjust the utc_start or utc_end until the conflict disappears.

That’s the core of a solid online radio setup: precise timing, reliable playlists, and a safety net for unexpected hiccups.

Configuring Dynamic Rotation for Multiple Shows

One show after another can become tedious to schedule manually, especially when you run a 24/7 station. LoovaCast solves this with recurrence rules (RRULE), a standard iCalendar syntax that tells the Scheduler API how often a show repeats.

To add a recurrence, include an rrule field in your POST /v1/schedules payload. For example, a weekly show that airs every Monday at 14:00 UTC looks like this:

{
  "title": "Tech Talk Tuesday",
  "utc_start": "2026-04-02T14:00:00Z",
  "utc_end":   "2026-04-02T15:30:00Z",
  "rrule": "FREQ=WEEKLY;BYDAY=TU;COUNT=52",
  "playlist_id": "pl_tech456"
}

The COUNT parameter limits the recurrence to 52 weeks, but you can also use UNTIL=2027-04-02T15:30:00Z for an end date. LoovaCast will automatically generate the individual entries behind the scenes, so you only need to maintain one JSON object.

Overlap handling is another crucial piece. If two shows are scheduled to start at the same moment, LoovaCast will prioritize the one with the higher priority value (default is 0). You can also define a fallback_playlist_id that plays whenever a scheduled slot has no live source. This ensures there’s never dead air, which is a cardinal rule for any online radio setup.

For stations that broadcast live events, you might want a “break‑in” rule: if a live source becomes unavailable, LoovaCast instantly swaps to the fallback playlist. To enable this, set auto_fallback: true in the schedule object. The system monitors the health of your live ingest (RTMP, SRT, or Icecast) and flips over in less than two seconds.

By combining RRULEs with smart overlap handling and fallback playlists, you build a resilient rotation that scales from a handful of shows to dozens without manual re‑entry. That’s the power behind a professional online radio setup.

Integrating Broadcast Encoding Settings

Even the best schedule is useless if the audio stream can’t be received. LoovaCast lets you pick the codec, bitrate, and sample rate that best match your audience’s bandwidth and device mix. Most modern browsers and mobile apps handle AAC at 128 kbps flawlessly, while older MP3 players still prefer 128‑256 kbps MP3 streams.

Here’s a quick decision matrix:

• AAC (LC) – Best quality at lower bitrates, ideal for mobile listeners on 3G/4G.
• MP3 – Universal compatibility, but needs higher bitrate for comparable quality.
• Opus – Emerging standard, great for low‑latency, but not yet supported by all hardware radios.

Set your encoding preferences in the LoovaCast dashboard under Settings → Encoding, or push them via the API with PATCH /v1/encoders/{id}. The JSON looks like this:

{
  "codec": "aac",
  "bitrate_kbps": 192,
  "sample_rate_hz": 44100
}

After you save, run a short test stream. Use a local encoder (OBS, Nicecast, or a hardware unit) and point it to the ingest URL LoovaCast provides. Listen on a variety of devices—desktop, smartphone, and even a car radio—to confirm there’s no clipping or buffering.

When the test finishes without hiccups, you’ve locked in the core audio parameters of your online radio setup. From here you can safely publish schedules knowing every listener will receive clean, consistent sound.

Testing and Monitoring Your Automation

Automation is only as good as the testing you perform. LoovaCast provides a sandbox endpoint (POST /sandbox/schedules) that mimics the live environment without actually broadcasting. Push a copy of your schedule there, then call GET /sandbox/logs to see a timeline of simulated playbacks.

The sandbox will flag:

• Time‑zone mismatches (e.g., a show scheduled at 02:00 UTC but marked as 02:00 local).
• Missing playlist items or dead URLs.
• Overlap conflicts that would cause a fallback to trigger.

Real‑time logs are accessible via GET /v1/logs?stream=live. Filter by schedule_id to watch a single show’s lifecycle. If an error occurs—say, a live ingest drops—the log will include an error code (e.g., INGEST_TIMEOUT) and a timestamp. You can set up webhook alerts to push these events to Slack, Discord, or email.

Beyond logs, LoovaCast can send SMS alerts for critical failures (e.g., encoder offline for more than 30 seconds). Configure these under Alerts → SMS. Pairing SMS with email ensures you’ll notice problems even when you’re away from the dashboard.

By routinely running sandbox simulations, watching live logs, and configuring alerts, you turn a static online radio setup into a self‑healing system that keeps listeners tuned in, no matter what.

Best Practices & Common Pitfalls

Even with a perfect API call, many broadcasters stumble over the same issues. Below are the top three lessons we’ve learned from years of supporting LoovaCast stations.

1. Store times in UTC, convert locally. The Scheduler API expects UTC, and LoovaCast stores everything that way. If you convert to local time before sending, daylight‑saving changes will shift your schedule by an hour. Keep the conversion logic in your front‑end UI, not in the API payload.

2. Graceful error handling for rate limits. LoovaCast enforces a 60‑request‑per‑minute limit on the Scheduler API. If you exceed it, you’ll receive a 429 Too Many Requests response with a retry_after header. Implement exponential back‑off in your code to avoid cascading failures.

3. Batch requests as you scale. When you have dozens of shows, send them in batches using POST /v1/schedules/batch. This reduces network overhead and keeps you safely under the rate limit. Each batch returns an array of results, letting you spot failures instantly.

Following these best practices will make your online radio setup robust, maintainable, and ready for growth. Remember, the Scheduler API is a tool—not a replacement for solid planning. Pair it with clear documentation, regular testing, and a pinch of patience, and your station will run like a well‑tuned orchestra.

Ready to launch your station? Get started with LoovaCast — your radio, your way.