# Veza Backend API Documentation

## Table of Contents

1. [Overview](#overview)
2. [Base URL](#base-url)
3. [Authentication](#authentication)
4. [Error Handling](#error-handling)
5. [Rate Limiting](#rate-limiting)
6. [Pagination](#pagination)
7. [Endpoints](#endpoints)
   - [Authentication](#authentication-endpoints)
   - [Users](#user-endpoints)
   - [Tracks](#track-endpoints)
   - [Playlists](#playlist-endpoints)
   - [Marketplace](#marketplace-endpoints)
   - [Analytics](#analytics-endpoints)
   - [Webhooks](#webhook-endpoints)
   - [Chat](#chat-endpoints)
   - [Search](#search-endpoints)
   - [Comments](#comment-endpoints)
   - [Roles](#role-endpoints)
   - [Notifications](#notification-endpoints)
   - [Sessions](#session-endpoints)
   - [Uploads](#upload-endpoints)
   - [Audit](#audit-endpoints)
   - [Admin](#admin-endpoints)

## Overview

The Veza Backend API is a RESTful API that provides endpoints for managing audio tracks, playlists, users, marketplace, analytics, and more. The API uses JSON for request and response payloads and follows REST conventions.

**API Version:** v1  
**Base Path:** `/api/v1`  
**Content-Type:** `application/json`

## Base URL

- **Production:** `https://api.veza.app`
- **Staging:** `https://staging-api.veza.app`
- **Development:** `http://localhost:8080`

## Authentication

Most endpoints require authentication using JWT (JSON Web Tokens). Include the access token in the `Authorization` header:

```
Authorization: Bearer <access_token>
```

### Getting an Access Token

1. Register a new user or login
2. Receive `access_token` in the response body
3. Receive `refresh_token` in an httpOnly cookie (automatically sent by browser)
4. Use `access_token` for authenticated requests
5. Use the refresh token cookie to get a new `access_token` when it expires

### Token Expiration

- **Access Token:** Valid for 24 hours
- **Refresh Token:** Valid for 30 days (or 90 days if "remember me" is selected)

### Authentication Cookies

#### Refresh Token Cookie

After successful login or token refresh, a `refresh_token` cookie is set with the following properties:

- **Name:** `refresh_token`
- **HttpOnly:** `true` (not accessible via JavaScript - prevents XSS attacks)
- **Secure:** `true` in production, `false` in development (HTTPS only in production)
- **SameSite:** `strict` in production, `lax` in development (prevents CSRF attacks)
- **Path:** `/`
- **Max-Age:** 30 days (or 90 days if "remember me" is selected)

**Important:** The refresh token is NOT returned in the JSON response body for security reasons. It is only available as an httpOnly cookie that is automatically sent by the browser with each request.

#### Using Refresh Token

To refresh your access token, make a POST request to `/auth/refresh`:

```bash
# The refresh token cookie is automatically sent by the browser
curl -X POST http://localhost:8080/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  --cookie "refresh_token=<token>" \
  -b cookies.txt -c cookies.txt
```

The new access token will be returned in the response body, and a new refresh token cookie will be set automatically.

#### Cookie Configuration

The cookie security settings can be configured via environment variables:

- `COOKIE_SECURE`: `true` in production (HTTPS only), `false` in development
- `COOKIE_SAME_SITE`: `strict` (production), `lax` (development)
- `COOKIE_DOMAIN`: Domain for the cookie (empty for current domain)
- `COOKIE_HTTP_ONLY`: Always `true` for refresh tokens
- `COOKIE_PATH`: Cookie path (default: `/`)

**Note:** In development, cookies work with `http://localhost` when `COOKIE_SECURE=false` and `COOKIE_SAME_SITE=lax`.

## Error Handling

All errors follow a consistent format:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": []
  }
}
```

### HTTP Status Codes

- `200 OK` - Request successful
- `201 Created` - Resource created successfully
- `400 Bad Request` - Invalid request parameters
- `401 Unauthorized` - Missing or invalid authentication
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Resource not found
- `409 Conflict` - Resource conflict (e.g., duplicate)
- `422 Unprocessable Entity` - Validation error
- `429 Too Many Requests` - Rate limit exceeded
- `500 Internal Server Error` - Server error

## Rate Limiting

Rate limiting is applied to prevent abuse. Limits vary by endpoint:

- **Global:** 100 requests per minute per IP
- **Login/Register:** 5 requests per minute per IP
- **Email Verification:** 3 requests per hour per email
- **Upload:** 10 uploads per hour per user

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

## Pagination

List endpoints support pagination using query parameters:

- `page` - Page number (default: 1)
- `limit` - Items per page (default: 20, max: 100)

Response includes pagination metadata:

```json
{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}
```

## Endpoints

### Authentication Endpoints

#### Register User

Create a new user account.

**Endpoint:** `POST /api/v1/auth/register`

**Request Body:**
```json
{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "SecurePassword123!",
  "password_confirm": "SecurePassword123!"
}
```

**Response (201 Created):**
```json
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "johndoe",
      "email": "john@example.com"
    },
    "token": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expires_in": 86400
    }
  }
}
```

#### Login

Authenticate and receive tokens.

**Endpoint:** `POST /api/v1/auth/login`

**Request Body:**
```json
{
  "email": "john@example.com",
  "password": "SecurePassword123!",
  "remember_me": false
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "johndoe",
      "email": "john@example.com"
    },
    "token": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expires_in": 86400
    },
    "requires_2fa": false
  }
}
```

#### Refresh Token

Get a new access token using refresh token.

**Endpoint:** `POST /api/v1/auth/refresh`

**Request Body:**
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400
  }
}
```

#### Logout

Revoke refresh token and current session.

**Endpoint:** `POST /api/v1/auth/logout`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Logged out successfully"
  }
}
```

#### Get Current User

Get profile information of the currently logged-in user.

**Endpoint:** `GET /api/v1/auth/me`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "email": "john@example.com",
    "role": "user"
  }
}
```

#### Check Username Availability

Check if a username is available.

**Endpoint:** `GET /api/v1/auth/check-username?username=johndoe`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "username": "johndoe",
    "available": true
  }
}
```

#### Verify Email

Verify user email address using a token.

**Endpoint:** `POST /api/v1/auth/verify-email?token=verification_token_here`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Email verified successfully"
  }
}
```

#### Resend Verification Email

Resend the email verification link.

**Endpoint:** `POST /api/v1/auth/resend-verification`

**Request Body:**
```json
{
  "email": "john@example.com"
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Verification email sent"
  }
}
```

### User Endpoints

#### Get User Profile

Get public profile information for a user.

**Endpoint:** `GET /api/v1/users/{id}`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "profile": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "johndoe",
      "email": "john@example.com",
      "bio": "Music producer",
      "avatar": "https://cdn.veza.app/avatars/user123.jpg",
      "location": "Paris, France",
      "created_at": "2025-01-01T00:00:00Z"
    }
  }
}
```

#### Get User Profile by Username

Get public profile information by username.

**Endpoint:** `GET /api/v1/users/by-username/{username}`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "profile": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "johndoe",
      "bio": "Music producer",
      "avatar": "https://cdn.veza.app/avatars/user123.jpg"
    }
  }
}
```

#### Update Profile

Update user profile details.

**Endpoint:** `PUT /api/v1/users/{id}`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "username": "johndoe",
  "bio": "Updated bio",
  "first_name": "John",
  "last_name": "Doe",
  "location": "New York, USA",
  "gender": "Male"
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "profile": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "johndoe",
      "bio": "Updated bio",
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}
```

#### Get Profile Completion

Get profile completion percentage and missing fields.

**Endpoint:** `GET /api/v1/users/{id}/completion`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "completion_percentage": 75,
    "missing_fields": ["bio", "avatar"]
  }
}
```

### Track Endpoints

#### List Tracks

Get a paginated list of tracks with filters.

**Endpoint:** `GET /api/v1/tracks`

**Query Parameters:**
- `page` (optional) - Page number (default: 1)
- `limit` (optional) - Items per page (default: 20, max: 100)
- `user_id` (optional) - Filter by user ID
- `genre` (optional) - Filter by genre
- `format` (optional) - Filter by format (mp3, flac, wav)
- `sort_by` (optional) - Sort field (default: created_at)
- `sort_order` (optional) - Sort order: asc/desc (default: desc)

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "tracks": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "My Track",
        "artist": "John Doe",
        "duration": 180,
        "format": "mp3",
        "genre": "Electronic",
        "is_public": true,
        "created_at": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}
```

#### Search Tracks

Search tracks with advanced filters.

**Endpoint:** `GET /api/v1/tracks/search`

**Query Parameters:**
- `q` (optional) - Search query
- `genre` (optional) - Filter by genre
- `format` (optional) - Filter by format
- `min_duration` (optional) - Minimum duration in seconds
- `max_duration` (optional) - Maximum duration in seconds
- `start_date` (optional) - Start date (RFC3339)
- `end_date` (optional) - End date (RFC3339)
- `sort_by` (optional) - Sort field (title, popularity, created_at)
- `sort_order` (optional) - Sort order (asc/desc)
- `page` (optional) - Page number
- `limit` (optional) - Items per page

**Response (200 OK):**
```json
{
  "tracks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My Track",
      "artist": "John Doe",
      "duration": 180
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "total_pages": 3
  }
}
```

#### Get Track

Get detailed information about a track.

**Endpoint:** `GET /api/v1/tracks/{id}`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "track": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My Track",
      "artist": "John Doe",
      "album": "My Album",
      "duration": 180,
      "format": "mp3",
      "file_size": 5242880,
      "genre": "Electronic",
      "year": 2025,
      "is_public": true,
      "like_count": 42,
      "play_count": 150,
      "created_at": "2025-01-01T00:00:00Z"
    }
  }
}
```

#### Upload Track

Upload a new track (audio file).

**Endpoint:** `POST /api/v1/tracks`

**Headers:** 
- `Authorization: Bearer <token>`
- `Content-Type: multipart/form-data`

**Form Data:**
- `file` (required) - Audio file (MP3, WAV, FLAC, OGG)

**Response (201 Created):**
```json
{
  "success": true,
  "data": {
    "track": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My Track",
      "status": "processing",
      "created_at": "2025-01-01T00:00:00Z"
    }
  }
}
```

#### Update Track

Update track metadata.

**Endpoint:** `PUT /api/v1/tracks/{id}`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "title": "Updated Title",
  "artist": "Updated Artist",
  "album": "Updated Album",
  "genre": "Rock",
  "year": 2025,
  "is_public": true
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "track": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Updated Title",
      "artist": "Updated Artist"
    }
  }
}
```

#### Delete Track

Permanently delete a track.

**Endpoint:** `DELETE /api/v1/tracks/{id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Track deleted successfully"
  }
}
```

#### Get Track Stats

Get statistics for a track.

**Endpoint:** `GET /api/v1/tracks/{id}/stats`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "stats": {
      "total_plays": 150,
      "unique_listeners": 45,
      "average_duration": 165.5,
      "completion_rate": 78.5
    }
  }
}
```

