# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://evenings.gitbook.io/evenings-api/api/tracks-api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.