# Audience / Streams API

Base URL: `{{baseUrl}}`

---

## Authentication

All protected endpoints require a Bearer token passed in the `Authorization` header:

Authorization: Bearer {{token}}

---

## 1. Create Audience (Stream)

**`POST`** `/audience`

Records a stream or audience entry for a track by a specific user.

### Headers

| Key | Value |
|-----|-------|
| Content-Type | `application/json` |

### Request Body

{
    "track_id": "365b278c258a7bdbb7a1b95be41a37b9",
    "user_id": "6a833be7-c434-4fc0-9144-01899eeac486"
}

### Body Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `track_id` | string | Yes | The unique identifier of the track being streamed |
| `user_id` | string (UUID) | Yes | The unique identifier of the user streaming the track |

### Example Request

POST {{baseUrl}}/audience

---

## 2. View Track Audience

**`GET`** `/audience-track/{track_id}`

Retrieves the audience/stream data for a specific track.

### Headers

| Key | Value | Type |
|-----|-------|------|
| Authorization | `Bearer {{token}}` | text |

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `track_id` | string | Yes | The unique identifier of the track |

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `main_user_id` | string (UUID) | No | The ID of the currently authenticated user for personalization |

### Example Request

GET {{baseUrl}}/audience-track/edc658bd0e768ca81f2ddc0438abca79?main_user_id=8bf0c9da-2f28-4628-91ed-8a6c11f6ae31

---

## 3. Top Audience

**`GET`** `/top-audience/{track_id}`

Retrieves the top audience members for a specific track.

### Headers

| Key | Value | Type |
|-----|-------|------|
| Authorization | `Bearer {{token}}` | text |

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `track_id` | string | Yes | The unique identifier of the track |

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `main_user_id` | string (UUID) | No | The ID of the currently authenticated user |

### Example Request

GET {{baseUrl}}/top-audience/edc658bd0e768ca81f2ddc0438abca79?main_user_id={{main_user_id}}

---

## 4. Get Total Audience

**`GET`** `/artist-audience/{artist_id}`

Retrieves the total audience/stream count across all tracks for a specific artist.

### Headers

| Key | Value | Type |
|-----|-------|------|
| Authorization | `Bearer {{token}}` | text |

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `artist_id` | string (UUID) | Yes | The unique identifier of the artist |

### Example Request

GET {{baseUrl}}/artist-audience/f3b8a31b-8af5-431e-8ed5-fa5dae80e868