#### Download Track

Download a track file.

**Endpoint:** `GET /api/v1/tracks/{id}/download`

**Response (200 OK):**
- Binary file download with appropriate `Content-Type` header

#### Like Track

Like a track.

**Endpoint:** `POST /api/v1/tracks/{id}/like`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Track liked"
  }
}
```

#### Unlike Track

Remove like from a track.

**Endpoint:** `DELETE /api/v1/tracks/{id}/like`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Track unliked"
  }
}
```

#### Get Track Likes

Get list of users who liked a track.

**Endpoint:** `GET /api/v1/tracks/{id}/likes`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "likes": [
      {
        "user_id": "550e8400-e29b-41d4-a716-446655440000",
        "username": "johndoe",
        "liked_at": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 42
  }
}
```

#### Initiate Chunked Upload

Start a new chunked upload session.

**Endpoint:** `POST /api/v1/tracks/initiate`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "filename": "my-track.mp3",
  "total_chunks": 10,
  "total_size": 52428800
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "upload_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Upload session initiated"
  }
}
```

#### Upload Chunk

Upload a single chunk of a file.

**Endpoint:** `POST /api/v1/tracks/chunk`

**Headers:** 
- `Authorization: Bearer <token>`
- `Content-Type: multipart/form-data`

**Form Data:**
- `chunk` (required) - Chunk file data
- `upload_id` (required) - Upload session ID
- `chunk_number` (required) - Chunk number (1-based)
- `total_chunks` (required) - Total number of chunks
- `total_size` (required) - Total file size in bytes
- `filename` (required) - Original filename

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "upload_id": "550e8400-e29b-41d4-a716-446655440000",
    "received_chunks": 5,
    "progress": 50.0,
    "message": "Chunk uploaded successfully"
  }
}
```

#### Complete Chunked Upload

Finish upload session and assemble file.

**Endpoint:** `POST /api/v1/tracks/complete`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "upload_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Response (201 Created):**
```json
{
  "success": true,
  "data": {
    "track": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "my-track",
      "status": "processing"
    },
    "md5": "d41d8cd98f00b204e9800998ecf8427e",
    "message": "Upload completed"
  }
}
```

#### Get Upload Status

Get the processing status of an uploaded track.

**Endpoint:** `GET /api/v1/tracks/{id}/status`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "status": "processing",
    "progress": 75
  }
}
```

