Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Default Settings system provides a powerful way to define reusable configurations that automatically apply to your catalog items (assets, products, and releases). Settings cascade through a hierarchical inheritance chain, allowing you to set defaults at different organizational levels while maintaining the flexibility to override them when needed.

​
Key Benefits

  • Reduce Repetitive Data Entry: Set common values once and have them automatically applied to new items
  • Maintain Consistency: Ensure catalog items follow organizational standards and branding
  • Flexible Inheritance: Override defaults at any level in the hierarchy
  • Template Library: Create and share reusable configuration presets
  • Preview Before Apply: Test how defaults will affect items without modifying data

​
Inheritance Chain

Default settings follow a priority-based inheritance chain, with higher levels overriding lower levels: 
User Settings (Highest Priority)
    ↓
Artist Settings
    ↓
Label Settings
    ↓
Catalog Settings
    ↓
Tenant Settings (Lowest Priority)
Example Scenario:
  1. Tenant Level: Set default language to “en” for all content
  2. Label Level: Override with genre [“Rock”, “Alternative”] for a specific label
  3. Artist Level: Add explicit content flag for a particular artist
  4. User Level: Individual users can set their own defaults
When creating a new product, the system merges all applicable defaults, with more specific settings taking precedence.

​
Endpoint Patterns

The Default Settings API uses two distinct endpoint patterns depending on the entity type:

​
Pattern 1: Tenant/Catalog (No Entity ID)

For workspace-wide and catalog-level settings, use endpoints without an entity ID:
  • GET /defaultsettings/{entityType}
  • POST /defaultsettings/{entityType}
  • PUT /defaultsettings/{entityType}/{settingId}
  • DELETE /defaultsettings/{entityType}/{settingId}
Applies to: tenant, catalog Example: 
GET /defaultsettings/tenant
POST /defaultsettings/catalog
PUT /defaultsettings/tenant/{settingId}
DELETE /defaultsettings/catalog/{settingId}

​
Pattern 2: Label/Artist/User (With Entity ID)

For entity-specific settings, use endpoints with an entity ID:
  • GET /defaultsettings/{entityType}/{entityId}
  • POST /defaultsettings/{entityType}/{entityId}
  • PUT /defaultsettings/{entityType}/{entityId}/{settingId}
  • DELETE /defaultsettings/{entityType}/{entityId}/{settingId}
Applies to: label, artist, user Example: 
GET /defaultsettings/artist/{artistId}
POST /defaultsettings/label/{labelId}
PUT /defaultsettings/artist/{artistId}/{settingId}
DELETE /defaultsettings/user/{userId}/{settingId}
Why two patterns? Tenant and catalog settings are global to your workspace and don’t belong to a specific entity, so they don’t require an entity ID. Label, artist, and user settings are entity-specific and require the entity ID to identify which specific label, artist, or user the settings belong to.

​
Settings Categories

Default settings are organized into four categories:

​
1. Content Settings

Metadata related to the creative content:
  • type: Media type (Audio, Video, Ringtone, YouTube)
  • format: Release format (Single, EP, Album, LP)
  • version: Version info (Deluxe Edition, Remastered, etc.)
  • explicit: Content rating (explicit, clean)
  • language: Primary language (ISO 639-1 code)
  • mainGenre: Primary genre classifications
  • subGenre: Secondary genre classifications
  • contributors: Role-based contributors map
Example: 
{
  "content": {
    "type": "Audio",
    "format": "Album",
    "mainGenre": ["Hip-Hop", "Rap"],
    "explicit": "explicit",
    "language": "en",
    "contributors": {
      "Producer": ["Dr. Dre", "Scott Storch"],
      "Mixer": ["Mike Dean"]
    }
  }
}

​
2. Business Settings

Rights, ownership, and commercial metadata:
  • label: Record label name
  • copyright: Copyright notice (e.g., ”© 2024 Label Name”)
  • publisher: Music publisher name
  • copyrightOwner: Copyright holder
  • distribution: Distribution method or partner
  • status: Default release status (Live, Scheduled, Pending)
Example: 
{
  "business": {
    "label": "Aftermath Entertainment",
    "copyright": "© 2024 Aftermath Entertainment",
    "publisher": "Universal Music Publishing",
    "distribution": "Empire Distribution",
    "status": "Pending"
  }
}

​
3. DDEX Settings

DDEX message generation configuration:
  • enableDDEX: Enable automatic DDEX message generation
  • labelName: Label name for DDEX messages
  • resourceReference: Resource reference pattern
  • grid: Global Release Identifier
  • icpn: International Catalog Product Number
