Royalti api

Skill Royalti-io/royalti-api-skill/skills/royalti-api

Royalti.io REST API v2.6 Agent Skill — install in Claude Code, Cursor, Codex CLI, or any Agent Skills compatible tool

Install

npx -y skills add Royalti-io/royalti-api-skill --skill royalti-api

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Royalti.io REST API v2.6 pattern reference for developers. Covers authentication, CRUD patterns, pagination, error handling, webhooks, WebSocket events, data models, DDEX distribution, AI chat, source creator, global search, checklist workflows, music publishing, billing, and more. Use when helping developers integrate with the Royalti API (api.royalti.io) or when writing integration code, API documentation, or troubleshooting API issues.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

57.1 KB, as published. Nobody here has run it

Royalti API v2.6 — Developer Reference

Pattern reference for integrating with the Royalti.io REST API.

Base URL: https://api.royalti.io Current Version: 2.6.4 Architecture: Multi-tenant (workspace-scoped)

1. Authentication

Token Types

Token	Prefix	Expiry	Use Case
JWT Access Token	—	6 hours	All API requests
JWT Refresh Token	—	1 day	Obtain new access tokens
Workspace API Key	`RWAK`	Never (revocable)	Programmatic workspace access
User API Key	`RUAK`	Never (revocable)	Programmatic user access

Two-Step JWT Login

# Step 1: Login — returns refresh token + workspace list
curl -X POST https://api.royalti.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "password": "secret" }'

# Response:
# {
#   "refresh_token": "eyJ...",
#   "workspaces": [{ "id": "ws_abc", "name": "My Label", ... }]
# }

# Step 2: Exchange refresh token for access token (scoped to a workspace)
curl https://api.royalti.io/auth/authtoken?currentWorkspace=ws_abc \
  -H "Authorization: Bearer <refresh_token>"

# Response:
# { "data": { "access_token": "eyJ..." } }

Using the Access Token

All subsequent requests include the access token:

curl https://api.royalti.io/artist/ \
  -H "Authorization: Bearer <access_token>"

API Key Authentication

API keys can be used instead of JWT tokens. Pass them in the Authorization header:

# Workspace API key
curl https://api.royalti.io/artist/ \
  -H "Authorization: Bearer RWAK_abc123..."

# User API key
curl https://api.royalti.io/asset \
  -H "Authorization: Bearer RUAK_def456..."

API Key Auth Resolution (Internals)

Understanding how RWAK/RUAK keys resolve to a workspace context helps debug auth errors:

1. Token prefix detected as RWAK/RUAK (not JWT)
2. ApiKeys table lookup → finds TenantId
3. Tenants table lookup → finds workspace (must be status='active')
4. Tenants.user field → used to find the owner TenantUser via TenantUser.findByPk()
5. Owner TenantUser populates req.user for all downstream handlers

Key detail: Tenants.user must store a TenantUser.id (UUID), NOT a User.id. These are different tables with different PKs. If this field is wrong, the API returns "Workspace user not found" (HTTP 404) despite the API key being valid.

The Tenants.user field is also used by:

Accounting endpoints — to exclude the workspace owner from payee/due calculations
Admin auth — to resolve workspace context for admin JWT tokens

Other Auth Methods

Endpoint	Method	Purpose
`POST /auth/loginlink`	POST	Magic link login
`POST /auth/forgotpassword`	POST	Request password reset
`PATCH /auth/resetpassword?code=CODE`	PATCH	Apply password reset
`GET /auth/google`	GET	Google OAuth
`GET /auth/linkedin`	GET	LinkedIn OAuth
`GET /auth/facebook`	GET	Facebook OAuth

Rate Limiting

Login endpoint: 20 requests per 3 minutes per IP
AI endpoints: Rate limited per tenant subscription tier (billing-period aligned)
Other endpoints: No documented limits (subject to fair use)

RBAC Roles (ascending privilege)

guest < user < admin < owner < super_admin < main_super_admin

Feature Gating

Certain API features require subscription-level feature flags:

Feature Flag	Required For
`royaltyAccess`	Royalty file upload, source creator, analytics
`aiAgent`	AI chat conversations and messages
`addonsAccess`	DDEX, Merlin, Publisher addons

Addon-specific checks: ddex, publisher, merlin — require the addon to be enabled on the tenant.

2. Request Patterns

Standard Headers

Authorization: Bearer <access_token | API_KEY>
Content-Type: application/json

Pagination (all list endpoints)

Param	Default	Description
`page`	`1`	Page number
`size`	`10`–`20`	Items per page (max `100`)
`sort`	`updatedAt`	Sort field
`order`	`desc`	`asc` or `desc`

GET /artist/?page=2&size=25&sort=artistName&order=asc

Filtering (analytics endpoints)

Param	Type	Description
`start`	`YYYY-MM-DD`	Date range start
`end`	`YYYY-MM-DD`	Date range end
`dsp`	CSV string	Filter by DSP/platform
`country`	CSV string	Filter by territory (ISO 3166-1 alpha-2)
`artists`	CSV string	Filter by artist IDs
`upc`	CSV string	Filter by UPC
`isrc`	CSV string	Filter by ISRC
`aggregator`	CSV string	Filter by distributor
`type`	string	Filter by sale type
`periodFilterType`	`accounting` or `sale`	Date filtering mode
`includePreviousPeriod`	boolean	Include comparison data
`table_name`	string	Filter by royalty file source table

Search

Many list endpoints support a search query param for text-based filtering:

GET /artist/?search=drake&page=1&size=10

Bulk Operations

Most resources support bulk create and delete:

POST /artist/bulk          # Create multiple artists
DELETE /artist/bulk/delete  # Delete multiple artists
POST /asset/bulksplits     # Assign splits to multiple assets

3. Response Patterns

Success Response

{
  "status": "success",
  "message": "Operation successful",
  "data": { ... }
}

Paginated List Response

Response shapes vary by resource. Most use data[], but some use resource-specific keys:

// Standard shape (labels, splits, payments, expenses, revenue, notifications)
{
  "status": "success",
  "data": [ ... ],
  "totalItems": 142,
  "totalPages": 15,
  "currentPage": 1
}

// Users — uses "Users" key, no "status" field
{
  "message": "success",
  "totalItems": 10,
  "Users": [ ... ],
  "totalPages": 1,
  "currentPage": 1
}

// Artists — uses "Artists" key, includes "filteredItems"
{
  "totalItems": 50,
  "Artists": [ ... ],
  "totalPages": 5,
  "currentPage": 1,
  "filteredItems": 50
}

// Products — uses "Products" key
// Assets — uses "data" key

Tip: Always check for both data and the resource-specific key (e.g., Users, Artists, Products) when parsing list responses.

Summary Response (v2.6.4+)

Available on: /artist/summary, /asset/summary, /product/summary, /user/summary, /split/summary, /payment/summary, /expense/summary, /revenue/summary, /file/summary

{
  "message": "Summary retrieved successfully",
  "summary": {
    "total": 250,
    "byStatus": { "active": 200, "inactive": 50 },
    "byFormat": { "Single": 120, "Album": 80, "EP": 50 },
    "byType": { "Audio": 230, "Video": 20 },
    "revenue": { "total": 15000.50, "currency": "USD" }
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": ["optional", "array", "of", "details"]
  }
}

