Skip to content

Latest commit

 

History

History
562 lines (484 loc) · 12.1 KB

DOCS.md

File metadata and controls

562 lines (484 loc) · 12.1 KB

iMediaPORT Universal Music Hub API (IMH-API)

Version: 1.0.0
Type: Multi-tenant, Role-based, Music Distribution & Management API
Audience: Backend, Frontend, Mobile, Integrations, Partners
Auth: API Key + JWT (Tenant-aware)

1. Core Concepts

1.1 Request Context Resolution Order

  1. JWT Claims (authoritative)
  2. Authorization Headers (X-TENANT, X-PLATFORM, versions) – optional overrides/hints
  3. API Key defaults

Headers never override JWT permissions but may be used for logging, routing, analytics, backward compatibility, and partner integrations.

Tenant is a simple string field used across all entities (User, Song/Album, Artist, Upload, etc.) to identify asset and account ownership (e.g. imediaport, singflex, singnify, mstudios, local). No separate Tenant table is required.

1.2 Multi-Tenancy

Every request is executed within a tenant (portal). Tenant is resolved from:

  • x-api-key → mapped to Portal/Admin
  • JWT token → embeds tenant_id, user_id, role, api_class
{
  "tenant_id": "portal_123",
  "user_id": "user_456",
  "role": "artist",
  "api_class": 10
}

2. Authentication & Security

2.1 Headers

  • Authorization: Bearer <JWT_TOKEN>
  • X-API-KEY: <PORTAL_API_KEY>
  • Content-Type: application/json

Optional Context Headers

  • X-TENANT: <string> (e.g. imediaport | singflex | singnify | mstudios | local)
  • X-TENANT-VERSION: <string> (e.g. v1, v1.2, 2026.01)
  • X-PLATFORM: <string> (web | mobile | api | partner)
  • X-PLATFORM-VERSION: <string> (e.g. web@1.0.0, ios@2.3.1, android@5.0)

2.2 API Classes & Limits

Class Role Example Max per page Can see total
5 Member 100 ❌
10 Manager 250 ❌
20 Admin 500 ✅
50 Super Admin Unlimited ✅

3. Roles & Artist Profile Limits

Role Max Artist Profiles Max Guest Artist Profiles
guest 0 0
listener 0 0
free_listener 0 0
trial_listener 0 0
premium_listener 0 0
member 0 0
artist 1 1
duo 2 1
band 10 2
studio 20 5
choir 100 0
label 1000 0
community unlimited unlimited
editor - -
supervisor - -
manager - -
admin - -
sadmin - -
superadmin - -

4. Status & Enums

4.1 Music Submission Status

adding | new | checking | flagged | flag_cover | flag_song | rejected | processing | submitted | approved | deleted

4.2 Upload File Status

null | loading | complete | used | trash | deleted

4.3 Roles

guest| member | artist | duo | band | studio | chior | label | editor| supervisor | manager | admin | sadmin

5. Data Models (Canonical)

5.1 User

{
  "id": "uuid",
  "email": "string",
  "username": "string",
  "provider": "local | google | spotify",
  "provider_id": "string",
  "platform": "web | mobile | api | partner",
  "tenant": "string",
  "firstname": "string",
  "lastname": "string",
  "role": "artist",
  "status": "active",
  "admin_scope": {
    "artists": ["artist_id"],
    "users": ["user_id"]
  }
}

5.2 Profile

{
  "user_id": "uuid",
  "language": "en",
  "address": "string",
  "socials": {
    "instagram": "",
    "twitter": "",
    "tiktok": ""
  }
}

5.3 ArtistProfile

{
  "id": "uuid",
  "userId": "uuid",
  "stageName": "string",
  "genre": "string",
  "country": "string",
  "bio": "string",
  "type": "main | guest | null",
  "platform": "string",
  "socials": { "instagram": "", "twitter": "" },
  "musicProfiles": { "spotify": "", "appleMusic": "" }
}

5.4 Song / Album (Single / Album / Medley)