#### Get Upload Quota

Get remaining upload quota for the user.

**Endpoint:** `GET /api/v1/tracks/quota/{id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "quota": {
      "used": 524288000,
      "limit": 1073741824,
      "remaining": 549453824,
      "percentage_used": 48.8
    }
  }
}
```

#### Resume Upload

Get state of an interrupted upload.

**Endpoint:** `GET /api/v1/tracks/resume/{uploadId}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "upload_id": "550e8400-e29b-41d4-a716-446655440000",
    "chunks_received": 7,
    "total_chunks": 10
  }
}
```

#### Batch Delete Tracks

Delete multiple tracks at once.

**Endpoint:** `POST /api/v1/tracks/batch/delete`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "track_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "deleted": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660e8400-e29b-41d4-a716-446655440001"
    ],
    "failed": {}
  }
}
```

#### Record Play

Record a track play event.

**Endpoint:** `POST /api/v1/tracks/{id}/play`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "duration": 120,
  "device": "Chrome Browser"
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Play event recorded",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

### Playlist Endpoints

#### List Playlists

Get a paginated list of playlists.

**Endpoint:** `GET /api/v1/playlists`

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:**
- `page` (optional) - Page number (default: 1)
- `limit` (optional) - Items per page (default: 20)
- `user_id` (optional) - Filter by user ID

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "playlists": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "My Playlist",
        "description": "A great playlist",
        "is_public": true,
        "track_count": 10,
        "follower_count": 5,
        "created_at": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 50,
      "total_pages": 3
    }
  }
}
```

