Public Tagging API Documentation

Design Philosophy

• ✓ Simple: Easy to understand and implement
• ✓ Interoperable: Works with any RSS music application
• ✓ Secure: API key protection for write operations
• ✓ RSS-Compatible: Uses standard RSS identifiers

Authentication Model

• Read No authentication required (anonymous access)
• Write Valid API key required
• Rate Limiting Different limits for authenticated vs anonymous users

API Key Format

API keys follow this format:

v4v_<32 random base64url characters>

Example: v4v_b4cr2eI2fBtTGJ-A9s9oR-MEGlSOhMLBLe1IncQZWWw

Using API Keys

API keys can be provided in two ways:

Header Method (Recommended)

curl -H "x-api-key: v4v_your_api_key_here" \
     https://v4vmusic.com/api/public/items/byGuid/05b75483-9f5b-5236-bd66-69e9d3e1b995/c56c5b2b-fa79-4cd7-ae23-55cb207b103b/tags

Body Method (for POST requests)

{
  "tags": ["rock", "metal"],
  "apiKey": "v4v_your_api_key_here"
}

JavaScript (Fetch API)

// Get all tags
const response = await fetch('https://v4vmusic.com/api/public/tags');
const data = await response.json();

// Add tags to an item
const addTags = async (feedGuid, itemGuid, tags, apiKey) => {
  const response = await fetch(
    `https://v4vmusic.com/api/public/items/byGuid/${feedGuid}/${itemGuid}/tags`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({ tags })
    }
  );
  return response.json();
};

Python (requests)

import requests

# Get all tags
response = requests.get('https://v4vmusic.com/api/public/tags')
tags = response.json()

# Add tags to an item
def add_tags(feed_guid, item_guid, tags, api_key):
    url = f'https://v4vmusic.com/api/public/items/byGuid/{feed_guid}/{item_guid}/tags'
    headers = {'x-api-key': api_key}
    data = {'tags': tags}
    response = requests.post(url, json=data, headers=headers)
    return response.json()

Discovering Music by Tags

1. Get all available tags: GET /api/public/tags
2. Find items with specific tags: GET /api/public/items/bytag/{tagName}
3. Get detailed item information: GET /api/public/items/byGuid/{feedGuid}/{itemGuid}

Contributing Tags to Music

1. Obtain an API key from the API Keys page
2. Identify the item's RSS identifiers (feedGuid, itemGuid)
3. Submit tags: POST /api/public/items/byGuid/{feedGuid}/{itemGuid}/tags
4. Verify the tags were added: GET /api/public/items/byGuid/{feedGuid}/{itemGuid}/tags

Building a Tag-Based Recommendation System

1. Analyze user's favorite music to identify common tags
2. Find similar items using those tags
3. Suggest new music based on tag overlap
4. Allow users to contribute tags to improve recommendations