Common HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request / validation error
`401`	Unauthorized (missing or invalid token)
`403`	Forbidden (insufficient role/permissions)
`404`	Resource not found
`409`	Conflict (duplicate, schema disparity)
`422`	Unprocessable entity
`429`	Rate limited
`500`	Server error

4. Core Resources

All resources follow the same CRUD pattern unless noted. Every resource is workspace-scoped (multi-tenant).

Standard CRUD Pattern

GET    /{resource}/          # List (paginated)
POST   /{resource}/          # Create
GET    /{resource}/{id}      # Get by ID
PUT    /{resource}/{id}      # Update
DELETE /{resource}/{id}      # Delete
GET    /{resource}/summary   # Summary stats (v2.6.4+)
GET    /{resource}/download/csv  # CSV export
POST   /{resource}/bulk      # Bulk create
DELETE /{resource}/bulk/delete   # Bulk delete

Users (`/user/`)

Standard CRUD plus:

Endpoint	Description
`GET /user/{id}/stats`	User royalty statistics
`GET /user/{id}/monthly`	Monthly breakdown
`GET /user/{id}/artists`	User's artists
`GET /user/{id}/assets`	User's assets
`GET /user/{id}/products`	User's products
`GET /user/{id}/aut`	User accounting data
`GET /user/invites`	Pending invitations
`POST /user/invites/{id}/resend`	Resend invitation
`POST /user/invites/{id}/cancel`	Cancel invitation

Artists (`/artist/`)

Standard CRUD plus:

Endpoint	Description
`GET /artist/{id}/assets`	Artist's tracks
`GET /artist/{id}/products`	Artist's releases
`GET /artist/{id}/splits`	Artist's splits
`GET /artist/{id}/splits/{type}`	Splits by type
`PUT /artist/{id}/splits/{type}`	Update split by type
`DELETE /artist/{id}/splits/{type}`	Delete split by type
`POST /artist/{id}/splits`	Create artist default split
`GET /artist/{id}/stats`	Artist analytics
`POST /artist/{id}/merge`	Merge duplicate artists
`POST /artist/bulksplit`	Bulk assign splits
`POST /artist/download/csv`	Download artist CSV

Key fields: artistName, signDate, label, publisher, copyright, externalId, artistImg, links (spotify/youtube/instagram/etc.), genres, realName, pseudonyms

Assets / Tracks (`/asset`)

Standard CRUD plus:

Endpoint	Description
`GET /asset/{id}/artists`	Track's artists
`GET /asset/{id}/stats`	Track analytics
`POST /asset/{id}/setdefaultsplit`	Set default split
`GET /asset/{id}/media`	Track media files
`DELETE /asset/{id}/media/{mediaName}`	Delete media
`GET /asset/{id}/ddex-metadata`	DDEX metadata
`GET /asset/{id}/ddex-readiness`	DDEX readiness check
`GET /asset/{assetId}/works`	Musical works (ISWC)
`POST /asset/bulksplits`	Bulk assign splits
`DELETE /asset/bulk/deletesplit`	Bulk remove splits
`POST /asset/bulk/defaultsplit`	Bulk set default splits

Key fields: title, ISRC, type (Audio|Video|Ringtone|YouTube), version, displayArtist, mainArtist[], mainGenre[], subGenre[], explicit, language, tempo, key, mood[], lyrics, label, copyright, publisher

Products / Releases (`/product/`)

Standard CRUD plus:

Endpoint	Description
`GET /product/{id}/artists`	Release's artists
`GET /product/{id}/assets`	Release's tracks
`GET /product/{id}/stats`	Release analytics
`POST /product/{id}/setdefaultsplit`	Set default split
`GET /product/{id}/media`	Release artwork/media
`GET /product/{id}/delivery`	Delivery info
`GET /product/{id}/delivery/status`	Delivery status
`POST /product/batch-delivery`	Batch deliver releases
`GET /product/{id}/deliveries`	Delivery history
`POST /product/{id}/deliveries/{deliveryId}/retry`	Retry failed delivery
`GET /product/delivery-providers`	Available distributors
`GET /product/download/metadata`	Metadata export

Splits (`/split/`)

Standard CRUD plus:

Endpoint	Description
`POST /split/default`	Create split from artist default
`POST /split/match`	Find splits matching criteria
`DELETE /split/bulk/catalog-splits`	Remove catalog-level splits

Split types: simple, conditional, temporal

{
  "entity_type": "artist",
  "entity_id": "uuid",
  "split_type": "conditional",
  "effective_date": "2025-01-01",
  "shares": [
    { "user": "user-uuid-1", "percentage": 60 },
    { "user": "user-uuid-2", "percentage": 40 }
  ],
  "conditions": {
    "territories": ["US", "GB", "CA"],
    "mode": "include",
    "sources": ["Spotify", "Apple Music"],
    "period_start": "2025-01-01",
    "period_end": "2025-12-31",
    "memo": "North America streaming deal"
  }
}

Rules: Shares must sum to 100. entity_type is artist, product, or asset. Conditions are optional (omit for simple splits).

Royalties / Analytics (`/royalty/`)

Read-only analytics endpoints. All support the standard filter params (start, end, dsp, country, etc.). Requires royaltyAccess feature.

Endpoint	Description
`GET /royalty/`	Main summary
`GET /royalty/month`	Monthly trends
`GET /royalty/dsp`	By DSP/platform
`GET /royalty/country`	By country/territory
`GET /royalty/artist`	By artist
`GET /royalty/product`	By product/release
`GET /royalty/asset`	By track
`GET /royalty/tables`	By data source
`GET /royalty/saletype`	By sale type (stream, download, etc.)
`GET /royalty/aggregator`	By distributor
`GET /royalty/accountingperiod`	By accounting period

Analytics response shape:

{
  "Downloads": 1500,
  "Streams": 250000,
  "Royalty": 1234.56,
  "Count": 251500,
  "RatePer1K": 4.91,
  "RoyaltyPercentage": 45.2,
  "CountPercentage": 38.7,
  "PreviousRoyalty": 1100.00,
  "PreviousCount": 220000
}

PreviousRoyalty and PreviousCount are only present when includePreviousPeriod=true.

Accounting (`/accounting/`)

Endpoint	Description
`GET /accounting/{id}/stats`	User accounting stats
`GET /accounting/transactions`	Transaction list
`GET /accounting/transactions/summary`	Transaction summary
`GET /accounting/transactions/monthly`	Monthly transaction breakdown
`GET /accounting/getcurrentdue`	Current amount due per user
`GET /accounting/gettotaldue`	Total outstanding across workspace
`POST /accounting/refresh`	Recalculate accounting
`POST /accounting/refreshstats`	Refresh stats cache
`POST /accounting/users/{id}/recalculate`	Recalculate single user
`POST /accounting/tenant/recalculate`	Recalculate entire workspace
`GET /accounting/queue/status`	Processing queue status

Payments (`/payment/`)

Standard CRUD. Supports both JSON and multipart/form-data (for attaching receipts).

Endpoint	Description
`GET /payment/summary`	Payment totals
`POST /payment/bulk`	Bulk create payments