#### Search Playlists

Search playlists with filters.

**Endpoint:** `GET /api/v1/playlists/search`

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:**
- `q` (optional) - Search query
- `user_id` (optional) - Filter by user ID
- `is_public` (optional) - Filter by public status (true/false)
- `page` (optional) - Page number
- `limit` (optional) - Items per page

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "playlists": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "My Playlist",
        "is_public": true
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 20
  }
}
```

#### Get Playlist

Get detailed information about a playlist.

**Endpoint:** `GET /api/v1/playlists/{id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "playlist": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My Playlist",
      "description": "A great playlist",
      "is_public": true,
      "track_count": 10,
      "tracks": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "title": "Track 1",
          "position": 1
        }
      ],
      "created_at": "2025-01-01T00:00:00Z"
    }
  }
}
```

#### Create Playlist

Create a new playlist.

**Endpoint:** `POST /api/v1/playlists`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "title": "My New Playlist",
  "description": "A great playlist",
  "is_public": true
}
```

**Response (201 Created):**
```json
{
  "success": true,
  "data": {
    "playlist": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My New Playlist",
      "description": "A great playlist",
      "is_public": true,
      "track_count": 0,
      "created_at": "2025-01-01T00:00:00Z"
    }
  }
}
```

#### Update Playlist

Update playlist metadata.

