> ## 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.

# Default Settings

> Learn how to use the Default Settings system to streamline catalog management with hierarchical configuration inheritance

## 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:

```text theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
GET /defaultsettings/artist/{artistId}
POST /defaultsettings/label/{labelId}
PUT /defaultsettings/artist/{artistId}/{settingId}
DELETE /defaultsettings/user/{userId}/{settingId}
```

<Note>
  **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.
</Note>

## 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```bash theme={null}
POST /defaultsettings/tenant
```

```json theme={null}
{
  "category": "content",
  "settings": {
    "content": {
      "language": "en",
      "type": "Audio"
    }
  }
}
```

### Step 2: Create Label-Specific Overrides

Customize settings for specific labels:

```bash theme={null}
POST /defaultsettings/label/{labelId}
```

```json theme={null}
{
  "category": "content",
  "settings": {
    "content": {
      "format": "Album",
      "mainGenre": ["Electronic", "Dance"]
    }
  }
}
```

### Step 3: Preview Before Creating Items

Test how defaults will apply to a new product:

```bash theme={null}
POST /defaultsettings/preview/product
```

```json theme={null}
{
  "labelId": "550e8400-e29b-41d4-a716-446655440000",
  "productData": {
    "productName": "New Album",
    "releaseDate": "2024-12-01"
  }
}
```

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
POST /defaultsettings/templates
```

