Skip to main content

​
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

ParameterTypeRequiredDefaultDescription
projectIdstringYes—The project ID
options.pagenumberNo1Page number
options.perPagenumberNo20Items per page (max: 100)
options.includesstring[]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

ParameterTypeRequiredDefaultDescription
projectIdstringYes—The project ID
contractIdnumberYes—The contract ID
options.includesstring[]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

ParameterTypeRequiredDefaultDescription
projectIdstringYes—The project ID
fileBuffer, Uint8Array, Blob, or stringYes—The file to upload. Pass a file path as a string to read from disk.
options.fileNamestringNoInferred from path or upload.pdfThe file name
options.fileTypestringNoapplication/pdfMIME type
options.extractionsstring[]No—Extraction types to run after upload
options.onProgressfunctionNo—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}`);
Upload with extractions: 
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'],
});
Upload from Buffer: 
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',
});
Upload with progress tracking: 
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}%`);
  },
});
The 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

ParameterTypeRequiredDescription
projectIdstringYesThe project ID
contractIdnumberYesThe 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

ParameterTypeRequiredDescription
projectIdstringYesThe project ID
contractIdnumberYesThe 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():
IncludeDescription
entitiesEntities linked to the contract
artistsArtists linked to the contract
writersWriters linked to the contract
royaltiesRoyalty terms extracted from the contract
splitsRevenue split information
costsCost provisions
compensationsCompensation terms
datesKey dates (effective, termination, etc.)
accounting-periodsAccounting period definitions
typesContract type classifications
signaturesSignature information
control-areasControl area definitions
creative-approvalsCreative approval clauses
balancesBalance provisions and terms
recordingsRecordings linked to the contract
compositionsCompositions linked to the contract

​
Extraction Types

Pass any combination of the following values in the extractions option when calling upload():
ExtractionDescription
extract-accounting-periodAccounting period definitions
extract-assetsAsset references
extract-commitmentsCommitment clauses
extract-compensationsCompensation terms
extract-control-areasControl area definitions
extract-costsCost provisions
extract-creative-approvalsCreative approval clauses
extract-datesKey dates (effective, termination, etc.)
extract-royaltiesRoyalty terms
extract-signaturesSignature information
extract-splitsRevenue split information
extract-targetsTarget and threshold clauses
extract-balancesBalance provisions and terms