**Endpoint:** `PUT /api/v1/playlists/{id}`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "title": "Updated Playlist Title",
  "description": "Updated description",
  "is_public": false
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "playlist": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Updated Playlist Title",
      "description": "Updated description"
    }
  }
}
```

#### Delete Playlist

Permanently delete a playlist.

**Endpoint:** `DELETE /api/v1/playlists/{id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Playlist deleted successfully"
  }
}
```

#### Add Track to Playlist

Add a track to the playlist.

**Endpoint:** `POST /api/v1/playlists/{id}/tracks`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "track_id": "660e8400-e29b-41d4-a716-446655440001"
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Track added to playlist"
  }
}
```

#### Remove Track from Playlist

Remove a track from the playlist.

**Endpoint:** `DELETE /api/v1/playlists/{id}/tracks/{track_id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Track removed from playlist"
  }
}
```

#### Reorder Tracks

Reorder tracks in the playlist.

**Endpoint:** `PUT /api/v1/playlists/{id}/tracks/reorder`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "track_ids": [
    "660e8400-e29b-41d4-a716-446655440001",
    "770e8400-e29b-41d4-a716-446655440002",
    "880e8400-e29b-41d4-a716-446655440003"
  ]
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Tracks reordered successfully"
  }
}
```

#### Get Playlist Recommendations

Get playlist recommendations.

**Endpoint:** `GET /api/v1/playlists/recommendations`

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:**
- `limit` (optional) - Number of recommendations (default: 10)

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "playlists": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Recommended Playlist",
        "is_public": true
      }
    ]
  }
}
```

#### Add Collaborator

Add a collaborator to a playlist.

**Endpoint:** `POST /api/v1/playlists/{id}/collaborators`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "user_id": "990e8400-e29b-41d4-a716-446655440004",
  "permission": "write"
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Collaborator added successfully"
  }
}
```

#### Get Collaborators

Get list of collaborators for a playlist.

**Endpoint:** `GET /api/v1/playlists/{id}/collaborators`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "collaborators": [
      {
        "id": "990e8400-e29b-41d4-a716-446655440004",
        "username": "collaborator",
        "permission": "write",
        "added_at": "2025-01-01T00:00:00Z"
      }
    ]
  }
}
```

#### Update Collaborator Permission

Update collaborator permission.

**Endpoint:** `PUT /api/v1/playlists/{id}/collaborators/{userId}`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "permission": "admin"
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Collaborator permission updated"
  }
}
```

#### Remove Collaborator

Remove a collaborator from a playlist.

**Endpoint:** `DELETE /api/v1/playlists/{id}/collaborators/{userId}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Collaborator removed successfully"
  }
}
```

#### Create Share Link

Create a share link for a playlist.

**Endpoint:** `POST /api/v1/playlists/{id}/share`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "share_token": "abc123def456",
    "share_url": "https://veza.app/playlists/shared/abc123def456",
    "expires_at": "2025-12-31T23:59:59Z"
  }
}
```

