Events API Documentation

The Events API lets anyone read a station's public event calendar — no API key required. Use it to embed upcoming broadcasts on your own website, build a custom calendar, or link listeners to an event page.

Every published event also has a shareable page at https://evenings.fm/e/:id, which is returned as url in API responses.

Base URL

All endpoints are relative to: https://api.evenings.co/v1

Authentication

None required. The endpoints on this page are public and rate limited to 50 requests per minute per IP. Exceeding the limit returns 429 Too Many Requests.

If you are the station owner, you may optionally pass your session token (Authorization: Bearer <token>) to the List Station Events endpoint to also receive unpublished events, internal fields, and live broadcast status. Sending an invalid or expired token returns 401 — it is never silently treated as a public request.

Endpoints

1. List Station Events

Retrieves a station's published events within a date range.

• URL: /stations/:slug/events
• Method: GET
• Auth Required: No
• URL Parameters:
  • slug: The station's URL slug (e.g. blue-radio for evenings.fm/blue-radio)
• Query Parameters:
  • startDate (optional): ISO 8601 date (e.g. 2026-07-01). Defaults to the start of the current month.
  • endDate (optional): ISO 8601 date. Defaults to the end of the current month.
  • When both dates are provided, endDate must be on or after startDate and the range may span at most 45 days.

Example:

GET /v1/stations/blue-radio/events?startDate=2026-07-01&endDate=2026-07-31

Response:

[
  {
    "id": "abc123def4",
    "title": "Tuesday Sessions",
    "host": "DJ Name",
    "description": "Weekly vibes",
    "image": "https://cdn.evenings.co/img/abc.jpg",
    "startAt": "2026-07-07T20:00:00.000Z",
    "endAt": "2026-07-07T22:00:00.000Z",
    "timezone": "America/New_York",
    "recurrence": "weekly",
    "status": "scheduled",
    "url": "https://evenings.fm/e/abc123def4"
  }
]

Only published events are returned, and only the fields above — internal fields are never included. startAt/endAt are UTC timestamps; timezone is the event's display timezone.

Station owners: the same URL called with your session token returns all events (including unpublished), the full event object, and — for an event currently broadcasting today — live online and listeners fields. A token for a different station is treated as a public request.

2. Get Event

Retrieves a single published event, including its station.

• URL: /events/:id
• Method: GET
• Auth Required: No
• URL Parameters:
  • id: The event id, as returned by List Station Events (also the id in the event's url)

Response:

{
  "id": "abc123def4",
  "title": "Tuesday Sessions",
  "host": "DJ Name",
  "description": "Weekly vibes",
  "image": "https://cdn.evenings.co/img/abc.jpg",
  "startAt": "2026-07-07T20:00:00.000Z",
  "endAt": "2026-07-07T22:00:00.000Z",
  "timezone": "America/New_York",
  "recurrence": "weekly",
  "status": "scheduled",
  "url": "https://evenings.fm/e/abc123def4",
  "station": {
    "name": "Blue Radio",
    "slug": "blue-radio",
    "image": "https://cdn.evenings.co/img/station.jpg"
  },
  "attendeeCount": 12
}

Unpublished or unknown events return 404, so an unpublished event's existence is never revealed.

Station owners: calling this endpoint with your session token returns the full event object for your own events, including unpublished ones.

GET /v1/events/public/:id is deprecated in favor of this endpoint. It continues to work, but new integrations should use GET /v1/events/:id.

Embedding events on your website

A minimal example that renders a station's upcoming events as links:

<ul id="events"></ul>
 
<script>
  const slug = "blue-radio"; // your station's slug
 
  fetch(`https://api.evenings.co/v1/stations/${slug}/events`)
    .then((res) => res.json())
    .then((events) => {
      const list = document.getElementById("events");
      for (const event of events) {
        const item = document.createElement("li");
        const link = document.createElement("a");
        link.href = event.url;
        const date = new Date(event.startAt).toLocaleString(undefined, {
          dateStyle: "medium",
          timeStyle: "short",
        });
        link.textContent = `${event.title} — ${date}`;
        item.appendChild(link);
        list.appendChild(item);
      }
    });
</script>

Without query parameters this returns the current month's events. Pass startDate and endDate to show a different window (up to 45 days at a time).

Error Responses

Questions

Looking to manage tracks programmatically? See the Tracks API.

If you have any questions or feedback, please contact us at contact@evenings.email.