Generate a data download - Royalti.io API

curl --request POST \
  --url https://api.royalti.io/download/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "emails": [
    "user@example.com"
  ],
  "format": [
    "xlsx"
  ],
  "include": [
    "aggregates"
  ],
  "type": "royalty",
  "start": "",
  "end": "",
  "artists": [],
  "user": [],
  "dsp": [],
  "country": []
}
'

{
  "status": "success",
  "message": "Download request accepted and is being processed",
  "data": {
    "downloadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "jobId": "<string>",
    "status": "pending"
  }
}

{
  "status": "error",
  "message": "Validation failed: emails must contain at least 1 valid email address"
}

{
  "status": "error",
  "message": "<string>",
  "code": "<string>",
  "details": {}
}

{
  "status": "error",
  "message": "No data found for the given filters"
}

POST

download

generate

curl --request POST \
  --url https://api.royalti.io/download/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "emails": [
    "user@example.com"
  ],
  "format": [
    "xlsx"
  ],
  "include": [
    "aggregates"
  ],
  "type": "royalty",
  "start": "",
  "end": "",
  "artists": [],
  "user": [],
  "dsp": [],
  "country": []
}
'

{
  "status": "success",
  "message": "Download request accepted and is being processed",
  "data": {
    "downloadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "jobId": "<string>",
    "status": "pending"
  }
}

{
  "status": "error",
  "message": "Validation failed: emails must contain at least 1 valid email address"
}

{
  "status": "error",
  "message": "<string>",
  "code": "<string>",
  "details": {}
}

{
  "status": "error",
  "message": "No data found for the given filters"
}

This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

POST /download/generate Description: Submits a download generation request. The server validates the input, generates BigQuery queries for the requested data, creates a Download record, and queues a background job. Returns immediately with a 202 Accepted response containing the download and job identifiers. Use GET /download/{id}/status to poll for completion. Authorization:

Required role: user or higher

Method: POST Request Body:

emails (required): At least one valid email address to notify on completion
format: Output formats (csv, xlsx, pdf). Defaults to xlsx.
include: Data sheets to include (raw, aggregates, aggregator). Defaults to aggregates.
type: Report type (royalty, accounting, expense). Defaults to royalty.
saleType: Filter by sale type (e.g. Download, Stream).
Filter fields (artists, user, isrc, upc, country, dsp, aggregator) accept either a comma-separated string or an array of strings. Empty arrays and empty strings are ignored.

Code Examples

const response = await fetch('https://api.royalti.io/download/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "ref": "#/components/schemas/GenerateDownloadRequest"
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
  'https://api.royalti.io/download/generate',
  headers={
    'Authorization': f'Bearer {token}'
  },
  json={"ref":"#/components/schemas/GenerateDownloadRequest"}
)

data = response.json()
print(data)

curl -X POST https://api.royalti.io/download/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":"#/components/schemas/GenerateDownloadRequest"}'

Authorizations

Authorization

string

header

required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Body

application/json

emails

string<email>[]

required

Email addresses to notify when the download is ready

Minimum array length: 1

Example:

["user@example.com"]

format

enum<string>[]

Output file formats to generate

Available options:

csv,

xlsx,

pdf

Example:

["csv", "xlsx"]

include

enum<string>[]

Types of data sheets to include in the download

Available options:

raw,

aggregates,

aggregator

Example:

["raw", "aggregates"]

type

enum<string>

default:royalty

Report type to generate

Available options:

royalty,

accounting,

expense

Example:

"royalty"

periodFilterType

enum<string>

Type of period to filter by. Send empty string to omit.

Available options:

accounting,

sale,

start

string

Start date for the report period (YYYY-MM-DD). Empty string is treated as no filter.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2024-01-01"

end

string

End date for the report period (YYYY-MM-DD). Empty string is treated as no filter.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2024-12-31"

artists

Artist IDs to filter by. Accepts a comma-separated string or an array. Empty arrays are ignored.

Example:

["e0dc6000-af34-4071-8a85-dcadace05c36"]

user

User IDs to filter by. Accepts a comma-separated string or an array.

isrc

ISRC codes to filter by. Accepts a comma-separated string or an array.

upc

UPC codes to filter by. Accepts a comma-separated string or an array.

country

Country codes to filter by. Accepts a comma-separated string or an array.

Example:

["US", "GB"]

dsp

DSP/platform names to filter by. Accepts a comma-separated string or an array.

Example:

["Spotify", "Apple Music"]

aggregator

Aggregator/distributor names to filter by. Accepts a comma-separated string or an array.

saleType

string

Filter by sale type (e.g. Download, Stream, Ad-Supported). Empty string is ignored.

Example:

"Stream"

table_name

string

Specific BigQuery table to query. Empty string is ignored.

Response

Download request accepted

status

string

Example:

"success"

message

string

Example:

"Download request accepted and is being processed"

data

object

Show child attributes

​Description

​Code Examples

Authorizations

Body

Response

Description

Code Examples