2231 lines
39 KiB
Markdown
2231 lines
39 KiB
Markdown
# 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
|
|
|