Example: 
{
  "ddex": {
    "enableDDEX": true,
    "labelName": "Aftermath",
    "resourceReference": "AFT-{YEAR}-{SEQUENCE}"
  }
}

​
4. Validation Settings

Business rules and requirements:
  • requireGenre: Enforce genre selection
  • requireLyrics: Require lyrics for tracks
  • requireDescription: Require description field
  • minimumTrackCount: Minimum tracks per release
  • maximumTrackCount: Maximum tracks per release
Example: 
{
  "validation": {
    "requireGenre": true,
    "requireLyrics": true,
    "minimumTrackCount": 1,
    "maximumTrackCount": 30
  }
}

​
Quick Start Guide

​
Step 1: Set Tenant-Wide Defaults

Start by setting defaults that apply to your entire workspace: 
POST /defaultsettings/tenant

{
  "category": "content",
  "settings": {
    "content": {
      "language": "en",
      "type": "Audio"
    }
  }
}

​
Step 2: Create Label-Specific Overrides

Customize settings for specific labels: 
POST /defaultsettings/label/{labelId}

{
  "category": "content",
  "settings": {
    "content": {
      "format": "Album",
      "mainGenre": ["Electronic", "Dance"]
    }
  }
}

​
Step 3: Preview Before Creating Items

Test how defaults will apply to a new product: 
POST /defaultsettings/preview/product

{
  "labelId": "550e8400-e29b-41d4-a716-446655440000",
  "productData": {
    "productName": "New Album",
    "releaseDate": "2024-12-01"
  }
}
Response: 
{
  "success": true,
  "data": {
    "original": {
      "productName": "New Album",
      "releaseDate": "2024-12-01"
    },
    "withDefaults": {
      "productName": "New Album",
      "releaseDate": "2024-12-01",
      "language": "en",
      "type": "Audio",
      "format": "Album",
      "mainGenre": ["Electronic", "Dance"]
    },
    "appliedDefaults": [
      {
        "field": "language",
        "value": "en",
        "source": {
          "entityType": "tenant",
          "category": "content"
        }
      },
      {
        "field": "format",
        "value": "Album",
        "source": {
          "entityType": "label",
          "entityId": "550e8400-e29b-41d4-a716-446655440000",
          "category": "content"
        }
      }
    ]
  }
}

​
Working with Templates

Templates provide reusable configuration presets that can be quickly applied to entities.

​
Creating a Template

POST /defaultsettings/templates

{
  "name": "Hip-Hop Album Standard",
  "description": "Standard settings for hip-hop album releases",
  "category": "content",
  "entityType": "release",
  "settings": {
    "content": {
      "type": "Audio",
      "format": "Album",
      "mainGenre": ["Hip-Hop", "Rap"],
      "language": "en"
    }
  },
  "isPublic": true,
  "tags": ["hip-hop", "album", "standard"]
}

​
Applying a Template

Apply a template to create default settings for an artist: 
POST /defaultsettings/templates/{templateId}/apply

{
  "entityType": "artist",
  "entityId": "660e8400-e29b-41d4-a716-446655440001"
}

​
Updating a Template

Modify an existing template (only the creator can update): 
PUT /defaultsettings/templates/{templateId}

{
  "name": "Updated Hip-Hop Album Standard",
  "description": "Revised settings with new industry standards",
  "tags": ["hip-hop", "album", "2024-update"]
}

​
Deleting a Template

Remove a template permanently (only the creator can delete): 
DELETE /defaultsettings/templates/{templateId}
Deleting a template does not affect default settings that were created from it. Those settings remain intact.
Discover frequently used templates: 
GET /defaultsettings/templates/popular?limit=10

​
Searching Templates

Find templates by tags or search terms: 
GET /defaultsettings/templates?tags=hip-hop,album&search=standard&limit=20

​
Advanced Use Cases

​
Use Case 1: Multi-Label Organization

Scenario: You manage multiple labels with different branding requirements. Solution:
  1. Set tenant defaults for universal requirements (language, basic validation)
  2. Create label-specific settings for each imprint’s branding
  3. Use templates for genre-specific configurations
# Universal tenant settings
POST /defaultsettings/tenant
{
  "category": "validation",
  "settings": {
    "validation": {
      "requireGenre": true,
      "requireDescription": true
    }
  }
}

# Label A: Electronic Music Focus
POST /defaultsettings/label/{labelAId}
{
  "category": "content",
  "settings": {
    "content": {
      "mainGenre": ["Electronic", "Dance"],
      "format": "Single"
    }
  }
}

