# AfricanMusic Ringtone API Documentation

## Overview

The AfricanMusic Ringtone API allows mobile operators to integrate African music ringtones into their platforms. This REST API provides access to thousands of ringtones with search, filtering, and download tracking capabilities.

## Base URL

```
https://africanmusic.online/api/v1
```

## Authentication

All API requests require an API key passed in the `x-api-key` header:

```bash
curl -H "x-api-key: YOUR_API_KEY" https://africanmusic.online/api/v1/ringtones
```

## Endpoints

### 1. List Ringtones

Get a list of available ringtones.

**Endpoint:** `GET /ringtones`

**Query Parameters:**
- `search` (string, optional) - Search by song title or artist name
- `genre` (string, optional) - Filter by genre
- `limit` (integer, optional) - Results per page (max 100, default 20)
- `offset` (integer, optional) - Pagination offset (default 0)

**Example Request:**
```bash
curl -H "x-api-key: africanmusic_abc123..." \
  "https://africanmusic.online/api/v1/ringtones?search=afrobeat&limit=10"
```

**Example Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Summer Vibes",
      "artist_name": "African Star",
      "genre": "Afrobeat",
      "duration": 210,
      "ringtone_duration": 30,
      "price": 0.99,
      "audio_url": "https://...",
      "cover_url": "https://...",
      "play_count": 15234
    }
  ],
  "meta": {
    "total": 156,
    "limit": 10,
    "offset": 0,
    "company": "Your Company Name"
  }
}
```

### 2. Get Ringtone Details

Get detailed information about a specific ringtone.

**Endpoint:** `GET /ringtones/:id`

**Example Request:**
```bash
curl -H "x-api-key: africanmusic_abc123..." \
  "https://africanmusic.online/api/v1/ringtones/123e4567-e89b-12d3-a456-426614174000"
```

**Example Response:**
```json
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Summer Vibes",
    "artist_name": "African Star",
    "genre": "Afrobeat",
    "duration": 210,
    "ringtone_duration": 30,
    "price": 0.99,
    "audio_url": "https://...",
    "cover_url": "https://..."
  }
}
```

### 3. Record Ringtone Download

Record a ringtone download and get the download URL.

**Endpoint:** `POST /ringtones/:id`

**Request Body:**
```json
{
  "customer_phone": "+1234567890",
  "currency": "USD"
}
```

**Example Request:**
```bash
curl -X POST \
  -H "x-api-key: africanmusic_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"customer_phone": "+1234567890", "currency": "USD"}' \
  "https://africanmusic.online/api/v1/ringtones/123e4567-e89b-12d3-a456-426614174000"
```

**Example Response:**
```json
{
  "success": true,
  "data": {
    "track_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Summer Vibes",
    "price": 0.99,
    "currency": "USD",
    "download_url": "https://africanmusic.online/api/v1/ringtones/123e4567.../download?key=..."
  }
}
```

## Rate Limiting

Each API key has a daily rate limit specified during creation (default: 1000 requests/day). When the limit is exceeded, you'll receive a `429 Too Many Requests` response.

## Error Responses

The API uses standard HTTP status codes:

- `200` - Success
- `401` - Unauthorized (invalid or missing API key)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `429` - Rate Limit Exceeded
- `500` - Internal Server Error

**Error Response Format:**
```json
{
  "error": "Rate limit exceeded"
}
```

## Permissions

API keys can have the following permissions:

- `ringtone:read` - List and view ringtones
- `ringtone:download` - Record downloads and get download URLs
- `track:search` - Search functionality

## Getting Started

1. Contact AfricanMusic admin to request API credentials
2. Receive your API key and secret (store securely!)
3. Test the API using the examples above
4. Integrate into your mobile operator platform

## Support

For technical support or to request API access:
- Email: api@africanmusic.online
- Admin Dashboard: https://africanmusic.online/admin/ringtone-api