### Marketplace Endpoints

#### List Products

List marketplace products with filters.

**Endpoint:** `GET /api/v1/marketplace/products`

**Query Parameters:**
- `status` (optional) - Product status (draft, active, archived)
- `seller_id` (optional) - Filter by seller ID

**Response (200 OK):**
```json
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My Product",
      "description": "A great track for sale",
      "price": 9.99,
      "currency": "EUR",
      "status": "active",
      "product_type": "track",
      "seller_id": "660e8400-e29b-41d4-a716-446655440001",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}
```

#### Create Product

Create a product (Track, Pack, Service) for sale.

**Endpoint:** `POST /api/v1/marketplace/products`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "title": "My Product",
  "description": "A great track for sale",
  "price": 9.99,
  "product_type": "track",
  "track_id": "770e8400-e29b-41d4-a716-446655440002",
  "license_type": "standard"
}
```

**Response (201 Created):**
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "My Product",
    "price": 9.99,
    "status": "active",
    "created_at": "2025-01-01T00:00:00Z"
  }
}
```

#### Update Product

Update product details (only seller can update).

**Endpoint:** `PUT /api/v1/marketplace/products/{id}`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "title": "Updated Product Title",
  "price": 12.99,
  "status": "active"
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Updated Product Title",
    "price": 12.99
  }
}
```

#### Create Order

Purchase products.

**Endpoint:** `POST /api/v1/marketplace/orders`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "items": [
    {
      "product_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}
```

**Response (201 Created):**
```json
{
  "success": true,
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "buyer_id": "990e8400-e29b-41d4-a716-446655440004",
    "total_amount": 9.99,
    "currency": "EUR",
    "status": "completed",
    "items": [
      {
        "product_id": "550e8400-e29b-41d4-a716-446655440000",
        "price": 9.99
      }
    ],
    "created_at": "2025-01-01T00:00:00Z"
  }
}
```

#### List Orders

Get all orders for the authenticated user.

**Endpoint:** `GET /api/v1/marketplace/orders`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "total_amount": 9.99,
      "status": "completed",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}
```

#### Get Order

Get details of a specific order.

**Endpoint:** `GET /api/v1/marketplace/orders/{id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "buyer_id": "990e8400-e29b-41d4-a716-446655440004",
    "total_amount": 9.99,
    "currency": "EUR",
    "status": "completed",
    "items": [
      {
        "product_id": "550e8400-e29b-41d4-a716-446655440000",
        "price": 9.99
      }
    ],
    "created_at": "2025-01-01T00:00:00Z"
  }
}
```

#### Get Download URL

Get a secure download URL for a purchased product.

**Endpoint:** `GET /api/v1/marketplace/download/{product_id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "url": "https://storage.example.com/download/track123.mp3?token=abc123"
  }
}
```

### Analytics Endpoints

#### Record Analytics Event

Record a custom analytics event.

**Endpoint:** `POST /api/v1/analytics/events`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "event_name": "user_interaction",
  "payload": {
    "action": "button_click",
    "page": "home"
  }
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "event recorded",
    "event_name": "user_interaction"
  }
}
```

#### Get Track Analytics Dashboard

Get comprehensive analytics dashboard for a track.

**Endpoint:** `GET /api/v1/analytics/tracks/{id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "dashboard": {
      "track_id": "550e8400-e29b-41d4-a716-446655440000",
      "stats": {
        "total_plays": 150,
        "unique_listeners": 45,
        "average_duration": 165.5,
        "completion_rate": 78.5
      },
      "plays_over_time": [
        {
          "date": "2025-01-01T00:00:00Z",
          "count": 10
        }
      ],
      "period": {
        "start_date": "2024-12-01T00:00:00Z",
        "end_date": "2025-01-01T00:00:00Z",
        "days": 30
      }
    }
  }
}
```

### Webhook Endpoints

#### Register Webhook

Register a new webhook.