{
  "id": "uuid",
  "tenant": "string",
  "type": "single | album | medley",
  "title": "Song Title",
  "upc": "string",
  "cover": "global_url",
  "genre": "string",
  "language": "string",
  "artist_id": "uuid",
  "number_of_tracks": 1,
  "status": "checking",
  "review_note": "string"
}

5.5 Track

{
  "id": "uuid",
  "song_id": "uuid",
  "artist_id": "uuid",
  "track_number": 1,
  "isrc": "string",
  "mp3": "global_url",
  "lyrics": "string",
  "explicit": "yes | no | covered",
  "lead_vocal": "string",
  "song_links": {
    "spotify": "",
    "apple": "",
    "youtube": ""
  },
  "song_info": {
    "producer": "",
    "writer": ""
  }
}

6. Songs API

6.1 GET /api/songs

Get all songs (paginated)

Query Params: ?page=1&limit=20&artist=&album=&status=

Advanced Filters:

  • @songs_like artist=wizkid,title=essence
  • @song_id=slug|upc|isrc

Response:

{
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 540
  },
  "data": [
    {
      "id": "uuid",
      "title": "Song",
      "album": "Album",
      "upc": "",
      "cover": "url",
      "tracks": []
    }
  ]
}

6.2 POST /api/songs

Create Song (Single / Album / Medley)

{
  "type": "single",
  "title": "My Song",
  "artist_id": "uuid",
  "tracks": [
    {
      "isrc": "",
      "mp3": "upload_id",
      "track_number": 1
    }
  ]
}

6.3 PATCH /api/songs/{id}

Partial JSON Update (field-level)

{
  "status": "submitted",
  "review_note": "Ready for DSP"
}

6.4 DELETE /api/songs/{id}

Soft delete → status = deleted

7. Upload System

7.1 Upload Log Model

{
  "id": "uuid",
  "user_id": "uuid",
  "filename": "song.mp3",
  "path": "/uploads",
  "status": "complete",
  "added_at": "timestamp",
  "last_action": "timestamp"
}

Cron Job Rules: trash or complete > 24h → deleted

8. Notifications & Alerts

{
  "id": "uuid",
  "user_id": "uuid",
  "type": "song_flagged",
  "message": "Cover issue detected",
  "read": false
}

9. Admin APIs

Capabilities:

  • Manage any tenant account
  • Approve / reject songs
  • Flag cover / audio
  • View system logs

Manager Restriction:

  • Can approve
  • ❌ Cannot create or modify accounts

10. Provider Authentication (Auth.js)

Supported:

  • Email + Password
  • Google OAuth
  • Spotify OAuth
{
  "provider": "spotify",
  "provider_id": "spotify_user_id"
}

11. Postman Collection Structure

{
  "info": {
    "name": "Universal Music Hub API"
  },
  "item": [
    { "name": "Auth" },
    { "name": "Songs" },
    { "name": "Uploads" },
    { "name": "Admin" }
  ]
}

12. Roadmap Extensions

  • DSP Delivery API
  • Revenue & Royalties API
  • Analytics & Charts
  • Webhooks (approval, release)

This document is designed to be exported as: OpenAPI 3.1 (Swagger), Postman Collection, PDF / Markdown SDK Reference

© Universal Music Hub API

3. Status & Enums

3.1 Music Submission Status

adding | new | checking | flagged | flag_cover | flag_song | rejected | processing | submitted | approved | deleted
3.2 Upload File Status
null | loading | complete | used | trash | deleted
3.3 Roles
member | artist | band | studio | label | editor | manager | admin | sadmin

4. Data Models (Canonical)
4.1 User
{
  "id": "uuid",
  "email": "string",
  "username": "string",
  "provider": "local | google | spotify",
  "provider_id": "string",
  "platform": "web | mobile | api | partner",
  "tenant": "string",
  "firstname": "string",
  "lastname": "string",
  "role": "artist",
  "status": "active",
  "admin_scope": {
    "artists": ["artist_id"],
    "users": ["user_id"]
  }
}
json { “id”: “uuid”, “email”: “string”, “username”: “string”, “provider”: “local | google | spotify”, “provider_id”: “string”, “platform”: “web | mobile | api | partner”, “firstname”: “string”, “lastname”: “string”, “role”: “artist”, “status”: “active”, “admin_scope”: { “artists”: [“artist_id”], “users”: [“user_id”] } }