Payment Requests (`/payment-request/`)

Endpoint	Description
`GET /payment-request/`	List requests
`GET /payment-request/{id}`	Get request
`POST /payment-request/{id}/approve`	Approve request
`POST /payment-request/{id}/decline`	Decline request

Royalty Files (`/file/`)

Endpoint	Description
`GET /file/royalty`	List uploaded royalty files
`GET /file/royalty/{id}`	Get file details
`DELETE /file/royalty/{id}`	Delete file
`GET /file/summary`	File summary stats
`POST /file/createroyalty`	Upload royalty file
`GET /file/upload-url`	Get presigned upload URL
`POST /file/confirm-upload-completion`	Confirm upload finished
`GET /file/detection/{sessionId}`	Poll auto-detection status
`POST /file/confirm-detection/{sessionId}`	Confirm detected format
`GET /file/auto-processing-config`	Auto-processing settings
`POST /file/enable-auto-processing`	Enable auto-processing
`GET /file/sources`	List royalty sources (DSPs)
`GET /file/{id}/download`	Download file
`GET /file/processing/{jobId}`	Processing job status
`POST /file/session/{sessionId}/start-source-creator`	Bridge to source creator for unknown formats
`POST /file/upload-from-drive`	Upload from Google Drive

Labels (`/labels/`)

Standard CRUD plus:

Endpoint	Description
`GET /labels/hierarchy`	Label tree structure

Releases (`/releases`)

Full release lifecycle with media management:

Release CRUD:

Endpoint	Description
`POST /releases`	Create release (draft)
`GET /releases`	List releases
`GET /releases/stats`	Release statistics
`GET /releases/{id}`	Get release details
`PUT /releases/{id}`	Update release
`DELETE /releases/{id}`	Delete release

Lifecycle Workflow:

Endpoint	Role	Description
`POST /releases/{id}/submit`	user	Submit for review
`POST /releases/{id}/review`	admin	Start review
`POST /releases/{id}/feedback`	admin	Add feedback
`POST /releases/{id}/revert-status`	admin	Revert release status

Release Media:

Endpoint	Description
`POST /releases/{id}/media/files`	Upload release files (artwork, etc.)
`POST /releases/{id}/media/links`	Submit release links
`GET /releases/{id}/media`	Get release media
`DELETE /releases/{id}/media/{mediaId}`	Delete release media

Track Management:

Endpoint	Description
`POST /releases/{id}/tracks`	Create track in release
`PUT /releases/{id}/tracks/{trackId}`	Update track
`DELETE /releases/{id}/tracks/{trackId}`	Delete track
`POST /releases/{id}/tracks/reorder`	Reorder release tracks
`POST /releases/{id}/tracks/link-asset`	Link existing asset to release

Track Media:

Endpoint	Description
`POST /releases/{id}/tracks/{trackId}/media/file`	Upload track audio/video file
`POST /releases/{id}/tracks/{trackId}/media/link`	Submit track link
`GET /releases/{id}/tracks/{trackId}/media`	Get track media
`DELETE /releases/{id}/tracks/{trackId}/media/{mediaId}`	Delete track media

Expenses & Revenue

Both follow standard CRUD at /expense/ and /revenue/ with summary endpoints.

Notifications (`/notifications/`)

Endpoint	Description
`GET /notifications/`	List notifications
`PATCH /notifications/{id}/read`	Mark as read
`PATCH /notifications/read-all`	Mark all as read
`GET /notifications/unread-count`	Unread count

Downloads / Reports (`/download/`)

Endpoint	Description
`POST /download/generate`	Generate report download
`GET /download/{id}/status`	Check generation status
`GET /download/list`	List available downloads

5. Global Search (`/search`)

Cross-entity search across the entire catalog.

Endpoint	Role	Description
`GET /search?q={query}&types={types}`	user	Global search
`GET /search/recent`	user	Get recent searches
`DELETE /search/recent`	user	Clear search history

Query Parameters:

Param	Type	Description
`q`	string	Search query text
`types`	CSV string	Entity types to search (e.g., `artist,product,asset,user`)

6. Royalty Sources (`/sources`)

Manage royalty data sources (DSPs, distributors, custom sources).

Tenant Routes:

Endpoint	Role	Description
`GET /sources`	user	List tenant's royalty sources
`POST /sources`	user	Create new tenant source
`GET /sources/{id}`	user	Get source details
`PUT /sources/{id}`	user	Update source
`DELETE /sources/{id}`	user	Delete source
`POST /sources/{id}/activate`	user	Activate source
`POST /sources/{id}/deactivate`	user	Deactivate source

7. Source Creator (`/source-creator`)

AI-powered wizard for creating new royalty source definitions. Requires royaltyAccess feature.

Analysis & Mapping:

Endpoint	Description
`POST /source-creator/analyze`	Upload and analyze file (multipart)
`POST /source-creator/ai-map-columns`	Get AI column mapping suggestions (rate limited)
`PUT /source-creator/sessions/{id}/mappings`	Save user-confirmed mappings
`PUT /source-creator/sessions/{id}/periods`	Confirm accounting periods
`POST /source-creator/sessions/{id}/suggest-name`	Get smart name suggestion

Query Generation & Testing:

Endpoint	Description
`POST /source-creator/generate-queries`	Generate BigQuery SQL from mappings (rate limited)
`POST /source-creator/test-queries`	Test queries against sample data

Save & Reuse:

Endpoint	Description
`POST /source-creator/save`	Save as draft source
`POST /source-creator/reuse`	Reuse existing source for new file
`GET /source-creator/sources/{id}/mappings`	Get source column mappings
`GET /source-creator/sources/{id}/queries`	Get source queries

Session Management:

Endpoint	Description
`GET /source-creator/sessions`	List sessions
`GET /source-creator/sessions/{id}`	Get session details
`DELETE /source-creator/sessions/{id}`	Delete session

Admin Routes (super admin only):

Endpoint	Description
`GET /source-creator/admin/drafts`	List all draft sources across tenants
`GET /source-creator/admin/sessions/{id}`	Get full session detail
`POST /source-creator/admin/{id}/promote`	Promote draft to global source

Source Creator Flow

1. POST /source-creator/analyze              → Upload file, get column analysis
2. POST /source-creator/ai-map-columns       → Get AI mapping suggestions
3. PUT  /source-creator/sessions/{id}/mappings → Confirm mappings
4. PUT  /source-creator/sessions/{id}/periods  → Confirm accounting periods
5. POST /source-creator/generate-queries      → Generate BigQuery SQL
6. POST /source-creator/test-queries          → Validate against sample data
7. POST /source-creator/save                  → Save as draft source
   (Admin) POST /source-creator/admin/{id}/promote → Promote to global

8. Checklist / Data Quality (`/checklist`)

Data quality validation, catalog enrichment, and workflow orchestration. Requires admin role.

Validation Checks:

Endpoint	Description
`GET /checklist/royaltyassets`	Assets appearing in royalty data but not in catalog
`GET /checklist/royaltyproducts`	Products appearing in royalty data but not in catalog
`GET /checklist/assetsplits`	Assets missing split assignments
`GET /checklist/productsplits`	Products missing split assignments
`GET /checklist/allsplits`	All split coverage issues
`GET /checklist/missingroyaltysplits`	Royalty items without splits
`GET /checklist/artistsplits`	Artist split user issues
`GET /checklist/missingprimaryartists`	Assets/products missing primary artists
`GET /checklist/duplicateartists`	Duplicate artist detection
`GET /checklist/productswithoutassets`	Products with no linked assets
`GET /checklist/assetswithoutproducts`	Assets with no linked products

Import from Royalty Data:

Endpoint	Description
`POST /checklist/royaltyassets/import`	Import missing assets from royalty data
`POST /checklist/royaltyproducts/import`	Import missing products from royalty data

Catalog Enrichment:

Endpoint	Description
`POST /checklist/assets/enrich`	Enrich assets with external metadata
`POST /checklist/products/enrich`	Enrich products with external metadata
`GET /checklist/enrichment`	List enrichment items
`GET /checklist/enrichment/job/{jobId}`	Get enrichment job status
`GET /checklist/enrichment/{id}`	Get enrichment item details
`PUT /checklist/enrichment/{id}`	Update enrichment item
`POST /checklist/enrichment/approve`	Approve enrichment items
`POST /checklist/enrichment/reject`	Reject enrichment items
`POST /checklist/enrichment/re-enrich`	Re-enrich rejected items
`POST /checklist/enrichment/cleanup`	Cleanup enrichment items

Workflow Orchestration:

Endpoint	Description
`POST /checklist/workflow`	Start a checklist workflow
`GET /checklist/workflow`	List workflows
`GET /checklist/workflow/{id}`	Get workflow details
`POST /checklist/workflow/{id}/respond`	Respond to workflow prompt
`POST /checklist/workflow/{id}/cancel`	Cancel workflow

9. DDEX Distribution (`/ddex`)

Digital Data Exchange standard support for release distribution. Requires addonsAccess feature + ddex addon.

ERN (Electronic Release Notification):

Endpoint	Role	Description
`POST /ddex/ern/generate`	admin	Generate ERN message for a release
`POST /ddex/ern/generate-batch`	admin	Generate multiple ERN messages

MEAD (Music Enrichment and Description):

Endpoint	Role	Description
`POST /ddex/mead/generate`	admin	Generate MEAD message
`PUT /ddex/mead/{entityId}`	admin	Update MEAD metadata

Message Management:

Endpoint	Role	Description
`GET /ddex/messages`	user	List all DDEX messages
`GET /ddex/messages/{messageId}`	user	Get message details
`POST /ddex/messages/{messageId}/validate`	admin	Validate message
`GET /ddex/messages/{messageId}/download`	admin	Download message XML

Delivery:

Endpoint	Role	Description
`POST /ddex/delivery/deliver/{messageId}`	admin	Deliver message to provider
`POST /ddex/delivery/deliver-batch`	admin	Batch delivery
`POST /ddex/delivery/retry/{messageId}`	admin	Retry failed delivery
`GET /ddex/delivery/status/{messageId}`	user	Get delivery status
`GET /ddex/delivery/logs/{messageId}`	admin	Get delivery logs
`POST /ddex/delivery/test-connection`	owner	Test DSP connection
`POST /ddex/delivery/test-all-connections`	owner	Test all provider connections

Provider Management:

Endpoint	Role	Description
`GET /ddex/providers`	user	List available DSP providers
`GET /ddex/providers/{providerId}`	user	Get provider details
`GET /ddex/providers/{providerId}/stats`	user	Get provider statistics

Tenant Provider Configuration:

Endpoint	Role	Description
`GET /ddex/tenant-providers`	admin	List tenant's configured providers
`POST /ddex/tenant-providers`	owner	Configure new provider
`PUT /ddex/tenant-providers/{id}`	owner	Update provider config
`DELETE /ddex/tenant-providers/{id}`	owner	Remove provider config

Queue & Monitoring:

Endpoint	Role	Description
`GET /ddex/queue/jobs`	admin	List queue jobs
`GET /ddex/queue/jobs/{jobId}`	admin	Get job details
`GET /ddex/queue/jobs/{jobId}/logs`	admin	Get job logs
`GET /ddex/monitoring/dashboard`	admin	Monitoring dashboard

Usage:

Endpoint	Role	Description
`GET /ddex/usage`	admin	Get DDEX usage stats
`GET /ddex/usage/dashboard`	admin	Usage dashboard

DDEX Distribution Flow

1. POST /ddex/tenant-providers                    → Configure DSP provider (one-time)
2. POST /ddex/delivery/test-connection            → Verify connection
3. POST /ddex/ern/generate { releaseId }          → Generate ERN message
4. POST /ddex/messages/{messageId}/validate       → Validate message
5. POST /ddex/delivery/deliver/{messageId}        → Deliver to DSP
6. GET  /ddex/delivery/status/{messageId}         → Monitor delivery status
   If failed: POST /ddex/delivery/retry/{messageId}

10. AI Chat Agent (`/ai`)

Conversational AI assistant with workspace context. Requires aiAgent feature. Supports Vercel AI SDK streaming.

Conversations:

Endpoint	Description
`POST /ai/conversations`	Create conversation
`GET /ai/conversations`	List conversations
`GET /ai/conversations/{conversationId}`	Get conversation
`PUT /ai/conversations/{conversationId}`	Update conversation
`DELETE /ai/conversations/{conversationId}`	Archive conversation

Messages:

Endpoint	Description
`GET /ai/conversations/{conversationId}/messages`	Get messages
`POST /ai/conversations/{conversationId}/messages`	Send message (rate limited)
`POST /ai/chat`	Vercel AI SDK streaming chat

Status & Configuration:

Endpoint	Description
`GET /ai/health`	Health check (public)
`GET /ai/rate-limit`	Check rate limit status
`GET /ai/budget-status`	Check cost budget status
`GET /ai/suggestions`	Get context-aware follow-up suggestions
`GET /ai/config`	Get AI configuration
`POST /ai/feedback`	Submit conversation feedback
`GET /ai/conversations/{conversationId}/stats`	Conversation stats

Retention Config (admin):

Endpoint	Description
`GET /ai/retention-config`	Get retention policy
`PUT /ai/retention-config`	Update retention policy
`POST /ai/retention/apply-now`	Apply retention immediately

AI Chat Streaming

The /ai/chat endpoint supports Vercel AI SDK streaming format:

POST /ai/chat
Content-Type: application/json

{
  "messages": [
    { "role": "user", "content": "What are my top performing artists this quarter?" }
  ],
  "conversationId": "optional-conversation-uuid"
}

The response is a server-sent event stream compatible with useChat() from the Vercel AI SDK.

11. Merlin Addon (`/merlin`)

Automated royalty file import via FTP with approval workflows. Requires addonsAccess feature + merlin addon.

Configuration:

Endpoint	Role	Description
`POST /merlin/config`	owner	Create or update Merlin config
`GET /merlin/config`	admin	Get Merlin configuration
`DELETE /merlin/config`	owner	Disable Merlin integration

Credentials & Connection:

Endpoint	Role	Description
`PUT /merlin/credentials`	owner	Update FTP credentials
`POST /merlin/test-connection`	owner	Test FTP connection
`GET /merlin/connection-status`	admin	Get connection status
`PUT /merlin/features`	admin	Update enabled features

Import Configuration (requires royaltyImport addon feature):

Endpoint	Role	Description
`GET /merlin/import/config`	admin	Get import config
`PUT /merlin/import/config`	admin	Update import config
`PUT /merlin/import/schedule`	admin	Update import schedule

Import Operations:

Endpoint	Role	Description
`POST /merlin/import/trigger`	admin	Trigger manual import
`GET /merlin/import/batches`	user	List import batches
`GET /merlin/import/batch/{id}`	user	Get batch details
`POST /merlin/import/batch/{id}/cancel`	admin	Cancel batch

Pending Import Approval:

Endpoint	Role	Description
`GET /merlin/pending`	user	List pending imports
`GET /merlin/pending/grouped`	user	Pending imports grouped by source/period
`GET /merlin/pending/{id}`	user	Get pending import details
`GET /merlin/pending/{id}/preview`	user	Preview file contents
`GET /merlin/pending/{id}/recommendation`	user	Get confidence recommendation
`POST /merlin/pending/{id}/approve`	admin	Approve pending import
`POST /merlin/pending/{id}/reject`	admin	Reject pending import
`POST /merlin/pending/bulk-approve`	admin	Bulk approve
`POST /merlin/pending/bulk-reject`	admin	Bulk reject

Auto-Approval:

Endpoint	Role	Description
`GET /merlin/batches/{batchId}/auto-approvable`	user	Get auto-approvable candidates
`GET /merlin/imports/groupable`	user	Get groupable imports

History & Stats:

Endpoint	Role	Description
`GET /merlin/sources`	user	List Merlin-compatible sources
`GET /merlin/history`	user	Import history
`GET /merlin/stats`	user	Import statistics
`GET /merlin/metrics`	user	Comprehensive metrics

12. Data Shares (`/data-shares`)

Cross-tenant royalty data sharing for labels sharing sources.

Endpoint	Role	Description
`GET /data-shares`	admin	List data shares
`POST /data-shares`	owner	Create data share
`GET /data-shares/{id}`	admin	Get share details
`PUT /data-shares/{id}`	owner	Update share
`DELETE /data-shares/{id}`	owner	Delete share

13. Music Publishing

Publishing management with CWR (Common Works Registration) export. Requires publisher addon.

Publishers (`/publishers`)

Endpoint	Role	Description
`GET /publishers`	user	List publishers
`POST /publishers`	admin	Create publisher
`GET /publishers/{id}`	user	Get publisher
`PUT /publishers/{id}`	admin	Update publisher
`DELETE /publishers/{id}`	admin	Delete publisher
`GET /publishers-with-user-data`	user	Publishers with associated user data

Territory Management:

Endpoint	Role	Description
`GET /publishers/{id}/territories`	user	List territories
`POST /publishers/{id}/territories`	admin	Add territory
`PUT /publishers/{id}/territories/{territoryId}`	admin	Update territory
`DELETE /publishers/{id}/territories/{territoryId}`	admin	Delete territory

Agreement Management:

Endpoint	Role	Description
`GET /publishers/{id}/agreements`	user	List agreements
`POST /publishers/{id}/agreements`	admin	Create agreement
`PUT /publishers/{id}/agreements/{agreementId}`	admin	Update agreement
`DELETE /publishers/{id}/agreements/{agreementId}`	admin	Delete agreement

Sub-Publishing:

Endpoint	Role	Description
`POST /sub-publishing`	admin	Create sub-publishing agreement
`GET /sub-publishing`	user	List sub-publishing agreements
`GET /sub-publishing/{id}`	user	Get agreement details
`PUT /sub-publishing/{id}`	admin	Update agreement
`POST /sub-publishing/check-conflicts`	admin	Check territory conflicts

Writers (`/writers`)

Endpoint	Role	Description
`GET /writers`	user	List writers
`POST /writers`	admin	Create writer
`GET /writers/{id}`	user	Get writer
`PUT /writers/{id}`	admin	Update writer
`DELETE /writers/{id}`	admin	Delete writer
`GET /writers-with-user-data`	user	Writers with associated user data
`POST /writers/{writerId}/works/{workId}`	admin	Assign writer to work
`DELETE /writers/{writerId}/works/{workId}`	admin	Remove writer from work

Musical Works (`/works`)

Endpoint	Role	Description
`GET /works`	user	List works
`POST /works`	admin	Create work
`GET /works/{id}`	user	Get work
`PUT /works/{id}`	admin	Update work
`DELETE /works/{id}`	admin	Delete work

Work-Recording Links:

Endpoint	Role	Description
`POST /works/{workId}/recordings/{assetId}`	admin	Link work to recording
`GET /works/{workId}/recordings`	user	Get work's recordings
`POST /works/{workId}/recordings/{assetId}/primary`	admin	Set primary recording
`GET /works/{workId}/recordings/primary`	user	Get primary recording
`GET /works/recordings/{assetId}/works`	user	Get recording's works

Work Registrations:

Endpoint	Role	Description
`POST /works/registrations`	admin	Create/update registration
`GET /works/registrations`	user	List all registrations
`GET /works/{workId}/registrations`	user	Get work's registrations
`GET /works/registrations/summary`	user	Registration summary
`GET /works/registrations/{id}`	user	Get registration details
`DELETE /works/registrations/{id}`	admin	Delete registration
`PATCH /works/registrations/{id}/status`	admin	Update registration status

Work-Writer Relationships:

Endpoint	Role	Description
`GET /works/work-writers`	user	List work-writer relationships

CWR Export (`/cwr`)

Endpoint	Role	Description
`POST /cwr/export`	admin	Export CWR file
`GET /cwr/status/{publisherId}`	user	Get export status
`POST /cwr/cancel`	admin	Cancel export
`POST /cwr/acknowledgment`	admin	Process acknowledgment file (upload)
`GET /cwr/works/registration-status`	user	Get work registration statuses
`GET /cwr/works/{workId}/registration`	user	Get work's CWR registration
`PATCH /cwr/registrations/{registrationId}/status`	admin	Update registration status

14. Currency Management (`/currencies`)

Public Routes:

Endpoint	Description
`GET /currencies`	List all supported currencies
`GET /currencies/{code}`	Get currency details

Tenant Routes:

Endpoint	Role	Description
`GET /currencies/tenant`	user	Get tenant's enabled currencies
`GET /currencies/tenant/default`	user	Get tenant's default currency
`POST /currencies/tenant/{code}/enable`	admin	Enable currency
`POST /currencies/tenant/{code}/disable`	admin	Disable currency
`POST /currencies/tenant/{code}/default`	owner	Set default currency

15. Billing & Subscriptions (`/billing`)

Subscription management with Stripe integration.

Current State:

Endpoint	Role	Description
`GET /billing/active`	user	Get active subscription
`GET /billing/sync-status`	user	Subscription sync status
`GET /billing/usage`	user	Usage summary

Plans:

Endpoint	Role	Description
`GET /billing/plans`	user	List available plans
`GET /billing/plans/stripe`	user	Get Stripe plans

Subscription Management:

Endpoint	Role	Description
`GET /billing/subscriptions`	admin	List subscriptions
`GET /billing/subscriptions/{id}`	admin	Get subscription
`POST /billing/subscriptions`	owner	Create subscription
`POST /billing/subscriptions/{id}/cancel`	owner	Cancel subscription

Plan Changes:

Endpoint	Role	Description
`POST /billing/upgrade/checkout-session`	owner	Create Stripe checkout for upgrade
`POST /billing/upgrade/{lookupKey}`	owner	Direct plan upgrade
`POST /billing/downgrade`	owner	Downgrade plan

Custom Invoices:

Endpoint	Role	Description
`POST /billing/invoices/custom`	owner	Create custom invoice
`PUT /billing/invoices/custom/{id}`	owner	Update custom invoice
`DELETE /billing/invoices/custom/{id}`	owner	Delete custom invoice
`POST /billing/invoices/custom/{id}/mark-paid`	owner	Mark invoice as paid
`GET /billing/invoices`	admin	List invoices

Stripe Integration:

Endpoint	Role	Description
`POST /billing/portal`	owner	Create Stripe customer portal session
`POST /billing/customer-session`	owner	Create Stripe customer session
`POST /billing/refresh`	owner	Force refresh subscription data

16. Custom Domains (`/domains`)

Cloudflare SaaS custom domain management.

Endpoint	Role	Description
`POST /domains/setup`	admin	Setup custom domain
`GET /domains/status`	user	Get domain status
`GET /domains/instructions`	user	Get DNS setup instructions
`POST /domains/switch-validation`	admin	Switch validation method
`POST /domains/restart-validation`	admin	Restart domain validation
`DELETE /domains`	owner	Delete custom domain
`GET /domains/all`	admin	List all domains

17. Admin Dashboard (`/admin/dashboard`)

Centralized admin dashboard for workspace management.

Endpoint	Role	Description
`GET /admin/dashboard/overview`	admin	Dashboard overview metrics
`GET /admin/dashboard/analytics`	admin	Release analytics
`GET /admin/dashboard/health`	admin	System health monitoring
`GET /admin/dashboard/users`	admin	User management data
`POST /admin/dashboard/releases/bulk-action`	owner	Bulk approve/reject releases
`GET /admin/dashboard/config`	admin	Get dashboard config
`PUT /admin/dashboard/config`	owner	Update dashboard config
`GET /admin/dashboard/config/export`	admin	Export config JSON
`POST /admin/dashboard/config/import`	owner	Import config JSON
`GET /admin/dashboard/workers/stats`	admin	Background worker statistics
`POST /admin/dashboard/workers/{workerName}/pause`	admin	Pause worker
`POST /admin/dashboard/workers/{workerName}/resume`	admin	Resume worker

18. Audit Trail (`/api/audit`)

Audit logging for compliance and security monitoring. Requires admin role.

Endpoint	Role	Description
`GET /api/audit`	admin	List all audit trails
`GET /api/audit/entity/{entityType}/{entityId}`	admin	Get entity audit trail
`GET /api/audit/user/{userId}/activity`	admin/self	Get user activity (self-access allowed)
`GET /api/audit/high-risk`	admin	Get high-risk security events

19. Monitoring (`/api/monitoring`)

System monitoring for delivery pipelines and integrations.

FUGA Delivery Monitoring:

Endpoint	Role	Description
`GET /api/monitoring/fuga/metrics`	user	FUGA delivery metrics
`GET /api/monitoring/fuga/health`	user	FUGA health status
`GET /api/monitoring/fuga/alerts`	user	FUGA alerts
`GET /api/monitoring/fuga/stuck-deliveries`	user	Stuck deliveries
`GET /api/monitoring/fuga/ftp-health`	user	FTP connection health
`PUT /api/monitoring/fuga/thresholds`	admin	Update alert thresholds

DDEX Registry Monitoring:

Endpoint	Role	Description
`GET /api/monitoring/registries/health`	user	Registry health
`GET /api/monitoring/registries/adapters`	user	Adapter health
`GET /api/monitoring/registries/providers`	user	Registered providers
`GET /api/monitoring/registries/metrics`	user	Adapter metrics

Prometheus Metrics:

Endpoint	Description
`GET /api/monitoring/metrics/fuga`	Prometheus-compatible metrics endpoint

20. Webhooks

Outbound Webhooks (Royalti → Your Endpoint)

Configure your webhook endpoint via tenant settings:

# Set webhook URL
PUT /tenant/settings/webhook-url
{ "webhookUrl": "https://yourapp.com/webhooks/royalti" }

# Enable/disable webhooks
PUT /tenant/settings/webhook-isActive
{ "isActive": true }

# Subscribe to event types
PUT /tenant/settings/webhook-enabledEvents
{ "enabledEvents": ["PAYMENT_COMPLETED", "ROYALTY_FILE_PROCESSED"] }

Event Categories

Financial Events:

PAYMENT_COMPLETED, PAYMENT_PROCESSING, PAYMENT_MADE_FAILED
PAYMENT_REQUEST_SENT, PAYMENT_REQUEST_APPROVED, PAYMENT_REQUEST_REJECTED
PAYMENT_DELETED
REVENUE_CREATED, REVENUE_UPDATED, REVENUE_DELETED
EXPENSE_CREATED, EXPENSE_UPDATED, EXPENSE_DELETED

Catalog Events:

ASSET_CREATED, ASSET_UPDATED, ASSET_DELETED
PRODUCT_CREATED, PRODUCT_UPDATED, PRODUCT_DELETED

Roster Events:

USER_CREATED, USER_UPDATED, USER_DELETED
USER_INVITATION_SENT
ARTIST_CREATED, ARTIST_UPDATED, ARTIST_DELETED

Royalty Events (opt-in):

ROYALTY_FILE_UPLOADED
ROYALTY_FILE_PROCESSED
ROYALTY_FILE_PROCESSING_FAILED

Split Events:

USER_ADDED_TO_SPLIT
USER_REMOVED_FROM_SPLIT

Webhook Payload Structure

{
  "id": "whd_{uuid}",
  "event": "PAYMENT_COMPLETED",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "version": "1.0",
  "tenant": {
    "id": "tenant-uuid",
    "name": "My Label",
    "domain": "mylabel.royalti.io"
  },
  "source": {
    "service": "royalti-api",
    "environment": "production",
    "traceId": "trace-uuid"
  },
  "data": {
    "event": {
      "id": "evt-uuid",
      "type": "PAYMENT_COMPLETED",
      "category": "financial",
      "timestamp": "2025-01-15T10:30:00.000Z",
      "importance": "high"
    },
    "actor": {
      "id": "user-uuid",
      "type": "user",
      "name": "John Doe",
      "email": "[email protected]"
    },
    "resource": {
      "type": "payment",
      "id": "payment-uuid",
      "url": "https://app.royalti.io/payments/payment-uuid",
      "displayName": "Payment #1234"
    },
    "attributes": {
      "amount": 500.00,
      "currency": "USD",
      "recipientId": "user-uuid"
    },
    "previous": {}
  },
  "delivery": {
    "attempt": 1,
    "maxAttempts": 3,
    "nextRetryAt": "2025-01-15T10:35:00.000Z"
  }
}

previous is only populated on *_UPDATED events (contains pre-update values)
delivery.maxAttempts is 3 with exponential backoff
Financial and split events include HMAC signature for verification

HMAC Signature Validation

Financial and split webhook deliveries include an HMAC signature header for verification. Validate the signature before processing the payload.

Webhook Delivery Management

Endpoint	Description
`GET /webhook-deliveries`	List deliveries (filterable by status, event type, date)
`GET /webhook-deliveries/summary`	Delivery stats
`GET /webhook-deliveries/{id}`	Delivery details
`POST /webhook-deliveries/{id}/retry`	Retry failed delivery

Delivery statuses: pending, success, failed, timeout, cancelled

21. WebSocket Events (Socket.io)

Real-time events for file processing and workflow progress.

Connection

import { io } from "socket.io-client";

const socket = io("wss://api.royalti.io", {
  auth: { token: "<access_token>" }
});

Events are user-scoped — only the user who uploaded the file receives processing events. Workflow events are emitted to the tenant room.

File Processing Events

Event	When
`file:processing:started`	File processing begins
`file:processing:progress`	Progress update (~10% intervals)
`file:processing:completed`	Processing finished successfully
`file:processing:failed`	Processing failed

Workflow Events

Event	When
`workflow:prompt`	Workflow requires user input
`workflow:step-started`	Workflow step begins
`workflow:step-complete`	Workflow step finishes
`workflow:completed`	Workflow finished

File Processing Event Payload

{
  "fileId": "file-uuid",
  "fileName": "spotify-2025-01.csv",
  "status": "processing",
  "progress": 75,
  "message": "Processing row 750 of 1000",
  "error": null,
  "metadata": {
    "rowsProcessed": 750,
    "source": "Spotify",
    "accountingPeriod": "2025-01",
    "salePeriod": "2025-01",
    "processingTimeMs": 45000
  }
}

22. Key Data Models

Tenant (Workspace)

id (integer), name, email, user (varchar — must be a TenantUser.id UUID),
status (active|inactive|suspended), plan, stripeCustomerId,
bigqueryDataset, domain, uid

Important: The user field on Tenants stores a TenantUser.id, not a User.id. This is used by API key auth resolution and accounting owner-exclusion. See "API Key Auth Resolution" in Section 1.

User (Global)

id (UUID), email, isVerified, isAdmin, provider, googleId, linkedinId, facebookId

A User can belong to multiple workspaces via TenantUser records.

TenantUser (Workspace-Scoped)

id (UUID), UserId (FK → User.id), TenantId (FK → Tenant.id),
firstName, lastName, email, nickName, profileImg,
role: main_super_admin | super_admin | owner | admin | user | guest,
userType, paymentSettings, permissions (JSONB),
ipi, externalId, country, phone, isActive

Key distinction: TenantUser.id is the workspace-scoped identity used throughout the API (splits, payments, accounting). User.id (UserId) is the global auth identity. API responses for /user/ return TenantUser records, not User records.

Artist

id (UUID), artistName, signDate, label, publisher, copyright,
externalId, artistImg, links {spotify, youtube, instagram, ...},
genres[], realName, pseudonyms, biography, influences,
instruments, activeYears, associatedActs, contributors

Asset (Track)

id (UUID), title, ISRC, type (Audio|Video|Ringtone|YouTube),
version, displayArtist, mainArtist[], mainGenre[], subGenre[],
explicit, language, tempo, key, mood[], lyrics,
label, copyright, publisher, copyrightOwner,
recordingDate, recordingLocation, productionYear,
enableDDEX, focusTrack, ddexMetadata, resourceReference

Product (Release)

id (UUID), title, UPC, format (Single|EP|Album|LP),
release_date, takedown_date, label, display_artist,
type (Audio|Video), catalog_number, version, explicit,
main_genre, sub_genre, status (active|inactive|pending|Live|Taken Down|Scheduled|Error),
distribution, external_id

Split

id, entity_type (artist|product|asset), entity_id,
split_type (simple|conditional|temporal),
effective_date,
shares: [{ user: UUID, percentage: 0-100 }],
conditions: { territories[], mode, sources[], period_start, period_end, memo }

Transaction

id (UUID), type (payment|royalty|expense|adjustment),
amount, currency, status (pending|processed|failed),
reference, metadata

TenantRoyaltySource

id (UUID), name, displayName, type (dsp|distributor|custom),
salesDataQuery (BigQuery SQL), extractionQueries[],
periodConfig { type, format, startField, endField },
feeRate, currency, isActive, parentSourceId, version

TenantDataShare

id (UUID), sourceTenantId, targetTenantId,
sourceId, status (active|inactive),
sharedColumns[], filters

Publisher

id (UUID), name, ipiNumber, ipiNameNumber,
territories[], agreements[],
type (original|sub), parentPublisherId

Writer

id (UUID), firstName, lastName, ipiNumber, ipiNameNumber,
prAffiliation, mrAffiliation, srAffiliation,
writerDesignationCode, citizenshipCountry

Work (Musical Work)

id (UUID), title, iswc, alternativeTitles[],
writers[] (with shares), publishers[] (with shares),
recordings[] (linked assets), registrations[]

23. Common Integration Patterns

Sync Catalog from External System

1. POST /artist/bulk          → Create artists
2. POST /product/bulk         → Create products
3. POST /asset/bulk           → Create assets/tracks
4. POST /split/               → Assign splits per entity
5. POST /accounting/refresh   → Recalculate accounting

Upload and Process Royalty File

1. GET  /file/upload-url               → Get presigned upload URL
2. PUT  <presigned_url>                 → Upload file to cloud storage
3. POST /file/confirm-upload-completion → Notify API upload is done
4. GET  /file/detection/{sessionId}     → Poll auto-detection (or listen via WebSocket)
5. POST /file/confirm-detection/{sessionId} → Confirm detected format
   If unknown source:
   POST /file/session/{sessionId}/start-source-creator → Bridge to Source Creator
6. GET  /file/processing/{jobId}        → Poll processing status
   OR subscribe to WebSocket: file:processing:progress
7. POST /accounting/refresh             → Recalculate after processing

Create a New Royalty Source (Source Creator)

1. POST /source-creator/analyze              → Upload & analyze file
2. POST /source-creator/ai-map-columns       → Get AI mapping suggestions
3. PUT  /source-creator/sessions/{id}/mappings → Confirm column mappings
4. PUT  /source-creator/sessions/{id}/periods  → Confirm periods
5. POST /source-creator/generate-queries      → Generate BigQuery SQL
6. POST /source-creator/test-queries          → Sandbox validation
7. POST /source-creator/save                  → Save as draft

DDEX Release Distribution

1. POST /ddex/tenant-providers                → Configure DSP provider
2. POST /ddex/delivery/test-connection        → Verify connection
3. POST /ddex/ern/generate { releaseId }      → Generate ERN
4. POST /ddex/messages/{id}/validate          → Validate
5. POST /ddex/delivery/deliver/{id}           → Deliver to DSP
6. GET  /ddex/delivery/status/{id}            → Monitor

Data Quality Checklist

1. GET /checklist/royaltyassets          → Find missing catalog items
2. POST /checklist/royaltyassets/import  → Import them
3. POST /checklist/assets/enrich         → Enrich with metadata
4. POST /checklist/enrichment/approve    → Approve enrichments
5. GET /checklist/missingroyaltysplits   → Find unsplit royalties
6. POST /checklist/workflow              → Start automated workflow

Fetch Analytics Dashboard Data

1. GET /royalty/?start=2025-01-01&end=2025-12-31              → Overview
2. GET /royalty/month?start=2025-01-01&end=2025-12-31         → Monthly trend
3. GET /royalty/dsp?start=2025-01-01&end=2025-12-31           → Platform breakdown
4. GET /royalty/country?start=2025-01-01&end=2025-12-31       → Geographic breakdown
5. GET /royalty/asset?start=2025-01-01&end=2025-12-31&size=10 → Top tracks

Set Up Webhook Listener

1. PUT /tenant/settings/webhook-url          → Set your endpoint
2. PUT /tenant/settings/webhook-enabledEvents → Choose event types
3. PUT /tenant/settings/webhook-isActive     → Enable
4. GET /webhook-deliveries                   → Monitor deliveries
5. POST /webhook-deliveries/{id}/retry       → Retry failures

Release Lifecycle

1. POST /releases                          → Create draft release
2. POST /releases/{id}/media/files         → Upload artwork
3. POST /releases/{id}/tracks              → Add tracks
4. POST /releases/{id}/tracks/{trackId}/media/file → Upload audio
5. POST /releases/{id}/tracks/reorder      → Set track order
6. POST /releases/{id}/submit              → Submit for review
7. POST /releases/{id}/review              → Admin reviews
8. POST /releases/{id}/feedback            → Admin feedback (optional)
   OR POST /ddex/ern/generate              → Generate DDEX for distribution

24. Code Examples

Language-specific integration examples are available in the references/ directory:

references/examples-javascript.md — Node.js/TypeScript client, auth, CRUD, file upload, WebSocket, Express webhook receiver
references/examples-python.md — Python client, auth, pagination, file upload, Flask webhook receiver, socketio
references/examples-php.md — PHP client, auth, pagination, file upload, Laravel and plain PHP webhook receivers

Load these files when the developer is working in a specific language.

25. Troubleshooting

Common Errors

Error Message	HTTP Code	Cause	Fix
`"Workspace user not found"`	404	API key's workspace has `Tenants.user` pointing to wrong ID (UserId instead of TenantUserId), or no owner TenantUser exists	Verify `Tenants.user` matches a `TenantUser.id` where `role='owner'` for that workspace
`"Workspace not found"`	404	Tenant doesn't exist or `status != 'active'`	Check tenant status in admin panel
`"Authorization token is missing"`	401	No `Authorization` header or malformed token	Ensure `Authorization: Bearer <token>` header is present
`"Route does not exist"`	—	Wrong URL path (e.g., `/api/users` instead of `/user/`)	Check endpoint paths — no `/api` prefix, resource names are singular
`"Access denied"`	403	Token valid but user lacks required role for endpoint	Check RBAC requirements for the endpoint

Endpoint Path Gotchas

Paths use singular nouns: /user/, /artist/, /asset, /product/
Exceptions: /labels/, /releases, /notifications/, /publishers, /writers
Most paths require a trailing slash: /user/ not /user
No /api prefix — endpoints are at the root: https://api.royalti.io/artist/
Sources endpoint: /file/sources (nested under files, not standalone)

26. Further Reading

API Explorer: apidocs.royalti.io
MCP Server: royalti.io/mcp — AI assistant integration for direct API interaction
MCP Setup Guide: royalti.io/help/setting-up-the-royalti-mcp-server

One thing to look at

What its author says it does

SKILL.md

Royalti API v2.6 — Developer Reference

1. Authentication

Token Types

Two-Step JWT Login

Using the Access Token

API Key Authentication

API Key Auth Resolution (Internals)

Other Auth Methods

Rate Limiting

RBAC Roles (ascending privilege)

Feature Gating

2. Request Patterns

Standard Headers

Pagination (all list endpoints)

Filtering (analytics endpoints)

Search

Bulk Operations

3. Response Patterns

Success Response

Paginated List Response

Summary Response (v2.6.4+)

Error Response

Common HTTP Status Codes

4. Core Resources

Standard CRUD Pattern

Users (/user/)

Artists (/artist/)

Assets / Tracks (/asset)

Products / Releases (/product/)

Splits (/split/)

Royalties / Analytics (/royalty/)

Accounting (/accounting/)

Payments (/payment/)

Payment Requests (/payment-request/)

Royalty Files (/file/)

Labels (/labels/)

Releases (/releases)

Expenses & Revenue

Notifications (/notifications/)

Downloads / Reports (/download/)

5. Global Search (/search)

6. Royalty Sources (/sources)

7. Source Creator (/source-creator)

Source Creator Flow

8. Checklist / Data Quality (/checklist)

9. DDEX Distribution (/ddex)

DDEX Distribution Flow

10. AI Chat Agent (/ai)

AI Chat Streaming

11. Merlin Addon (/merlin)

12. Data Shares (/data-shares)

13. Music Publishing

Publishers (/publishers)

Writers (/writers)

Musical Works (/works)

CWR Export (/cwr)

14. Currency Management (/currencies)

15. Billing & Subscriptions (/billing)

16. Custom Domains (/domains)

17. Admin Dashboard (/admin/dashboard)

18. Audit Trail (/api/audit)

19. Monitoring (/api/monitoring)

20. Webhooks

Outbound Webhooks (Royalti → Your Endpoint)

Event Categories

Webhook Payload Structure

HMAC Signature Validation

Webhook Delivery Management

21. WebSocket Events (Socket.io)

Connection

File Processing Events

Workflow Events

File Processing Event Payload

22. Key Data Models

Tenant (Workspace)

User (Global)

TenantUser (Workspace-Scoped)

Users (`/user/`)

Artists (`/artist/`)

Assets / Tracks (`/asset`)

Products / Releases (`/product/`)

Splits (`/split/`)

Royalties / Analytics (`/royalty/`)

Accounting (`/accounting/`)

Payments (`/payment/`)

Payment Requests (`/payment-request/`)

Royalty Files (`/file/`)

Labels (`/labels/`)

Releases (`/releases`)

Notifications (`/notifications/`)

Downloads / Reports (`/download/`)

5. Global Search (`/search`)

6. Royalty Sources (`/sources`)

7. Source Creator (`/source-creator`)

8. Checklist / Data Quality (`/checklist`)

9. DDEX Distribution (`/ddex`)

10. AI Chat Agent (`/ai`)

11. Merlin Addon (`/merlin`)

12. Data Shares (`/data-shares`)

Publishers (`/publishers`)

Writers (`/writers`)

Musical Works (`/works`)

CWR Export (`/cwr`)

14. Currency Management (`/currencies`)

15. Billing & Subscriptions (`/billing`)

16. Custom Domains (`/domains`)

17. Admin Dashboard (`/admin/dashboard`)

18. Audit Trail (`/api/audit`)

19. Monitoring (`/api/monitoring`)