> For the complete documentation index, see [llms.txt](https://evenings.gitbook.io/evenings-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://evenings.gitbook.io/evenings-api/api/tracks-api-documentation.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.