# Label B: Hip-Hop Focus
POST /defaultsettings/label/{labelBId}
{
  "category": "content",
  "settings": {
    "content": {
      "mainGenre": ["Hip-Hop", "Rap"],
      "format": "Album",
      "explicit": "explicit"
    }
  }
}

​
Use Case 2: Artist-Specific Branding

Scenario: An artist has consistent branding across all releases. Solution:
  1. Set artist-level defaults for consistent metadata
  2. Include contributor information
  3. Set DDEX configuration for automated distribution
POST /defaultsettings/artist/{artistId}
{
  "category": "content",
  "settings": {
    "content": {
      "contributors": {
        "Producer": ["Artist's Producer"],
        "Mixer": ["Artist's Engineer"]
      }
    }
  }
}

POST /defaultsettings/artist/{artistId}
{
  "category": "business",
  "settings": {
    "business": {
      "label": "Artist's Label",
      "copyright": "© 2024 Artist Name",
      "publisher": "Artist's Publishing"
    }
  }
}

​
Use Case 3: Cloning Settings

Scenario: You want to replicate settings from one artist to a similar artist. Solution: Use the clone endpoint to copy all settings: 
POST /defaultsettings/clone
{
  "sourceEntityType": "artist",
  "sourceEntityId": "550e8400-e29b-41d4-a716-446655440000",
  "targetEntityType": "artist",
  "targetEntityId": "660e8400-e29b-41d4-a716-446655440001"
}

​
Resolution and Preview Endpoints

​
Understanding Resolution

The resolution process merges settings from all applicable levels in the inheritance chain: 
POST /defaultsettings/preview/resolve

{
  "labelId": "550e8400-e29b-41d4-a716-446655440000",
  "artistId": "660e8400-e29b-41d4-a716-446655440001",
  "targetType": "release"
}
Response shows the complete resolution chain: 
{
  "success": true,
  "data": {
    "resolved": {
      "content": {
        "language": "en",
        "type": "Audio",
        "format": "Album",
        "mainGenre": ["Hip-Hop", "Rap"],
        "explicit": "explicit"
      }
    },
    "chain": [
      {
        "entityType": "tenant",
        "category": "content",
        "settings": { "content": { "language": "en" } },
        "priority": 0
      },
      {
        "entityType": "label",
        "entityId": "550e8400-...",
        "category": "content",
        "settings": { "content": { "type": "Audio" } },
        "priority": 0
      },
      {
        "entityType": "artist",
        "entityId": "660e8400-...",
        "category": "content",
        "settings": {
          "content": {
            "format": "Album",
            "mainGenre": ["Hip-Hop", "Rap"],
            "explicit": "explicit"
          }
        },
        "priority": 0
      }
    ]
  }
}

​
Preview by Entity Type

Test defaults for specific catalog item types: Assets: 
POST /defaultsettings/preview/asset
{
  "artistId": "660e8400-e29b-41d4-a716-446655440001",
  "assetData": {
    "assetName": "New Track",
    "duration": 180
  }
}
Products: 
POST /defaultsettings/preview/product
{
  "labelId": "550e8400-e29b-41d4-a716-446655440000",
  "productData": {
    "productName": "New Album"
  }
}
Releases: 
POST /defaultsettings/preview/release
{
  "artistId": "660e8400-e29b-41d4-a716-446655440001",
  "releaseData": {
    "title": "New Release",
    "releaseDate": "2024-12-01"
  }
}

​
Managing Settings

​
Retrieving Settings

Get all settings for an entity. Use the appropriate endpoint pattern based on entity type: For tenant or catalog level: 
GET /defaultsettings/tenant
GET /defaultsettings/catalog
For label, artist, or user level: 
GET /defaultsettings/{entityType}/{entityId}

# Examples:
GET /defaultsettings/artist/{artistId}
GET /defaultsettings/label/{labelId}
GET /defaultsettings/user/{userId}
Filter by category: 
GET /defaultsettings/artist/{artistId}?category=content
GET /defaultsettings/tenant?category=business
Include inactive settings: 
GET /defaultsettings/label/{labelId}?includeInactive=true
GET /defaultsettings/catalog?includeInactive=true
Get a single setting by ID: 
GET /defaultsettings/settings/{settingId}
This last endpoint is useful when you have a setting ID from a previous response and want to retrieve just that specific setting without filtering through all entity settings, regardless of entity type.

​
Updating Settings