### 4.2 Profile
```json
{
  "user_id": "uuid",
  "language": "en",
  "address": "string",
  "socials": {
    "instagram": "",
    "twitter": "",
    "tiktok": ""
  }
}
4.3 Artist
{
  "id": "uuid",
  "name": "Artist Name",
  "label": "Label Name",
  "genre": "Afrobeats",
  "language": "en",
  "country": "NG",
  "thumbnail": "url",
  "profilePicture": "url"
}
4.4 Song / Album (Single / Album / Medley)
{
  "id": "uuid",
  "tenant": "string",
  "type": "single | album | medley",
  "title": "Song Title",
  "upc": "string",
  "cover": "global_url",
  "genre": "string",
  "language": "string",
  "artist_id": "uuid",
  "number_of_tracks": 1,
  "status": "checking",
  "review_note": "string"
}
json { “id”: “uuid”, “type”: “single | album | medley”, “title”: “Song Title”, “upc”: “string”, “cover”: “global_url”, “genre”: “string”, “language”: “string”, “artist_id”: “uuid”, “number_of_tracks”: 1, “status”: “checking”, “review_note”: “string” }

### 4.5 Track
```json
{
  "id": "uuid",
  "song_id": "uuid",
  "artist_id": "uuid",
  "track_number": 1,
  "isrc": "string",
  "mp3": "global_url",
  "lyrics": "string",
  "explicit": "yes | no | covered",
  "lead_vocal": "string",
  "song_links": {
    "spotify": "",
    "apple": "",
    "youtube": ""
  },
  "song_info": {
    "producer": "",
    "writer": ""
  }
}

5. Songs API
5.1 GET /api/songs
Description: Get all songs (paginated)
Query Params
?page=1&limit=20&artist=&album=&status=
Advanced Filters
@songs_like artist=wizkid,title=essence
@song_id=slug|upc|isrc
Response
{
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 540
  },
  "data": [
    {
      "id": "uuid",
      "title": "Song",
      "album": "Album",
      "upc": "",
      "cover": "url",
      "tracks": []
    }
  ]
}

5.2 POST /api/songs
Create Song (Single / Album / Medley)
{
  "type": "single",
  "title": "My Song",
  "artist_id": "uuid",
  "tracks": [
    {
      "isrc": "",
      "mp3": "upload_id",
      "track_number": 1
    }
  ]
}

5.3 PATCH /api/songs/{id}
Partial JSON Update (field-level)
{
  "status": "submitted",
  "review_note": "Ready for DSP"
}

5.4 DELETE /api/songs/{id}
Soft delete → status = deleted

6. Upload System
6.1 Upload Log Model
{
  "id": "uuid",
  "user_id": "uuid",
  "filename": "song.mp3",
  "path": "/uploads",
  "status": "complete",
  "added_at": "timestamp",
  "last_action": "timestamp"
}
Cron Job Rules - trash or complete > 24h → deleted

7. Notifications & Alerts
{
  "id": "uuid",
  "user_id": "uuid",
  "type": "song_flagged",
  "message": "Cover issue detected",
  "read": false
}

8. Admin APIs
Capabilities
Manage any tenant account
Approve / reject songs
Flag cover / audio
View system logs
Manager Restriction
Can approve
❌ Cannot create or modify accounts

9. Provider Authentication (Auth.js)
Supported: - Email + Password - Google OAuth - Spotify OAuth
{
  "provider": "spotify",
  "provider_id": "spotify_user_id"
}

10. Postman Collection Structure
{
  "info": {
    "name": "Universal Music Hub API"
  },
  "item": [
    { "name": "Auth" },
    { "name": "Songs" },
    { "name": "Uploads" },
    { "name": "Admin" }
  ]
}

11. Roadmap Extensions
DSP Delivery API
Revenue & Royalties API
Analytics & Charts
Webhooks (approval, release)

This document is designed to be exported as: - OpenAPI 3.1 (Swagger) - Postman Collection - PDF / Markdown SDK Reference

© Universal Music Hub API