Skip to main content
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