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

Most endpoints require authentication using an API key. To get an API key, see our documentation on how to setup your API key.

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",
    "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"
}

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"

Error Responses

• 404 Not Found: When a requested resource is not found

• 400 Bad Request: When the request is malformed or missing required fields

• 500 Internal Server Error: When an unexpected error occurs on the server

Error messages typically include a human-readable description of the error.

Questions

If you have any questions or feedback, please contact us at [e-mail].