**Endpoint:** `POST /api/v1/webhooks`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "url": "https://example.com/webhook",
  "events": ["track.uploaded", "playlist.created"],
  "secret": "webhook_secret_key"
}
```

**Response (201 Created):**
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/webhook",
    "api_key": "wh_abc123def456",
    "created_at": "2025-01-01T00:00:00Z"
  }
}
```

#### List Webhooks

Get all webhooks for the authenticated user.

**Endpoint:** `GET /api/v1/webhooks`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://example.com/webhook",
      "events": ["track.uploaded"],
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}
```

#### Delete Webhook

Delete a webhook.

**Endpoint:** `DELETE /api/v1/webhooks/{id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Webhook deleted successfully"
  }
}
```

#### Test Webhook

Test a webhook by sending a test event.

**Endpoint:** `POST /api/v1/webhooks/{id}/test`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Test event sent",
    "status": "delivered"
  }
}
```

#### Get Webhook Stats

Get statistics for webhooks.

**Endpoint:** `GET /api/v1/webhooks/stats`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "total_webhooks": 5,
    "total_events": 150,
    "successful_deliveries": 145,
    "failed_deliveries": 5
  }
}
```

#### Regenerate API Key

Regenerate API key for a webhook.

**Endpoint:** `POST /api/v1/webhooks/{id}/regenerate-key`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "api_key": "wh_new_abc123def456"
  }
}
```

### Chat Endpoints

#### Get Chat Token

Generate a short-lived token for chat authentication.

**Endpoint:** `GET /api/v1/chat/token`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "token": "chat_token_abc123"
  }
}
```

#### Get Chat Stats

Get chat statistics.

**Endpoint:** `GET /api/v1/chat/stats`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "total_rooms": 10,
    "total_messages": 500,
    "active_users": 25
  }
}
```

### Search Endpoints

#### General Search

Search across tracks, playlists, and users.

**Endpoint:** `GET /api/v1/search`

**Query Parameters:**
- `q` (required) - Search query
- `type` (optional) - Filter by type (tracks, playlists, users)
- `page` (optional) - Page number
- `limit` (optional) - Items per page

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "tracks": [...],
    "playlists": [...],
    "users": [...],
    "total": 150
  }
}
```

### Comment Endpoints

#### Get Comments

Get comments for a track.

**Endpoint:** `GET /api/v1/tracks/{id}/comments`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "comments": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": "660e8400-e29b-41d4-a716-446655440001",
        "username": "johndoe",
        "content": "Great track!",
        "created_at": "2025-01-01T00:00:00Z"
      }
    ]
  }
}
```

#### Create Comment

Create a comment on a track.

**Endpoint:** `POST /api/v1/tracks/{id}/comments`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "content": "Great track!"
}
```

**Response (201 Created):**
```json
{
  "success": true,
  "data": {
    "comment": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "Great track!",
      "created_at": "2025-01-01T00:00:00Z"
    }
  }
}
```

#### Delete Comment

Delete a comment.

**Endpoint:** `DELETE /api/v1/comments/{id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Comment deleted successfully"
  }
}
```

### Role Endpoints

#### Get Roles

Get all available roles.

**Endpoint:** `GET /api/v1/roles`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "roles": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "admin",
        "permissions": ["all"]
      }
    ]
  }
}
```

#### Get Role

Get details of a specific role.

**Endpoint:** `GET /api/v1/roles/{id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "role": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "admin",
      "permissions": ["all"]
    }
  }
}
```

### Notification Endpoints

#### Get Notifications

Get notifications for the authenticated user.

**Endpoint:** `GET /api/v1/notifications`

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:**
- `page` (optional) - Page number
- `limit` (optional) - Items per page
- `unread_only` (optional) - Filter unread only (true/false)

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "track_liked",
        "message": "Your track was liked",
        "read": false,
        "created_at": "2025-01-01T00:00:00Z"
      }
    ]
  }
}
```

#### Mark Notification as Read

Mark a notification as read.

**Endpoint:** `POST /api/v1/notifications/{id}/read`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Notification marked as read"
  }
}
```