Update existing default settings (deep merge within category). Use the appropriate endpoint pattern based on entity type: For tenant or catalog level: 
PUT /defaultsettings/tenant/{settingId}
PUT /defaultsettings/catalog/{settingId}
For label, artist, or user level: 
PUT /defaultsettings/{entityType}/{entityId}/{settingId}

# Examples:
PUT /defaultsettings/artist/{artistId}/{settingId}
PUT /defaultsettings/label/{labelId}/{settingId}
PUT /defaultsettings/user/{userId}/{settingId}
Example request body: 
{
  "settings": {
    "content": {
      "explicit": "clean",
      "version": "Radio Edit"
    }
  }
}
Deactivate without deleting: 
PUT /defaultsettings/artist/{artistId}/{settingId}

{
  "isActive": false
}

​
Deleting Settings

Permanently remove a setting. Use the appropriate endpoint pattern based on entity type: For tenant or catalog level: 
DELETE /defaultsettings/tenant/{settingId}
DELETE /defaultsettings/catalog/{settingId}
For label, artist, or user level: 
DELETE /defaultsettings/{entityType}/{entityId}/{settingId}

# Examples:
DELETE /defaultsettings/artist/{artistId}/{settingId}
DELETE /defaultsettings/label/{labelId}/{settingId}
DELETE /defaultsettings/user/{userId}/{settingId}
Deletion is permanent and cannot be undone. Consider using isActive: false to temporarily deactivate settings instead.

​
Priority System

By default, all settings at the same level have equal priority (0). You can adjust priority for conflict resolution: 
POST /defaultsettings/label/{labelId}
{
  "category": "content",
  "settings": {
    "content": {
      "mainGenre": ["Rock", "Alternative"]
    }
  },
  "priority": 10
}
Higher priority values win within the same entity type.

​
Best Practices

​
1. Start Broad, Then Specialize

Begin with tenant-wide defaults for universal requirements, then add specificity at lower levels:
  • Tenant: Language, basic validation rules
  • Catalog: Default content type
  • Label: Branding, genre preferences
  • Artist: Specific contributors, copyright
  • User: Personal workflow preferences

​
2. Use Templates for Reusable Patterns

Create templates for common configurations:
  • Genre-specific settings (Hip-Hop Album, Rock Single, etc.)
  • Release type patterns (Deluxe Edition, Remastered, Live)
  • Territory-specific configurations

​
3. Preview Before Committing

Always use preview endpoints to verify:
  • Default inheritance is working as expected
  • No unintended overwrites
  • All required fields will be populated

​
4. Document Your Template Library

Add clear descriptions and tags to templates: 
{
  "name": "Explicit Hip-Hop Album",
  "description": "Standard explicit hip-hop album with advisory labeling",
  "tags": ["hip-hop", "explicit", "album", "parental-advisory"],
  "isPublic": true
}

​
5. Regularly Audit Settings

Periodically review and clean up:
  • Inactive settings that should be deleted
  • Outdated configuration values
  • Unused templates

​
6. Consider Settings Succession

For time-based changes (e.g., label rebranding), create new settings with higher priority rather than modifying existing ones. This maintains audit trails.

​
Integration with Catalog Creation

Default settings automatically integrate with catalog creation workflows:

​
Asset Creation

POST /asset
{
  "assetName": "New Track",
  "artistId": "660e8400-e29b-41d4-a716-446655440001",
  "duration": 180
  // Defaults are automatically applied during creation
}

​
Product Creation

POST /product
{
  "productName": "New Album",
  "labelId": "550e8400-e29b-41d4-a716-446655440000",
  "releaseDate": "2024-12-01"
  // Label defaults + tenant defaults are merged
}

​
Release Creation

POST /releases
{
  "title": "New Release",
  "artistId": "660e8400-e29b-41d4-a716-446655440001"
  // Full inheritance chain is applied
}

​
Error Handling

​
Common Errors

409 Conflict - Duplicate Setting: 
{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "A default setting for this entity and category already exists"
  }
}
Solution: Use PUT to update the existing setting instead. 404 Not Found - Entity Doesn’t Exist: 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Artist with ID 660e8400-... not found"
  }
}
Solution: Verify the entity exists before creating settings. 400 Bad Request - Invalid Category: 
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid category. Must be one of: content, business, ddex, validation"
  }
}

​
API Reference

For complete endpoint documentation, see:

​
Default Settings Management

Retrieving Settings: Creating Settings: Updating Settings: Deleting Settings: Other Operations:

​
Template Management

​
Preview & Testing

​
Support

For questions or issues with Default Settings: