API Endpoints

All examples use the public base URL:

https://api.rosterroyalties.com

Endpoint categories

Statements

Use statement endpoints to list statements, retrieve one statement, retrieve statement lines, and retrieve aggregate summaries.

curl "https://api.rosterroyalties.com/v1/statements?artist_id=artist_123&limit=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "statement_123",
      "artist_id": "artist_123",
      "period": "2026-Q2",
      "currency": "GBP",
      "status": "processed"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

Statement lines

curl "https://api.rosterroyalties.com/v1/statements/statement_123/lines?limit=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Statement aggregates

curl "https://api.rosterroyalties.com/v1/statements/statement_123/aggregates" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Imports

Create an import session before submitting rows.

curl -X POST "https://api.rosterroyalties.com/v1/imports" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Idempotency-Key: import-request-123" \
  -H "Content-Type: application/json" \
  -d '{
    "label_id": "label_123",
    "period": "2026-Q2",
    "currency": "GBP",
    "source_system": "partner_platform",
    "file_name": "royalties.csv"
  }'

Submit rows with stable source_row_key values.

curl -X POST "https://api.rosterroyalties.com/v1/imports/import_123/rows" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "source_row_key": "file-001-row-001",
        "artist_id": "artist_123",
        "statement_id": "statement_123",
        "song_title": "Example Track",
        "isrc": "GBABC2600001",
        "platform": "Spotify",
        "territory": "GB",
        "units": 1000,
        "gross_amount": 12.34,
        "royalty_amount": 8.76,
        "currency": "GBP"
      }
    ]
  }'

Prepared runs

Prepared run endpoints let permitted integrations preview imported royalty groups before committing them.

OAuth

OAuth endpoints are documented in the OAuth 2.0 Guide.

Pagination

List endpoints support limit/offset style pagination where available.

Filtering

Common filters include artist_id, statement_id, period, status, and date ranges where supported.

Public error format

{
  "ok": false,
  "error": {
    "code": "insufficient_scope",
    "message": "This token does not include the required scope."
  }
}

Rate limits

Public rate-limit values have not been confirmed for publication. Integrations should use exponential backoff for 429 responses and avoid unnecessary polling.