> ## 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.

# Contracts

> List, retrieve, upload, download, and track contract processing with the SDK.

## list()

Returns a paginated list of contracts for a project. Use the `includes` option to embed sub-resource data inline.

### Signature

```js theme={null}
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

```js theme={null}
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

```js theme={null}
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

```js theme={null}
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

```js theme={null}
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:**

```js theme={null}
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:**

```js theme={null}
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:**

```js theme={null}
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:**

```js theme={null}
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

```js theme={null}
royaltyport.contracts.download(projectId, contractId)
```

### Parameters

| Parameter    | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `projectId`  | `string` | Yes      | The project ID  |
| `contractId` | `number` | Yes      | The contract ID |

### Example

```js theme={null}
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

```js theme={null}
royaltyport.contracts.processes(projectId, contractId)
```

### Parameters

| Parameter    | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `projectId`  | `string` | Yes      | The project ID  |
| `contractId` | `number` | Yes      | The contract ID |

### Example

```js theme={null}
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       |

***

## Extraction Types

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             |