Tracks API Documentation

This document outlines the available endpoints for managing tracks in the Evenings.fm API.

Base URL

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

Authentication

All endpoints require authentication using an API key, sent as a bearer token:

Authorization: Bearer <your-api-key>

To get an API key, see our documentation on how to set up your API key.

Publish Track and Unpublish Track currently require a user session token instead of an API key — see the notes on those endpoints.

Endpoints

1. List Tracks

Retrieves a paginated list of tracks for a station.

• URL: /tracks
• Method: GET
• Auth Required: Yes
• Query Parameters:
  • page (optional): Page number (default: 0)
  • limit (optional): Number of items per page (default: 100)
  • tags (optional): Comma-separated list of tags to filter by

Response:

[
  {
    "id": "string",
    "title": "string",
    "description": "string",
    "host": "string",
    "tags": ["string"],
    "url": "string",
    "location": "string",
    "filename": "string",
    "duration": "number",
    "filetype": "string",
    "image": "string",
    "stationId": "string",
    "published": "boolean",
    "publishedAt": "string | null",
    "createdAt": "string",
    "updatedAt": "string",
    "listens": "number"
  }
]

Headers:

• x-page: Current page number
• x-page-size: Number of items per page
• x-total: Total number of tracks

2. Create Track

Uploads a new track to a station.

• URL: /tracks
• Method: POST
• Auth Required: Yes
• Content-Type: multipart/form-data
• Body:
  • file: Audio file (required)

Response:

{
  "id": "string",
  "title": "string",
  "stationId": "string",
  "location": "string",
  "filename": "string",
  "duration": "number",
  "filetype": "string"
}

3. Get Track

Retrieves details of a specific track.

• URL: /tracks/:id
• Method: GET
• Auth Required: Yes

Response:

{
  "id": "string",
  "title": "string",
  "description": "string",
  "host": "string",
  "tags": ["string"],
  "url": "string",
  "location": "string",
  "filename": "string",
  "duration": "number",
  "filetype": "string",
  "image": "string",
  "stationId": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "listens": "number"
}

4. Update Track

Updates details of a specific track.

• URL: /tracks/:id
• Method: PATCH
• Auth Required: Yes
• Body:

{
  "title": "string",
  "description": "string",
  "host": "string",
  "tags": ["string"],
  "url": "string",
  "published": "boolean"
}

All fields are optional; only the fields you send are updated.

Response: Updated track object (same as Get Track response).

5. Add Track Image

Adds an image to a track.

• URL: /tracks/:id/images
• Method: POST
• Auth Required: Yes
• Content-Type: multipart/form-data
• Body:
  • file: Image file (required)

Response: Updated track object (same as Get Track response).

6. Delete Track Image

Removes the image from a track.

• URL: /tracks/:id/images
• Method: DELETE
• Auth Required: Yes

Response: Updated track object (same as Get Track response).

7. Delete Track

Deletes a specific track.

• URL: /tracks/:id
• Method: DELETE
• Auth Required: Yes

Response:

"Success! Replay deleted"

8. Publish Track

Makes a track publicly visible.

• URL: /tracks/:id/publish
• Method: POST
• Auth Required: Yes — user session token only (API keys are not currently supported for this endpoint)

Response:

{ "message": "Success! Track published" }

9. Unpublish Track

Hides a previously published track.

• URL: /tracks/:id/publish
• Method: DELETE
• Auth Required: Yes — user session token only (API keys are not currently supported for this endpoint)

Response:

{ "message": "Success! Track unpublished" }

Error Responses

• 404 Not Found: When a requested resource is not found
• 400 Bad Request: When the request is malformed or missing required fields
• 401 Unauthorized: When the API key or token is missing or invalid
• 500 Internal Server Error: When an unexpected error occurs on the server

Error messages include a human-readable description. Depending on the endpoint, the body may be a JSON object ({ "error": "..." } or { "message": "..." }) or a plain string.

Questions

Looking to display a station's schedule? See the Events API.

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