senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/veza-backend-api/docs/API_DOCUMENTATION.md
senke aef5bcbdb4 [DOC-001] doc: Write API documentation
2025-12-25 02:48:06 +01:00

39 KiB
Raw Blame History

Veza Backend API Documentation

Table of Contents

  1. Overview
  2. Base URL
  3. Authentication
  4. Error Handling
  5. Rate Limiting
  6. Pagination
  7. 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:

{
  "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:

{
  "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:

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "SecurePassword123!",
  "password_confirm": "SecurePassword123!"
}

Response (201 Created):

{
  "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:

{
  "email": "john@example.com",
  "password": "SecurePassword123!",
  "remember_me": false
}

Response (200 OK):

{
  "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:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK):

{
  "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:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK):

{
  "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):

{
  "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):

{
  "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):

{
  "success": true,
  "data": {
    "message": "Email verified successfully"
  }
}

Resend Verification Email

Resend the email verification link.

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

Request Body:

{
  "email": "john@example.com"
}

Response (200 OK):

{
  "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):

{
  "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):

{
  "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:

{
  "username": "johndoe",
  "bio": "Updated bio",
  "first_name": "John",
  "last_name": "Doe",
  "location": "New York, USA",
  "gender": "Male"
}

Response (200 OK):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "title": "Updated Title",
  "artist": "Updated Artist",
  "album": "Updated Album",
  "genre": "Rock",
  "year": 2025,
  "is_public": true
}

Response (200 OK):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "filename": "my-track.mp3",
  "total_chunks": 10,
  "total_size": 52428800
}

Response (200 OK):

{
  "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):

{
  "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:

{
  "upload_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response (201 Created):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "track_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}

Response (200 OK):

{
  "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:

{
  "duration": 120,
  "device": "Chrome Browser"
}

Response (200 OK):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "title": "My New Playlist",
  "description": "A great playlist",
  "is_public": true
}

Response (201 Created):

{
  "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:

{
  "title": "Updated Playlist Title",
  "description": "Updated description",
  "is_public": false
}

Response (200 OK):

{
  "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):

{
  "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:

{
  "track_id": "660e8400-e29b-41d4-a716-446655440001"
}

Response (200 OK):

{
  "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):

{
  "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:

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

Response (200 OK):

{
  "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):

{
  "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:

{
  "user_id": "990e8400-e29b-41d4-a716-446655440004",
  "permission": "write"
}

Response (200 OK):

{
  "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):

{
  "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:

{
  "permission": "admin"
}

Response (200 OK):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "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):

{
  "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:

{
  "title": "Updated Product Title",
  "price": 12.99,
  "status": "active"
}

Response (200 OK):

{
  "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:

{
  "items": [
    {
      "product_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Response (201 Created):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "event_name": "user_interaction",
  "payload": {
    "action": "button_click",
    "page": "home"
  }
}

Response (200 OK):

{
  "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):

{
  "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:

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

Response (201 Created):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "content": "Great track!"
}

Response (201 Created):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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: