API Documentation

Build on the HIPHOP.WORLD platform. Access profiles, cards, communities, events, and music data.

1

Apply for Access

Submit a partner application and get approved for an API key.

2

Get Your Keys

Generate API keys from your enterprise dashboard.

3

Start Building

Authenticate and call the API. All responses are JSON.

Base URL

https://hiphop.world/api/v1

Authentication

Two methods are supported. Use API Key for server-to-server calls, OAuth Bearer for user-delegated access.

API Key

Server-to-server authentication for enterprise partners. Pass your key in the X-API-Key header.

curl -H "X-API-Key: hpw_live_abc123..." \
  https://hiphop.world/api/v1/cards.php?action=list

OAuth Bearer Token

User-delegated access via OAuth2. Pass the JWT access token in the Authorization header.

curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://hiphop.world/api/v1/users.php?action=me

OAuth2 Flow

HIPHOP.WORLD supports the Authorization Code flow with PKCE for public clients.

Authorize: https://hiphop.world/oauth/authorize

Token: https://hiphop.world/api/oauth/token.php

UserInfo: https://hiphop.world/api/oauth/userinfo.php

Discovery: https://hiphop.world/.well-known/openid-configuration

Redirect user to /oauth/authorize?client_id=YOUR_ID&redirect_uri=CALLBACK&response_type=code&scope=openid+profile
User logs in and consents to the requested scopes
User is redirected to your redirect_uri with a code parameter
Exchange the code for tokens via POST to /api/oauth/token.php
Use the access token (RS256 JWT, 1h expiry) to call API endpoints

PKCE Required for Public Clients: Send code_challenge (S256) in the authorize request and code_verifier in the token exchange. Confidential clients use client_secret instead.

Scopes

Request only the scopes your application needs. Available scopes depend on your enterprise tier.

Scope	Description
profile	Read basic profile info (username, display name, avatar)
email	Read email address
cash.balance	Read Cash balance
cash.transfer	Initiate Cash transfers
cards.read	Read cards and stacks
cards.write	Create and manage cards
communities.read	Read community info
communities.write	Manage communities
events.read	Read events and tours
events.write	Create and manage events
directory.read	Read directory listings
directory.write	Manage directory listings
music.read	Read music catalog

Users

Access user profiles. The me action requires an OAuth token with user context (API keys cannot be used).

GET /api/v1/users.php?action=me profile OAuth

Returns the profile of the user associated with the OAuth access token. Not available with API key auth.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "me"

Response

{
    "data": {
        "username": "djsoul",
        "display_name": "DJ Soul",
        "hip_hop_id": "HH-0042",
        "email": "dj@example.com",
        "avatar_url": "https://hiphop.world/avatars/42.jpg",
        "created_at": "2025-01-15T10:30:00Z"
    }
}

Possible errors: 401 403

GET /api/v1/users.php?action=lookup&username={username} profile Key OAuth

Returns the public profile for a given username. Works with both API key and OAuth auth.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "lookup"
username	query	string	yes	Username to look up

Response

{
    "data": {
        "username": "djsoul",
        "display_name": "DJ Soul",
        "avatar_url": "https://hiphop.world/avatars/42.jpg",
        "hip_hop_id": "HH-0042",
        "bio": "Producer from ATL",
        "created_at": "2025-01-15T10:30:00Z"
    }
}

Possible errors: 401 403 404

Cards

Browse and inspect cards. 9 types: audio, photo, movie, marketing, social, tour, capital, vote, trade.

GET /api/v1/cards.php?action=list cards.read Key OAuth

Returns a paginated list of active cards. Filter by type, creator username, or community.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "list"
type	query	string	no	Filter by card type (audio, photo, movie, etc.)
creator	query	string	no	Filter by creator username
community	query	string	no	Filter by community code
limit	query	integer	no	Results per page (1-100, default 20)
offset	query	integer	no	Pagination offset

Response

{
    "data": [
        {
            "id": 1,
            "card_type": "audio",
            "title": "Summer Beat",
            "description": "A chill summer instrumental",
            "media_url": "https://hiphop.world/media/cards/1.mp3",
            "cash_locked": 500,
            "holder_count": 42,
            "status": "active",
            "created_at": "2025-03-01T08:00:00Z",
            "creator_username": "djsoul",
            "creator_display_name": "DJ Soul",
            "stack_count": 3
        }
    ],
    "pagination": {
        "total": 128,
        "limit": 20,
        "offset": 0
    }
}

Possible errors: 401 403

GET /api/v1/cards.php?action=detail&id={id} cards.read Key OAuth

Returns full card info including stacks (communities) and holders.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "detail"
id	query	integer	yes	Card ID

Response

{
    "data": {
        "id": 1,
        "card_type": "audio",
        "title": "Summer Beat",
        "status": "active",
        "stacks": [
            {
                "community_name": "Town Square",
                "community_code": "0000"
            }
        ],
        "holders": [
            {
                "username": "djsoul",
                "display_name": "DJ Soul"
            }
        ]
    }
}

Possible errors: 401 403 404

GET /api/v1/cards.php?action=types cards.read Key OAuth

Returns all available card types with descriptions.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "types"

Response

{
    "data": [
        {
            "type": "audio",
            "description": "Music, beats, podcasts"
        },
        {
            "type": "photo",
            "description": "Photography and artwork"
        },
        {
            "type": "movie",
            "description": "Video content"
        },
        {
            "type": "marketing",
            "description": "Promotional content"
        },
        {
            "type": "social",
            "description": "Social connection cards"
        },
        {
            "type": "tour",
            "description": "Tour packages"
        },
        {
            "type": "capital",
            "description": "Governance and finance cards"
        },
        {
            "type": "vote",
            "description": "Voting and governance cards"
        },
        {
            "type": "trade",
            "description": "Exchange and trade cards"
        }
    ]
}

Possible errors: 401 403

Communities

Browse communities on the 10x10 land grid. Each community has places, stacking, and governance.

GET /api/v1/communities.php?action=list communities.read Key OAuth

Returns paginated communities (excludes locked). Search by name or code.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "list"
search	query	string	no	Search by name or code
limit	query	integer	no	Results per page (1-100, default 20)
offset	query	integer	no	Pagination offset

Response

{
    "data": [
        {
            "id": 1,
            "code": "0000",
            "name": "Town Square",
            "description": "The genesis community",
            "status": "active",
            "voting_power": 1520,
            "owner_username": "hiphopworld",
            "owner_display_name": "HIPHOP.WORLD",
            "place_count": 100,
            "claimed_places": 48,
            "active_stackers": 210
        }
    ],
    "pagination": {
        "total": 48,
        "limit": 20,
        "offset": 0
    }
}

Possible errors: 401 403

GET /api/v1/communities.php?action=detail&id={id} communities.read Key OAuth

Full community info including places, voting breakdown, and stats.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "detail"
id	query	integer	yes	Community ID

Response

{
    "data": {
        "id": 1,
        "code": "0000",
        "name": "Town Square",
        "places": [
            {
                "id": 1,
                "name": "Main Stage",
                "owner_username": "djsoul"
            }
        ],
        "voting_breakdown": [
            {
                "source": "stacking",
                "power": 1200
            }
        ],
        "stats": {
            "total_places": 100,
            "claimed_places": 48,
            "total_stacks": 1520
        }
    }
}

Possible errors: 401 403 404

Events

Browse events and tours. Supports physical, digital, and hybrid events with single, multi, or recurring dates.

GET /api/v1/events.php?action=list events.read Key OAuth

Returns upcoming events by default. Filter by type and date range.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "list"
type	query	string	no	physical, digital, or hybrid
date_from	query	string	no	Start date filter (YYYY-MM-DD)
date_to	query	string	no	End date filter (YYYY-MM-DD)
limit	query	integer	no	Results per page (1-100, default 20)
offset	query	integer	no	Pagination offset

Response

{
    "data": [
        {
            "id": 10,
            "title": "Block Party NYC",
            "event_type": "physical",
            "venue_name": "Brooklyn Bowl",
            "venue_city": "Brooklyn",
            "venue_state": "NY",
            "is_free": false,
            "status": "published",
            "organizer_username": "djsoul",
            "organizer_display_name": "DJ Soul",
            "next_date": "2025-07-04T18:00:00Z",
            "total_dates": 1
        }
    ],
    "pagination": {
        "total": 64,
        "limit": 20,
        "offset": 0
    }
}

Possible errors: 401 403

GET /api/v1/events.php?action=detail&id={id} events.read Key OAuth

Full event info including all scheduled dates and recurrence rules.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "detail"
id	query	integer	yes	Event ID

Response

{
    "data": {
        "id": 10,
        "title": "Block Party NYC",
        "event_type": "physical",
        "venue_name": "Brooklyn Bowl",
        "description": "Annual summer block party",
        "dates": [
            {
                "start_datetime": "2025-07-04T18:00:00Z",
                "end_datetime": "2025-07-04T23:00:00Z",
                "is_all_day": false
            }
        ],
        "recurrence": null
    }
}

Possible errors: 401 403 404

Music

Browse the music catalog: artists, albums, and songs with lyrics and playback metadata.

GET /api/v1/music.php?action=artists music.read Key OAuth

Search and paginate through artist profiles.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "artists"
search	query	string	no	Search by artist name
limit	query	integer	no	Results per page (1-100, default 20)
offset	query	integer	no	Pagination offset

Response

{
    "data": [
        {
            "id": 1,
            "name": "DJ Soul",
            "slug": "dj-soul",
            "avatar_url": "https://hiphop.world/avatars/artists/1.jpg",
            "bio": "Producer from ATL",
            "linked_username": "djsoul",
            "album_count": 3,
            "song_count": 24
        }
    ],
    "pagination": {
        "total": 210,
        "limit": 20,
        "offset": 0
    }
}

Possible errors: 401 403

GET /api/v1/music.php?action=albums&artist_id={artist_id} music.read Key OAuth

Returns albums for a given artist with track counts.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "albums"
artist_id	query	integer	yes	Artist ID
limit	query	integer	no	Results per page (1-100, default 20)
offset	query	integer	no	Pagination offset

Response

{
    "artist": {
        "id": 1,
        "name": "DJ Soul",
        "slug": "dj-soul"
    },
    "albums": [
        {
            "id": 1,
            "title": "First Light",
            "slug": "first-light",
            "artwork_url": "https://hiphop.world/media/albums/1.jpg",
            "release_year": 2025,
            "track_count": 8,
            "active_song_count": 8
        }
    ],
    "pagination": {
        "total": 3,
        "limit": 20,
        "offset": 0
    }
}

Possible errors: 401 403

GET /api/v1/music.php?action=songs&album_id={album_id} music.read Key OAuth

Returns songs for a given album with playback and lyrics metadata.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "songs"
album_id	query	integer	yes	Album ID
limit	query	integer	no	Results per page (1-100, default 50)
offset	query	integer	no	Pagination offset

Response

{
    "album": {
        "id": 1,
        "title": "First Light",
        "artist_name": "DJ Soul"
    },
    "songs": [
        {
            "id": 1,
            "title": "Golden Hour",
            "slug": "golden-hour",
            "track_number": 1,
            "duration": 225,
            "features": null,
            "play_count": 1420,
            "has_lyrics": true
        }
    ],
    "pagination": {
        "total": 8,
        "limit": 50,
        "offset": 0
    }
}

Possible errors: 401 403

Land

Browse the 10,000 territory marketplace (0000-9999). Public read-only access, no authentication required. Rate limited to 60 requests/min per IP.

GET /api/v1/land.php?action=list Public

Returns a paginated list of territories. Filter by claim status and search by territory ID or owner name. Cached 5 minutes.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "list"
page	query	integer	no	Page number (1-indexed, default 1)
per_page	query	integer	no	Results per page (1-100, default 20)
filter	query	string	no	Filter: all, claimed, or unclaimed (default all)
search	query	string	no	Search by territory ID (numeric) or owner display name

Response

{
    "success": true,
    "data": {
        "territories": [
            {
                "id": 42,
                "code": "0042",
                "display_name": "Beat Lab",
                "description": "Production headquarters",
                "banner_url": "https://hiphop.world/uploads/land/42-banner.jpg",
                "accent_color": "#FF6B35",
                "status": "claimed",
                "claimed_at": "2026-01-15T10:30:00Z",
                "url": "https://hiphop.land/0042",
                "owner": {
                    "username": "djsoul",
                    "display_name": "DJ Soul",
                    "avatar_url": "https://hiphop.world/avatars/42.jpg"
                }
            }
        ],
        "pagination": {
            "total": 10000,
            "page": 1,
            "per_page": 20,
            "total_pages": 500
        }
    },
    "api_version": "1.0",
    "documentation": "https://hiphop.world/api/v1/docs"
}

Possible errors: 429 500

GET /api/v1/land.php?action=detail&id={id} Public

Returns full territory info including owner profile, featured directory listings, and featured audio releases. Cached 5 minutes.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "detail"
id	query	integer	yes	Territory ID (0-9999)

Response

{
    "success": true,
    "data": {
        "id": 42,
        "code": "0042",
        "display_name": "Beat Lab",
        "status": "claimed",
        "url": "https://hiphop.land/0042",
        "owner": {
            "username": "djsoul",
            "display_name": "DJ Soul"
        },
        "featured_directory": [
            {
                "profile_name": "Soul Productions",
                "profile_slug": "soul-productions",
                "profile_category": "music-production"
            }
        ],
        "featured_audio": [
            {
                "album_title": "First Light",
                "album_slug": "first-light",
                "artist_name": "DJ Soul"
            }
        ]
    },
    "api_version": "1.0",
    "documentation": "https://hiphop.world/api/v1/docs"
}

Possible errors: 400 404 429 500

GET /api/v1/land.php?action=pricing Public

Returns current territory price, progressive pricing tiers, and supply info. Cached 1 minute.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "pricing"

Response

{
    "success": true,
    "data": {
        "current_price_usd": 100,
        "lands_sold": 47,
        "total_supply": 10000,
        "total_available": 9953,
        "current_tier": 0,
        "lands_until_price_increase": 453,
        "next_price_usd": 200,
        "tiers": [
            {
                "tier": 0,
                "price_usd": 100,
                "range_start": 0,
                "range_end": 499,
                "is_current": true
            },
            {
                "tier": 1,
                "price_usd": 200,
                "range_start": 500,
                "range_end": 999,
                "is_current": false
            }
        ]
    },
    "api_version": "1.0",
    "documentation": "https://hiphop.world/api/v1/docs"
}

Possible errors: 429 500

GET /api/v1/land.php?action=recent Public

Returns the most recently claimed territories, ordered by claim date descending. Cached 5 minutes.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "recent"
limit	query	integer	no	Number of results (1-50, default 10)

Response

{
    "success": true,
    "data": [
        {
            "id": 42,
            "code": "0042",
            "display_name": "Beat Lab",
            "claimed_at": "2026-01-15T10:30:00Z",
            "price_paid": 100,
            "owner": {
                "username": "djsoul",
                "display_name": "DJ Soul"
            }
        }
    ],
    "api_version": "1.0",
    "documentation": "https://hiphop.world/api/v1/docs"
}

Possible errors: 429 500

GET /api/v1/land.php?action=leaderboard Public

Returns top territories ranked by views (30-day), newest claims, or featured content count. Cached 10 minutes.

Parameters

Name	In	Type	Req	Description
action	query	string	yes	Must be "leaderboard"
sort	query	string	no	Sort by: views (default), newest, or featured
limit	query	integer	no	Number of results (1-50, default 25)

Response

{
    "success": true,
    "data": {
        "sort_by": "views",
        "territories": [
            {
                "rank": 1,
                "id": 0,
                "code": "0000",
                "display_name": "Town Square",
                "views_30d": 1520,
                "owner": {
                    "username": "hiphopworld",
                    "display_name": "HIPHOP.WORLD"
                }
            }
        ]
    },
    "api_version": "1.0",
    "documentation": "https://hiphop.world/api/v1/docs"
}

Possible errors: 429 500

OAuth

OpenID Connect / OAuth2 endpoints for authorization, token exchange, and identity.

GET /.well-known/openid-configuration Public

Auto-discovery metadata for the OAuth2/OIDC provider. Public, no auth required. Cached 24 hours.

Response

{
    "issuer": "https://hiphop.world",
    "authorization_endpoint": "https://hiphop.world/oauth/authorize",
    "token_endpoint": "https://hiphop.world/api/oauth/token.php",
    "userinfo_endpoint": "https://hiphop.world/api/oauth/userinfo.php",
    "jwks_uri": "https://hiphop.world/.well-known/jwks.json"
}

Possible errors: 405

POST /api/oauth/token.php Public

Exchange authorization codes for access tokens, refresh tokens, or issue client credentials. Supports application/x-www-form-urlencoded and application/json.

Parameters

Name	In	Type	Req	Description
grant_type	body	string	yes	authorization_code, refresh_token, or client_credentials
code	body	string	no	Authorization code (for authorization_code grant)
client_id	body	string	yes	Your OAuth client ID
client_secret	body	string	no	Client secret (required for confidential clients)
redirect_uri	body	string	no	Must match the original authorize request
code_verifier	body	string	no	PKCE code verifier (S256)
refresh_token	body	string	no	Refresh token (for refresh_token grant)

Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "def50200abc123...",
    "scope": "openid profile email"
}

Possible errors: 400 401

GET /api/oauth/userinfo.php openid OAuth

OpenID Connect UserInfo endpoint. Returns claims based on granted scopes. Also accepts POST.

Response

{
    "sub": "42",
    "username": "djsoul",
    "display_name": "DJ Soul",
    "avatar_url": "https://hiphop.world/avatars/42.jpg",
    "bio": "Producer from ATL",
    "email": "dj@example.com",
    "email_verified": true
}

Possible errors: 401

GET /.well-known/jwks.json Public

Public keys for verifying RS256-signed access tokens. Cached 1 hour.

Response

{
    "keys": [
        {
            "kty": "RSA",
            "alg": "RS256",
            "use": "sig",
            "kid": "abc123def456",
            "n": "...",
            "e": "AQAB"
        }
    ]
}

POST /api/oauth/clients.php Session

Create a new OAuth2 client application. Requires an authenticated session. Max 10 apps per user. HTTPS required for redirect URIs (localhost exempt).

Parameters

Name	In	Type	Req	Description
name	body	string	yes	App name (max 255 chars)
description	body	string	no	App description
redirect_uris	body	array	yes	Callback URLs (HTTPS required)
scopes	body	string	no	Space-separated scopes (default: openid profile)
is_confidential	body	boolean	no	Confidential client (default: true)

Response

{
    "client_id": "a1b2c3d4e5f6...",
    "client_secret": "secret_shown_once...",
    "name": "My App",
    "message": "Save your client_secret now -- it cannot be retrieved later."
}

Possible errors: 400 401

Errors

All errors return a consistent JSON body:

{
  "error": "insufficient_scope",
  "error_description": "This endpoint requires the cards.read scope"
}

HTTP Status Codes

200	Request succeeded
201	Resource created successfully
400	Invalid or missing parameters
401	Missing or invalid API key / token
403	Insufficient scope or permissions
404	Resource does not exist
405	HTTP method not supported for this endpoint
429	Rate limit exceeded -- check Retry-After header
500	Internal error -- contact support

OAuth Error Codes

invalid_request	Missing required parameter
invalid_client	Unknown client_id or bad credentials
invalid_grant	Expired or invalid authorization code
unauthorized_client	Client not authorized for this grant type
unsupported_grant_type	Grant type not supported
invalid_scope	Requested scope not allowed
access_denied	User denied consent
insufficient_scope	Token lacks required scope
invalid_token	Token expired, revoked, or malformed

Rate Limits

Limits depend on your enterprise tier. All limits reset daily at midnight UTC.

Tier	Daily Limit	Per Minute	Monthly Cost	OAuth Apps
starter	1,000	1	100 Cash	1
professional	10,000	7	500 Cash	3
enterprise	100,000	70	2,000 Cash	Unlimited

Rate Limit Headers

X-RateLimit-Limit: Your daily limit

X-RateLimit-Remaining: Calls remaining today

X-RateLimit-Reset: Unix timestamp when the window resets

Retry-After: Seconds to wait (only on 429)

When you receive a 429 Too Many Requests, back off for the number of seconds in the Retry-After header.

Code Examples

API Key Authentication

curl -H "X-API-Key: hpw_live_your_key_here" \
  https://hiphop.world/api/v1/cards.php?action=list&type=audio

OAuth Bearer Token

curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://hiphop.world/api/v1/users.php?action=me

API Key Authentication

const res = await fetch('https://hiphop.world/api/v1/cards.php?action=list&type=audio', {
  headers: { 'X-API-Key': 'hpw_live_your_key' }
});
const { data } = await res.json();
console.log(data);

OAuth Bearer Token

const res = await fetch('https://hiphop.world/api/v1/users.php?action=me', {
  headers: { 'Authorization': 'Bearer ' + accessToken }
});
const user = await res.json();
console.log(user.data.username);

API Key Authentication

$ch = curl_init('https://hiphop.world/api/v1/cards.php?action=list&type=audio');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER     => ['X-API-Key: hpw_live_your_key'],
  CURLOPT_RETURNTRANSFER => true,
]);
$cards = json_decode(curl_exec($ch), true);
curl_close($ch);

OAuth Bearer Token

$ch = curl_init('https://hiphop.world/api/v1/users.php?action=me');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $token],
  CURLOPT_RETURNTRANSFER => true,
]);
$user = json_decode(curl_exec($ch), true);
curl_close($ch);

API Key Authentication

import requests

r = requests.get(
    'https://hiphop.world/api/v1/cards.php',
    params={'action': 'list', 'type': 'audio'},
    headers={'X-API-Key': 'hpw_live_your_key'}
)
cards = r.json()['data']

OAuth Bearer Token

import requests

r = requests.get(
    'https://hiphop.world/api/v1/users.php',
    params={'action': 'me'},
    headers={'Authorization': f'Bearer {access_token}'}
)
user = r.json()['data']