#### Mark All Notifications as Read

Mark all notifications as read.

**Endpoint:** `POST /api/v1/notifications/read-all`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "All notifications marked as read"
  }
}
```

### Session Endpoints

#### Get Sessions

Get all active sessions for the authenticated user.

**Endpoint:** `GET /api/v1/sessions`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "ip_address": "192.168.1.1",
        "user_agent": "Mozilla/5.0...",
        "created_at": "2025-01-01T00:00:00Z",
        "last_activity": "2025-01-01T12:00:00Z"
      }
    ]
  }
}
```

#### Logout Session

Logout from a specific session.

**Endpoint:** `POST /api/v1/sessions/logout`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Logged out successfully"
  }
}
```

#### Logout All Sessions

Logout from all sessions.

**Endpoint:** `POST /api/v1/sessions/logout-all`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Logged out from all sessions"
  }
}
```

#### Revoke Session

Revoke a specific session.

**Endpoint:** `DELETE /api/v1/sessions/{session_id}`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "message": "Session revoked successfully"
  }
}
```

#### Get Session Stats

Get session statistics.

**Endpoint:** `GET /api/v1/sessions/stats`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "total_sessions": 5,
    "active_sessions": 3
  }
}
```

### Upload Endpoints

#### Upload File

Upload a file.

**Endpoint:** `POST /api/v1/uploads`

**Headers:** 
- `Authorization: Bearer <token>`
- `Content-Type: multipart/form-data`

**Form Data:**
- `file` (required) - File to upload

**Response (201 Created):**
```json
{
  "success": true,
  "data": {
    "upload_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing"
  }
}
```

#### Get Upload Status

Get upload status.

**Endpoint:** `GET /api/v1/uploads/{id}/status`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "status": "completed",
    "progress": 100
  }
}
```

### Audit Endpoints

#### Search Audit Logs

Search audit logs.

**Endpoint:** `GET /api/v1/audit/logs`

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:**
- `user_id` (optional) - Filter by user ID
- `action` (optional) - Filter by action
- `start_date` (optional) - Start date (RFC3339)
- `end_date` (optional) - End date (RFC3339)
- `page` (optional) - Page number
- `limit` (optional) - Items per page

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": "660e8400-e29b-41d4-a716-446655440001",
        "action": "track.uploaded",
        "ip_address": "192.168.1.1",
        "created_at": "2025-01-01T00:00:00Z"
      }
    ]
  }
}
```

#### Get Audit Stats

Get audit statistics.

**Endpoint:** `GET /api/v1/audit/stats`

**Headers:** `Authorization: Bearer <token>`

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "total_logs": 1000,
    "actions_count": {
      "track.uploaded": 500,
      "playlist.created": 300
    }
  }
}
```

### Admin Endpoints

All admin endpoints require admin role.

#### Get Audit Logs (Admin)

**Endpoint:** `GET /api/v1/admin/audit/logs`

**Headers:** `Authorization: Bearer <token>`

#### Get Audit Stats (Admin)

**Endpoint:** `GET /api/v1/admin/audit/stats`

**Headers:** `Authorization: Bearer <token>`

#### Detect Suspicious Activity (Admin)

**Endpoint:** `GET /api/v1/admin/audit/suspicious`

**Headers:** `Authorization: Bearer <token>`

## Additional Resources

- **Swagger UI:** `/swagger/index.html` - Interactive API documentation
- **ReDoc:** `/redoc` - Alternative API documentation
- **OpenAPI Spec:** `/swagger/doc.json` - OpenAPI 3.0 specification

## Support

For API support, please contact:
- **Email:** support@veza.app
- **Documentation:** https://docs.veza.app
- **Issues:** https://github.com/veza/veza-backend-api/issues

