Documentation Index
Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt
Use this file to discover all available pages before exploring further.
list()
Returns a paginated list of contracts for a project. Use the includes option to embed sub-resource data inline.
Signature
royaltyport.contracts.list(projectId, options?)
Parameters
| Parameter | Type | Required | Default | Description |
|---|
projectId | string | Yes | — | The project ID |
options.page | number | No | 1 | Page number |
options.perPage | number | No | 20 | Items per page (max: 100) |
options.includes | string[] | No | — | Sub-resources to embed in each contract |
Example
import { Royaltyport } from '@royaltyport/sdk';
const royaltyport = new Royaltyport({
apiKey: 'rp_your_token_here',
});
const { data } = await royaltyport.contracts.list('project-id', {
perPage: 50,
includes: ['entities', 'royalties', 'dates'],
});
for (const contract of data.items) {
console.log(`${contract.file_name} (ID: ${contract.id})`);
}
get()
Returns a single contract by ID, with optional sub-resource includes.
Signature
royaltyport.contracts.get(projectId, contractId, options?)
Parameters
| Parameter | Type | Required | Default | Description |
|---|
projectId | string | Yes | — | The project ID |
contractId | number | Yes | — | The contract ID |
options.includes | string[] | No | — | Sub-resources to embed |
Example
import { Royaltyport } from '@royaltyport/sdk';
const royaltyport = new Royaltyport({
apiKey: 'rp_your_token_here',
});
const { data: contract } = await royaltyport.contracts.get('project-id', 123, {
includes: ['entities', 'artists', 'royalties', 'splits'],
});
console.log(contract.file_name);
upload()
Uploads a contract PDF to a project. The file is stored and queued for processing. You can optionally request specific extractions to run automatically after upload.
Signature
royaltyport.contracts.upload(projectId, file, options?)
Parameters
| Parameter | Type | Required | Default | Description |
|---|
projectId | string | Yes | — | The project ID |
file | Buffer, Uint8Array, Blob, or string | Yes | — | The file to upload. Pass a file path as a string to read from disk. |
options.fileName | string | No | Inferred from path or upload.pdf | The file name |
options.fileType | string | No | application/pdf | MIME type |
options.extractions | string[] | No | — | Extraction types to run after upload |
options.onProgress | function | No | — | Upload progress callback |
Examples
Upload from file path:
import { Royaltyport } from '@royaltyport/sdk';
const royaltyport = new Royaltyport({
apiKey: 'rp_your_token_here',
});
const { data } = await royaltyport.contracts.upload('project-id', './contract.pdf');
console.log(`Staging ID: ${data.staging_id}`);
console.log(`Stage: ${data.staging_stage}`);
import { Royaltyport } from '@royaltyport/sdk';
const royaltyport = new Royaltyport({
apiKey: 'rp_your_token_here',
});
const { data } = await royaltyport.contracts.upload('project-id', './contract.pdf', {
extractions: ['extract-royalties', 'extract-dates', 'extract-splits'],
});
import { readFileSync } from 'node:fs';
import { Royaltyport } from '@royaltyport/sdk';
const royaltyport = new Royaltyport({
apiKey: 'rp_your_token_here',
});
const buffer = readFileSync('./contract.pdf');
const { data } = await royaltyport.contracts.upload('project-id', buffer, {
fileName: 'contract.pdf',
});
import { Royaltyport } from '@royaltyport/sdk';
const royaltyport = new Royaltyport({
apiKey: 'rp_your_token_here',
});
const { data } = await royaltyport.contracts.upload('project-id', './contract.pdf', {
extractions: ['extract-royalties'],
onProgress: (event) => {
console.log(`Upload progress: ${event.percent}%`);
},
});
onProgress callback receives an object with bytesUploaded, bytesTotal, and percent fields.
download()
Returns a pre-signed download URL for a contract file.
Signature
royaltyport.contracts.download(projectId, contractId)
Parameters
| Parameter | Type | Required | Description |
|---|
projectId | string | Yes | The project ID |
contractId | number | Yes | The contract ID |
Example
import { Royaltyport } from '@royaltyport/sdk';
const royaltyport = new Royaltyport({
apiKey: 'rp_your_token_here',
});
const { data } = await royaltyport.contracts.download('project-id', 123);
console.log('Download URL:', data.url);
console.log('Expires:', data.expires_at);
processes()
Returns the processing status for a contract, including staging and extraction progress.
Signature
royaltyport.contracts.processes(projectId, contractId)
Parameters
| Parameter | Type | Required | Description |
|---|
projectId | string | Yes | The project ID |
contractId | number | Yes | The contract ID |
Example
import { Royaltyport } from '@royaltyport/sdk';
const royaltyport = new Royaltyport({
apiKey: 'rp_your_token_here',
});
const { data: status } = await royaltyport.contracts.processes('project-id', 123);
console.log('Staging done:', status.staging_done);
console.log('Extraction done:', status.extraction_done);
console.log('Stage:', status.staging_processes.stage);
Include Fields
Pass any combination of the following values in the includes option when calling list() or get():
| Include | Description |
|---|
entities | Entities linked to the contract |
artists | Artists linked to the contract |
writers | Writers linked to the contract |
royalties | Royalty terms extracted from the contract |
splits | Revenue split information |
costs | Cost provisions |
compensations | Compensation terms |
dates | Key dates (effective, termination, etc.) |
accounting-periods | Accounting period definitions |
types | Contract type classifications |
signatures | Signature information |
control-areas | Control area definitions |
creative-approvals | Creative approval clauses |
balances | Balance provisions and terms |
recordings | Recordings linked to the contract |
compositions | Compositions linked to the contract |
Pass any combination of the following values in the extractions option when calling upload():
| Extraction | Description |
|---|
extract-accounting-period | Accounting period definitions |
extract-assets | Asset references |
extract-commitments | Commitment clauses |
extract-compensations | Compensation terms |
extract-control-areas | Control area definitions |
extract-costs | Cost provisions |
extract-creative-approvals | Creative approval clauses |
extract-dates | Key dates (effective, termination, etc.) |
extract-royalties | Royalty terms |
extract-signatures | Signature information |
extract-splits | Revenue split information |
extract-targets | Target and threshold clauses |
extract-balances | Balance provisions and terms |
