# 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` and `refresh_token` in the response
3. Use `access_token` for authenticated requests
4. Use `refresh_token` to get a new `access_token` when it expires

### Token Expiration

- **Access Token:** Valid for 24 hours
- **Refresh Token:** Valid for 30 days

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