```json theme={null}
{
  "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:

```bash theme={null}
POST /defaultsettings/templates/{templateId}/apply
```

```json theme={null}
{
  "entityType": "artist",
  "entityId": "660e8400-e29b-41d4-a716-446655440001"
}
```

### Updating a Template

Modify an existing template (only the creator can update):

```bash theme={null}
PUT /defaultsettings/templates/{templateId}
```

```json theme={null}
{
  "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):

```bash theme={null}
DELETE /defaultsettings/templates/{templateId}
```

<Warning>
  Deleting a template does not affect default settings that were created from it. Those settings remain intact.
</Warning>

### Browsing Popular Templates

Discover frequently used templates:

```bash theme={null}
GET /defaultsettings/templates/popular?limit=10
```

### Searching Templates

Find templates by tags or search terms:

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
POST /defaultsettings/preview/resolve
```

```json theme={null}
{
  "labelId": "550e8400-e29b-41d4-a716-446655440000",
  "artistId": "660e8400-e29b-41d4-a716-446655440001",
  "targetType": "release"
}
```

**Response shows the complete resolution chain:**

```json theme={null}
{
  "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:**

```bash theme={null}
POST /defaultsettings/preview/asset
{
  "artistId": "660e8400-e29b-41d4-a716-446655440001",
  "assetData": {
    "assetName": "New Track",
    "duration": 180
  }
}
```

**Products:**

```bash theme={null}
POST /defaultsettings/preview/product
{
  "labelId": "550e8400-e29b-41d4-a716-446655440000",
  "productData": {
    "productName": "New Album"
  }
}
```

**Releases:**

```bash theme={null}
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:**

```bash theme={null}
GET /defaultsettings/tenant
GET /defaultsettings/catalog
```

**For label, artist, or user level:**

```bash theme={null}
GET /defaultsettings/{entityType}/{entityId}

# Examples:
GET /defaultsettings/artist/{artistId}
GET /defaultsettings/label/{labelId}
GET /defaultsettings/user/{userId}
```

**Filter by category:**

```bash theme={null}
GET /defaultsettings/artist/{artistId}?category=content
GET /defaultsettings/tenant?category=business
```

**Include inactive settings:**

```bash theme={null}
GET /defaultsettings/label/{labelId}?includeInactive=true
GET /defaultsettings/catalog?includeInactive=true
```

**Get a single setting by ID:**

```bash theme={null}
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:**

```bash theme={null}
PUT /defaultsettings/tenant/{settingId}
PUT /defaultsettings/catalog/{settingId}
```

**For label, artist, or user level:**

```bash theme={null}
PUT /defaultsettings/{entityType}/{entityId}/{settingId}

# Examples:
PUT /defaultsettings/artist/{artistId}/{settingId}
PUT /defaultsettings/label/{labelId}/{settingId}
PUT /defaultsettings/user/{userId}/{settingId}
```

**Example request body:**

```json theme={null}
{
  "settings": {
    "content": {
      "explicit": "clean",
      "version": "Radio Edit"
    }
  }
}
```

**Deactivate without deleting:**

```bash theme={null}
PUT /defaultsettings/artist/{artistId}/{settingId}
```

```json theme={null}
{
  "isActive": false
}
```

### Deleting Settings

Permanently remove a setting. Use the appropriate endpoint pattern based on entity type:

**For tenant or catalog level:**

```bash theme={null}
DELETE /defaultsettings/tenant/{settingId}
DELETE /defaultsettings/catalog/{settingId}
```

**For label, artist, or user level:**

```bash theme={null}
DELETE /defaultsettings/{entityType}/{entityId}/{settingId}

# Examples:
DELETE /defaultsettings/artist/{artistId}/{settingId}
DELETE /defaultsettings/label/{labelId}/{settingId}
DELETE /defaultsettings/user/{userId}/{settingId}
```

<Warning>
  Deletion is permanent and cannot be undone. Consider using `isActive: false` to temporarily deactivate settings instead.
</Warning>

## Priority System

By default, all settings at the same level have equal priority (0). You can adjust priority for conflict resolution:

```bash theme={null}
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:

```json theme={null}
{
  "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

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

### Product Creation

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

### Release Creation

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

## Error Handling

### Common Errors

**409 Conflict - Duplicate Setting:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

* [Get Default Settings (Tenant/Catalog)](/api-reference/default-settings/get-defaultsettings-id) - For tenant and catalog level
* [Get Default Settings (Entity-Specific)](/api-reference/default-settings/get-defaultsettings-id-id) - For label, artist, and user
* [Get Default Setting by ID](/api-reference/default-settings/get-defaultsettings-settings-id) - Get any setting by its unique ID

**Creating Settings:**

* [Create Default Setting (Tenant/Catalog)](/api-reference/default-settings/post-defaultsettings-id) - For tenant and catalog level
* [Create Default Setting (Entity-Specific)](/api-reference/default-settings/post-defaultsettings-id-id) - For label, artist, and user

**Updating Settings:**

* [Update Default Setting (Tenant/Catalog)](/api-reference/default-settings/put-defaultsettings-id-id) - For tenant and catalog level
* [Update Default Setting (Entity-Specific)](/api-reference/default-settings/put-defaultsettings-id-id-id) - For label, artist, and user

**Deleting Settings:**

* [Delete Default Setting (Tenant/Catalog)](/api-reference/default-settings/delete-defaultsettings-id-id) - For tenant and catalog level
* [Delete Default Setting (Entity-Specific)](/api-reference/default-settings/delete-defaultsettings-id-id-id) - For label, artist, and user

**Other Operations:**

* [Clone Settings](/api-reference/default-settings/post-defaultsettings-clone) - Copy settings between entities

### Template Management

* [Get Templates](/api-reference/default-settings/get-defaultsettings-templates)
* [Get Popular Templates](/api-reference/default-settings/get-defaultsettings-templates-popular)
* [Create Template](/api-reference/default-settings/post-defaultsettings-templates)
* [Update Template](/api-reference/default-settings/put-defaultsettings-templates-id)
* [Delete Template](/api-reference/default-settings/delete-defaultsettings-templates-id)
* [Apply Template](/api-reference/default-settings/post-defaultsettings-templates-id-apply)

### Preview & Testing

* [Preview Resolution](/api-reference/default-settings/post-defaultsettings-preview-resolve)
* [Preview Asset Defaults](/api-reference/default-settings/post-defaultsettings-preview-asset)
* [Preview Product Defaults](/api-reference/default-settings/post-defaultsettings-preview-product)
* [Preview Release Defaults](/api-reference/default-settings/post-defaultsettings-preview-release)

## Support

For questions or issues with Default Settings:

* Email: [support@royalti.io](mailto:support@royalti.io)