> 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/getting-started.md).

# Getting Started

Welcome to the Evenings API! Whether you’re building an application or integrating with our streaming service, this guide will help you get started smoothly. In just a few steps, you'll be ready to interact with the Evenings API to enhance your application with our stations' information.

### Step 1: Understanding the Evenings API

The Evenings API provides endpoints to retrieve information about stations, tracks, and stream status. Familiarize yourself with the three main endpoints:

1. `GET /v1/streams/{stream}/public`: Get public stream information.
2. `GET /v1/stations/{station}/tracks`: Get a list of tracks for a station.
3. `GET /v1/stations/{station}/status`: Get the status of a station.

### Step 2: Authentication

Before making requests, you need an API key to authenticate. Follow these steps to authenticate your requests:

1. Obtain an API key through [contacting us](https://app.gitbook.com/o/diaRKGs5p09EPLiNod7d/s/TNYZSJCOGSx4jEGDBWSW/~/changes/17/api/api-keys#obtaining-an-api-key)
2. Use the Bearer token method for authentication.
3. Include the API key in the Authorization header like so: `Authorization: Bearer YOUR_API_KEY`.

Replace `YOUR_API_KEY` with the key you received.

### Step 3: Making Your First Request

To start interacting with the Evenings API, make a simple `GET` request to any of the public endpoints. Here’s how you can make a request to retrieve public stream information:

HTTP

```http
GET https://api.evenings.co/v1/streams/eveningsfm/public
```

Replace `eveningsfm` with the slug of the station you are interested in.

### Step 4: Handling Responses

The Evenings API will return responses in JSON format. Ensure your application can parse JSON and handle the data accordingly.

For instance, when fetching station tracks, your application should be prepared to handle an array of track objects, each with details such as title, location, and duration.

### Step 5: Error Handling

Understand and handle errors correctly:

* If you receive a `4xx` status code, it often indicates an issue with your request (like a bad request or unauthorized access).
* A `5xx` status code indicates a problem on the Evenings API server.

Refer to the HTTP status codes for proper error handling.

### Step 6: Best Practices

* Avoid making unnecessary requests; cache responses where possible.
* Respect the rate limits to prevent being blocked.
* Secure your API key; do not expose it in client-side code.

### Step 7: Getting Support

If you encounter any issues or have questions:

* Contact [**contact@evenings.email**](mailto:contact@evenings.email) for support via email.
* Send a DM to **@EVENINGSFM** on Twitter.

By following these steps, you should be well on your way to successfully integrating with the Evenings API. Happy coding!


---

# 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/getting-started.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.