> ## 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. # API Changelog > Track changes and updates to the Royalti.io API > [!NOTE] > > This changelog tracks all changes to the Royalti.io API. Entries are organized by release date, with newest changes first. **2026-07-14** Documentation refresh ## Documentation ### API reference expanded Published reference coverage for previously undocumented modules: the Publishing & CWR cluster (publishers, works, writers, publisher-writer agreements, claims), catalog import/export, the statements lifecycle, billing, currencies, white-label domains/branding, and the newer saved-views + royalty analytics endpoints. **2026-07-07** Statements API — recoupment & PDF generation ## Improvements ### Recoupment tracking, balance carry-forward, and downloadable PDF statements The accounting engine underneath the statements API now tracks recoupment against advances and carries unrecouped balances forward automatically, and can generate downloadable PDF royalty statements per artist or writer. * Revenue, expense, and dues ledgers, plus a payments view of what's owed and what's been paid * Automatic recoupment tracking, with unrecouped balances carried forward period to period * PDF statement generation with a per-split breakdown * Statement-ready notifications Some statement features require the `publisher` add-on. [Statements API reference](/api-reference/statements/get-statements.md) **2026-07-06** Publishing API — search, pagination, and setup improvements ## Improvements ### Search, pagination, and MusicBrainz-assisted setup on Publishing endpoints A round of usability fixes to the Publishing module's list and setup endpoints, based on real usage since launch. * Analytics filters on publishing endpoints for narrowing by date, work, or writer * Pagination added to the claims-inbox endpoint for large catalogs * Search and facet filters added to the writer and work list endpoints (e.g. `GET /writer/writers` now takes `search`, `affiliatedPRO`, and `writerRole`) * Reconciliation now accepts manual statement adjustment entries * The setup wizard can pull known work/writer data from MusicBrainz during onboarding Applies automatically to accounts on the `publisher` add-on. **2026-07-04** Catalog Import API — pull existing catalog from provider accounts ## New Features ### Catalog import from connected DSP/streaming provider accounts A new catalog importer connects to your existing DSP/streaming provider accounts and stages matching catalog metadata for review before anything goes live. * Search connected provider accounts and pull in matching tracks, releases, and metadata * Fetch jobs run asynchronously so large catalogs don't block other work * Imported items land in a staging area — nothing touches your live catalog until you confirm * Already-imported items are recognized and skipped on re-run Requires admin access. **2026-07-02** Catalog Export API — branded PDF/Excel + new templates ## New Features ### Branded, white-label exports for reports and catalog data Analytics and catalog exports can now carry your own branding, and catalog export gained new templates. * Analytics exports (PDF/Excel) carry your label's letterhead, logo, and chart colors * Per-card export pulls a single chart or table without generating a full report * New catalog export templates for labels, splits, and releases Requires a plan with white-label/aggregates access. **2026-06-26** API v2.6.5 — patch ## New Features ### AI Release Builder — media upload (cover art / audio / documents) The Guided Release Builder now includes a dedicated media collection step between draft creation and correctness checks. The builder suspends and prompts you to upload files before validation runs — closing the gap that previously made artwork-missing a permanent blocker. **What's new:** * **Cover art upload via chat** — attach a JPEG or PNG directly in the Ask Roy widget; it attaches to the draft immediately. Cover art is required to pass submission checks. A cover that is at least 1500×1500 px is automatically **upscaled to 3000×3000** to meet the delivery minimum; smaller images are flagged. * **Per-track audio** — attach audio files one at a time; Roy shows a track picker so each file goes to the right track. Duration and bitrate are read from the file automatically. * **PDF release documents** — any PDF you attach is added as a release document. * After attaching files, say **"done"** (or send `{ confirm: true }` via REST) to move on to validation and review. Media attaches through the standard release-media endpoints — `POST /releases/:id/media/files` (cover art + documents) and `POST /releases/:id/tracks/:trackId/media/file` (audio) — so the builder uses the same upload path as the rest of the app. **Builder workflow (updated):** ``` Start build → create draft → SUSPEND: upload media (cover art required + audio/docs optional) → user: "done" → resume { confirm: true } → validate (artwork-missing check clears) → SUSPEND: review findings → user confirms → submit → under_review ✓ ``` [Guided Release Builder guide — media step](/guides/release-management.md#upload-cover-art-audio-and-documents) > [!NOTE] > > This update does not change the royalty file upload path. Builder media uploads reuse the existing release-media endpoints and have no effect on royalty processing. **2026-06-26** API v2.6.5 ## New Features ### Guided Release Builder (Ask Roy) Ask Roy can now guide you through creating a release end-to-end — gathering metadata, running pre-submission correctness checks, surfacing any issues, and submitting it for review once you confirm. It's available conversationally in Ask Roy and as a REST API for integrations and automation. **New Endpoints:** | Endpoint | Description | | - | - | | **POST** `/ai/release-builder` | Start a guided build — creates a draft, runs the checks, and returns findings (the run **suspends** for your review) | | **POST** `/ai/release-builder/{runId}/resume` | Confirm with `{ "confirm": true }` — submits the release when no blocking issues remain, otherwise it stays a draft | **Pre-submission correctness checks:** * **Metadata completeness** — release date, main genre, explicit flag, language, copyright * **ISRC / UPC** — format validity + duplicate detection across your catalog * **Artwork & delivery readiness** — cover art (≥ 3000×3000) and DDEX/DSP territories * **Split coverage** — splits total 100% per track **Example:** ```json theme={null} // POST /ai/release-builder → { status, message, data } { "status": "success", "message": "Release builder started", "data": { "runId": "…", "status": "suspended", "suspendPayload": { "releaseId": "…", "blocking": true, "findings": [ { "rule": "release-date-required", "severity": "block", "field": "releaseDate" } ] } } } ``` [Guided Release Builder guide](/guides/release-management.md) > [!NOTE] > > AI routes are served at `https://api.royalti.io/ai/...` (not `/api/ai`). The guided builder requires AI to be enabled for your workspace. **2026-06-24** Royalty analytics — compare mode, saved views, unified view ## Improvements ### Compare mode, saved views, and a unified royalty analytics view The royalty analytics surface was rebuilt with a flexible period selector, side-by-side comparisons, saved views, and a single consolidated view across master, publishing, and neighbouring-rights royalties. * Flexible period selector with an uncapped all-time chart * Compare mode to line up two periods, sources, or catalogs * Saved views for reusable filter/date-range combinations * A consolidated royalty view spanning master, publishing, and neighbouring rights Requires admin-level account access. [Royalty analytics API reference](/api-reference/royalties/get-royalty.md) **2026-06-13** Webhooks — release & DDEX delivery lifecycle events ## New Features ### Webhooks for release & delivery events Subscribe to release and DDEX delivery lifecycle events instead of polling the API. * Subscribe to release and DDEX delivery events (submitted, delivered, failed, and more) * Configure and manage webhook endpoints from Settings → API & Developer * Near-real-time delivery instead of polling * A reliability fix shipped July 6 resolved a case where some events weren't being delivered [Webhook integration guide](/guides/webhook-integration.md) **2026-05-31** Publishing API — works, writers, registrations, DMP import, PRO connect ## New Features ### Publishing module: works, writers, registrations, DMP import & PRO connect A full publishing surface for managing works, writers, and PRO registrations against your catalog, instead of spreadsheets or a separate tool. * Create and link works to recordings, with writer and share detail * Register works with PROs through a guided CWR workflow * Import existing publishing data from Django Music Publisher instead of re-entering it * Connect your tenant to the PROs you work with * A guided bootstrap wizard gets a catalog publishing-ready from a blank state Available under the `publisher` add-on. Reference documentation for the writers, works, and publisher-writer agreement endpoints is part of this docs refresh. **2026-05-29** DDEX — ERN 4.3, takedown/re-deliver, JosPlay ## Improvements ### Broader ERN coverage, takedown/re-deliver, and JosPlay Delivery now supports takedown and re-delivery actions, the ERN 4.3 message format, and JosPlay as an additional aggregator destination. * Takedown and re-deliver actions available directly via the delivery API, no support ticket needed * Upgraded ERN messaging from 4.2 to 4.3 for wider DSP/aggregator compatibility * JosPlay added as a supported aggregator delivery destination Applies going forward for anything delivered next; existing deliveries are unaffected. Requires the DDEX & Deliveries add-on. [DDEX API reference](/api-reference/ddex/post-ddex-ern-generate.md) | [DDEX integration guide](/guides/ddex-integration.md) **2026-05-28** Delivery API — readiness checklist and bulk retry ## New Features ### Delivery readiness checklist and bulk retry New readiness and retry endpoints surface exactly what's blocking a release from delivering, and let you re-attempt multiple failed deliveries in one call. * Readiness checklist flags missing metadata, artwork, rights info, and more before you attempt delivery * Bulk retry re-attempts multiple failed deliveries in a single request * Powers both the dashboard checklist and the bulk-retry action Requires the DDEX & Deliveries add-on. [Product delivery guide](/guides/product-delivery) **2026-05-18** Merlin API — pool-report approvals & invoice reconciliation ## New Features ### Merlin neighbouring rights: pool-report approvals and invoice reconciliation The Merlin add-on brings neighbouring-rights pool-report approval and invoice reconciliation into the API, so you can track and verify neighbouring-rights income programmatically. * Pool-report cluster approval, bulk or individual * Invoice scanner matches incoming Merlin invoices against expected payouts * Paid-status reconciliation flags invoices as paid, unpaid, or mismatched * Full invoice history available via the Invoices API Requires the Merlin add-on. [Merlin API reference](/api-reference/merlin/get-merlin-history.md) | [Merlin add-on guide](/guides/merlin-addon) | [Merlin webhooks guide](/guides/merlin-webhooks) **2026-05-06** Publishing claims API ## New Features ### Claims & disputes inbox for publishing A dedicated claims and disputes surface for reviewing, resolving, and documenting publishing claims against your catalog. * Lists every open claim or dispute tied to your catalog * Bulk resolve for closing out multiple claims at once * Evidence attachment on a dispute * Dispute state tracking (open, under review, resolved) Requires the `publisher` add-on. Reference documentation for the publishing-claims endpoints is part of this docs refresh. **2026-05-06** Publisher statements — reconciliation & payout tracking ## New Features ### Publishing statement reconciliation & payouts Match incoming publishing statements against registered works and writer splits, and track payout status without leaving the API. * Match statements against registered works and writer splits * Surface mismatches where expected shares don't match what's reported * Track payout status per writer and per work * Drill into any statement line for the underlying work/writer breakdown Requires the `publisher` add-on. **2026-04-30** DDEX/FUGA delivery — onboarding, CSV import, FLAC/WAV packaging fixes ## Improvements ### DDEX & FUGA delivery pipeline rebuild The DDEX/FUGA delivery workflow got a full rebuild — guided onboarding, centralized delivery preferences, CSV catalog import with preview, a remote-folder browser, one-click retry-all, plus backend fixes for FLAC/WAV packaging and editable delivery metadata. * Guided onboarding for connecting DDEX/FUGA delivery * Centralized, per-label delivery preferences * CSV import with live preview for bulk catalog loading before delivery * Remote-folder browser for picking source files from connected storage * Retry-all re-sends every failed delivery in one action * Backend fixes for FLAC/WAV packaging and editable delivery metadata Existing delivery configurations carry over automatically. Requires the DDEX & Deliveries add-on. [FUGA integration guide](/guides/fuga-integration.md) | [FUGA delivery API reference](/api-reference/fuga-delivery/batch-product-delivery.md) **2026-04-23** Splits API — time-based conditions ## New Features ### Time-based royalty splits The splits API now supports time-based conditions, so ownership and payout percentages can change automatically at a set date — a buyout, a contract renewal, a rights reversion. * Temporal-succession splits: define who gets paid what before and after a given date * Split fields for physical-sale-specific royalties on catalogs with physical distribution * A rebuilt 1:1 conditions model for clearer, more reliable split configuration [Splits API reference](/api-reference/splits/post-split.md) | [Splits management guide](/guides/splits-management.md) **2026-04-09** Royalty processing — per-source fees, multi-currency routing, duplicate detection ## Improvements ### Per-source fees, multi-currency routing, and duplicate detection Royalty processing now applies a fee rate and currency per source automatically, and flags duplicate or malformed files before they can skew your numbers. * Fee rate and currency configurable per royalty source, applied automatically during processing * Multi-currency routing sends mixed-currency statement lines to the right place without manual conversion * Format and duplicate detection catches re-uploaded or malformed files before they land in your totals * The Source Creator wizard now guides setup with a data-class picker, column mapping, and automatic decimal-format detection Existing sources keep working; detection runs automatically on future uploads. [Royalty sources API reference](/api-reference/sources/get-sources.md) **2026-04-06** Currency & billing — exchange rate management ## New Features ### Exchange rate management Import historical exchange-rate data in bulk, pull live rates, and look up the exact rate used for a specific statement period. * Bulk import of historical exchange-rate data * Live exchange rates on demand * Date-picker lookup for the rate used on any given statement period Reference documentation for the currency and billing endpoints is part of this docs refresh. **2026-03-15** Ask Roy / MCP — query your real catalog and royalty data ## New Features ### Ask Roy: query your real catalog and royalty data Ask Roy answers using your actual catalog, royalty, and release data instead of generic guidance, and walks through common workflows step by step. It's available conversationally in the dashboard, and programmatically via MCP for integrations and automation. * Natural-language questions about earnings, releases, splits, or catalog status, answered from your own account data * Guided, step-by-step help for common workflows * Upload a royalty statement or sales file and Roy auto-detects the format before you map anything [MCP integration guide](/introduction/ai-integration.md) **2025-12-10** API v2.6.4 ## New Features ### Summary Endpoints Added 8 new summary endpoints that return aggregated statistics for key entities. All endpoints support role-based scoping where admins/owners see tenant-wide data, and regular users see only their associated data. **New Endpoints:** | Endpoint | Description | | - | - | | **GET** `/product/summary` | Total products, counts by status/format/type, revenue from ProductStats | | **GET** `/asset/summary` | Total assets, counts by type/explicit, revenue from AssetStats | | **GET** `/artist/summary` | Total artists, counts by label, revenue from ArtistStats | | **GET** `/user/summary` | Total users, counts by role/status, accounting totals | | **GET** `/split/summary` | Total splits, counts by type/level, conditional splits breakdown | | **GET** `/payment/summary` | Total payments, counts by status/currency, total amounts | | **GET** `/expense/summary` | Total expenses, counts by type/expenseableType, total amounts | | **GET** `/revenue/summary` | Total revenues, counts by type, total amounts | **Example Response (Product Summary):** ```json theme={null} { "message": "success", "summary": { "total": 150, "byStatus": { "Live": 120, "Taken Down": 15, "Scheduled": 10, "Pending": 5 }, "byFormat": { "Single": 80, "EP": 45, "Album": 25 }, "byType": { "Audio": 140, "Video": 10 }, "revenue": { "totalCount": 5000000, "totalRoyalty": 45000.50 } } } ``` **Key Features:** * **Role-based scoping**: Regular users see only data for their associated artists * **Parallel aggregation**: All queries run concurrently for optimal performance * **Consistent format**: All endpoints return `{ message, summary }` structure [View Product Summary API](/api-reference/product/get-product-summary.md) | [View Asset Summary API](/api-reference/asset/get-asset-summary.md) > [!NOTE] > > These summary endpoints are ideal for dashboard widgets and analytics displays where you need aggregated counts without fetching full entity lists. **2025-11-23** API v2.6.3 ## New Features ### Royalty Source Filtering Enhancement Added optional `includeAll` query parameter to `GET /file/sources` for more secure and precise source filtering. **Parameter Details:** * **Name**: `includeAll` * **Type**: String enum (`"true"` | `"false"`) * **Default**: `"true"` (maintains backward compatibility) * **Location**: Query parameter **Behavior:** * `includeAll=true` (default): Returns all active public sources (backward compatible) * `includeAll=false`: Returns only tenant-associated sources (more secure, filters to sources your organization has configured) **Use Case:** Filter royalty sources to show only those relevant to your organization, improving security and user experience. **Example:** ```javascript theme={null} // Get only your tenant's configured sources const response = await fetch('https://api.royalti.io/file/sources?includeAll=false', { headers: { 'Authorization': `Bearer ${token}` } }); ``` [View GET /file/sources API Reference](/api-reference/file/get-file-sources.md) ## Security Improvements ### Pattern Creator Admin Authentication All `/pattern-creator/*` routes now require admin authentication via `enhancedGodminAuth` middleware. **Impact:** * Non-admin users can no longer access pattern creator endpoints * Pattern creator is now properly secured as an admin-only feature **Reason:** Pattern creator is an administrative tool for managing source configurations and should only be accessible to system administrators. ## Deprecated Endpoints ### Pattern Creator Sources Endpoint Removed **Removed:** `GET /pattern-creator/sources` **Status**: Endpoint has been removed from the codebase **Replacement**: Use `GET /sources/admin` instead for admin-level source management **Reason**: This endpoint was redundant with `/sources/admin` and has been consolidated to reduce code duplication and improve maintainability. **Migration Guide:** ```diff theme={null} - // Old approach - const sources = await fetch('/pattern-creator/sources'); + // New approach + const sources = await fetch('/sources/admin'); ``` **Breaking Change**: Yes - API calls to `/pattern-creator/sources` will return 404 Not Found > [!WARNING] > > If you were using `GET /pattern-creator/sources`, migrate to `GET /sources/admin` immediately. The old endpoint has been removed. ## Improvements * Reduced code duplication by 70% through introduction of shared `RoyaltySourceService` * Enhanced service layer architecture for better maintainability * Improved Swagger documentation accuracy across all source-related endpoints * Updated integration guides with new parameter documentation > [!NOTE] > > The `includeAll` parameter addition is fully backward-compatible. Existing API clients will continue to work without changes, receiving all active sources by default. **2025-11-06** Documentation v2.6.2 ## New Documentation ### Default Settings API Comprehensive documentation added for the Default Settings system - a powerful hierarchical configuration management feature for catalog items. **New API Reference Pages (16 endpoints):** *Default Settings Management:* * **GET** `/defaultsettings/{entityType}/{entityId}` - Retrieve default settings * **GET** `/defaultsettings/settings/{settingId}` - Get single setting by ID * **POST** `/defaultsettings/{entityType}/{entityId}` - Create default settings * **PUT** `/defaultsettings/{entityType}/{entityId}/{settingId}` - Update default settings * **DELETE** `/defaultsettings/{entityType}/{entityId}/{settingId}` - Delete default settings * **POST** `/defaultsettings/clone` - Clone settings between entities *Template Management:* * **GET** `/defaultsettings/templates` - Browse reusable templates * **GET** `/defaultsettings/templates/popular` - Get most-used templates * **POST** `/defaultsettings/templates` - Create configuration templates * **PUT** `/defaultsettings/templates/{templateId}` - Update template * **DELETE** `/defaultsettings/templates/{templateId}` - Delete template * **POST** `/defaultsettings/templates/{templateId}/apply` - Apply template to entity *Preview & Testing:* * **POST** `/defaultsettings/preview/resolve` - Preview inheritance chain * **POST** `/defaultsettings/preview/asset` - Preview asset defaults * **POST** `/defaultsettings/preview/product` - Preview product defaults * **POST** `/defaultsettings/preview/release` - Preview release defaults **New Integration Guide:** Added comprehensive [Default Settings Guide](/guides/default-settings.md) covering: * Hierarchical inheritance chain (User → Artist → Label → Catalog → Tenant) * Four settings categories: Content, Business, DDEX, and Validation * Template system for reusable configurations * Preview endpoints for testing before applying * Advanced use cases and best practices * Complete code examples in Node.js, Python, and cURL **Key Features Documented:** * **Inheritance Chain**: Settings cascade from tenant-wide defaults down to user-specific overrides * **Categories**: Organize settings by content metadata, business info, DDEX configuration, and validation rules * **Templates**: Create and share reusable configuration presets * **Preview System**: Test how defaults will be applied without modifying data * **Clone Operation**: Duplicate settings between entities for consistency [Explore Default Settings API](/api-reference/default-settings/get-defaultsettings-id-id.md) | [Read Integration Guide](/guides/default-settings.md) > [!NOTE] > > The Default Settings feature has been available since v2.6.0 but was previously undocumented. This release makes the full API specification available to all developers. **2025-11-04** API v2.6.1 ## New Features ### Webhook Delivery System Send real-time event notifications to your external systems with our new webhook infrastructure. * Configure webhook endpoints per workspace with custom headers and authentication * Automatic retry with exponential backoff for failed deliveries * Monitor webhook health and delivery status in real-time * Secure webhook delivery with signature verification and rate limiting * Support for multiple event types: payments, royalty processing, asset changes, releases, and billing events [View Webhook Integration Guide](/guides/webhook-integration.md) ### Enhanced Notification System Stay informed with improved multi-channel notifications across your workspace. * Multi-channel notification support (email, SMS, push, in-app) * Customizable notification templates for different event types * User-level notification preferences * Real-time event routing and delivery ## Improvements * Enhanced webhook delivery retry logic for better reliability * Improved notification routing performance * Better error handling and status reporting for webhook endpoints * Updated integration guides with webhook examples > [!NOTE] > > This release is fully backward-compatible with v2.6.0. No breaking changes. **2025-11-03** API v2.6.0 ## New Endpoints * **GET** `/accounting/{id}/stats` - Get detailed accounting statistics * **POST** `/ddex/ern/generate` - Generate ERN messages for digital distribution * **GET** `/royalties/analytics/artist` - Advanced artist revenue analytics ## Breaking Changes > [!WARNING] > > The `/artist/{id}` endpoint now requires the `includeStats` query parameter to return statistics. Previously this was included by default. > > **Migration**: Add `?includeStats=true` to your API calls if you need statistics data. ## Improvements * Enhanced error messages for validation failures * Improved performance for bulk operations (up to 50% faster) * Better caching strategies for frequently accessed data * Added pagination support to all list endpoints ## Bug Fixes * Fixed issue with split calculations not totaling 100% in edge cases * Resolved timezone handling for international date fields * Corrected DDEX message validation for special characters **2025-10-15** API v2.5.2 ## Improvements * Optimized database queries for artist and asset endpoints * Enhanced webhook delivery retry logic * Improved file upload validation ## Bug Fixes * Fixed duplicate entries in royalty processing * Resolved authentication token refresh issues * Corrected calculation errors in temporal splits **2025-09-28** API v2.5.0 ## New Endpoints * **POST** `/splits/validate` - Validate split configurations before saving * **GET** `/releases/{id}/analytics` - Get release performance metrics * **POST** `/notifications/preferences` - Configure notification settings ## Improvements * Added multi-currency support for payments * Enhanced DDEX provider configuration options * Improved royalty file pattern recognition ## Bug Fixes * Fixed edge case in split succession calculations * Resolved issues with large file uploads (>100MB) * Corrected artist merge functionality **2025-08-12** API v2.4.0 ## New Endpoints * **GET** `/accounting/transactions/summary` - Get transaction summaries * **POST** `/artist/bulk` - Create artists in bulk * **GET** `/revenue/analytics/country` - Geographic revenue breakdown ## Improvements * Added BigQuery integration for advanced analytics * Enhanced file processing queue performance * Improved error handling across all endpoints This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.