# 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:**

```json
[
  {
    "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
"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 [**contact@evenings.email**](mailto:contact@evenings.email).