{
  "openapi": "3.1.0",
  "info": {
    "title": "BE | Music Agentic Gateway API",
    "version": "2.0.0",
    "description": "Public catalog queries, beat licensing marketplace, and referral attribution endpoints for BE | Music.",
    "contact": {
      "name": "BLXCKHIPPY Entertainment",
      "url": "https://music.blxckhippyentertainment.com",
      "email": "admin@music.blxckhippyentertainment.com"
    }
  },
  "servers": [
    {
      "url": "https://music.blxckhippyentertainment.com",
      "description": "Production Edge Server"
    }
  ],
  "paths": {
    "/api/db.php": {
      "post": {
        "summary": "Catalog & Streaming Queries",
        "description": "Query tracks, releases, artists, and execute global catalog search.",
        "operationId": "queryCatalog",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": ["get_home_data", "get_albums", "get_album_detail", "get_artists", "get_artist_profile", "search"]
                  },
                  "query": { "type": "string", "description": "Search keyword for search action" },
                  "album_id": { "type": "string", "description": "Release identifier for get_album_detail" },
                  "artist_id": { "type": "string", "description": "Artist identifier for get_artist_profile" }
                },
                "required": ["action"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful catalog response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/producer.php": {
      "post": {
        "summary": "Beat Store & Licensing Gateway",
        "description": "Search beats by genre/BPM, fetch license pricing, and audition previews.",
        "operationId": "queryBeats",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": ["get_beats", "get_beat_detail", "get_producers"]
                  },
                  "genre": { "type": "string", "description": "Filter by genre e.g. Trap, R&B, Drill" },
                  "sort": { "type": "string", "enum": ["latest", "bpm", "price_asc", "price_desc"] },
                  "min_bpm": { "type": "integer" },
                  "max_bpm": { "type": "integer" },
                  "beat_id": { "type": "string" }
                },
                "required": ["action"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful beat store response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": { "type": "array" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/referrals.php": {
      "post": {
        "summary": "VIP Referral & Invitation Resolver",
        "description": "Resolve public inviter details from a referral code or dispatch email invites.",
        "operationId": "resolveReferral",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": ["resolve_code", "get_my_referrals", "send_email_invite"]
                  },
                  "referral_code": { "type": "string", "description": "Public referral code e.g. BE-XXXX" },
                  "referrer_user_id": { "type": "string" },
                  "to_email": { "type": "string", "format": "email" },
                  "target_role": { "type": "string", "enum": ["artist", "producer", "listener"] }
                },
                "required": ["action"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful referral resolution",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/user.php": {
      "post": {
        "summary": "User Registration & Profile Claiming",
        "description": "Register new accounts with referral attribution or claim unlinked artist profiles.",
        "operationId": "userOperations",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": ["register", "login", "claim_profile", "get_profile"]
                  },
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string" },
                  "name": { "type": "string" },
                  "role": { "type": "string", "enum": ["artist", "producer", "listener"] },
                  "referral_code": { "type": "string" },
                  "artist_id": { "type": "string" }
                },
                "required": ["action"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authentication or claiming response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "token": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}