> ## 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 and retrieve contracts with optional sub-resource includes.

## List Contracts

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

### Request

```
GET /v1/contracts
```

### Query Parameters

| Parameter   | Type    | Required | Default | Description                                    |
| ----------- | ------- | -------- | ------- | ---------------------------------------------- |
| `projectId` | UUID    | Yes      | —       | The project to list contracts for              |
| `page`      | integer | No       | `1`     | Page number (1-indexed)                        |
| `perPage`   | integer | No       | `20`    | Items per page (1–100)                         |
| `includes`  | string  | No       | —       | Comma-separated list of sub-resources to embed |

### Headers

| Header          | Required | Description                                                |
| --------------- | -------- | ---------------------------------------------------------- |
| `Authorization` | Yes      | `Bearer <token>` — must be scoped to the requested project |

### Sub-Resource Includes

Pass a comma-separated list of sub-resource names in the `includes` parameter to embed related data in each contract object:

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

### Response

```json theme={null}
{
  "data": [
    {
      "id": "contract-123",
      "name": "Distribution Agreement",
      "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2025-03-01T12:00:00Z",
      "entities": [
        { "id": "ent-1", "name": "Sony Music Entertainment" }
      ],
      "royalties": [
        { "id": "roy-1", "rate": "18%", "type": "mechanical" }
      ]
    }
  ]
}
```

<Note>
  Sub-resource keys only appear in the response when requested via `includes`. Without `includes`, only the base contract fields are returned.
</Note>

### Errors

| Status | Description                                     |
| ------ | ----------------------------------------------- |
| `400`  | Missing `projectId` or invalid query parameters |
| `403`  | Token is not scoped to the requested project    |

### Example

```bash theme={null}
curl "https://api.royaltyport.com/v1/contracts?projectId=a1b2c3d4-...&page=1&perPage=10&includes=entities,royalties" \
  -H "Authorization: Bearer rp_your_token_here"
```

***

## Get Contract

Returns a single contract by ID, with optional sub-resource includes.

### Request

```
GET /v1/contracts/{contract_id}
```

### Path Parameters

| Parameter     | Type   | Required | Description     |
| ------------- | ------ | -------- | --------------- |
| `contract_id` | string | Yes      | The contract ID |

### Query Parameters

| Parameter   | Type   | Required | Default | Description                                                      |
| ----------- | ------ | -------- | ------- | ---------------------------------------------------------------- |
| `projectId` | UUID   | Yes      | —       | The project the contract belongs to                              |
| `includes`  | string | No       | —       | Comma-separated list of sub-resources to embed (see table above) |

### Headers

| Header          | Required | Description                                                |
| --------------- | -------- | ---------------------------------------------------------- |
| `Authorization` | Yes      | `Bearer <token>` — must be scoped to the requested project |

### Response

```json theme={null}
{
  "data": {
    "id": "contract-123",
    "name": "Distribution Agreement",
    "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2025-03-01T12:00:00Z",
    "entities": [
      { "id": "ent-1", "name": "Sony Music Entertainment" }
    ]
  }
}
```

### Errors

| Status | Description                                     |
| ------ | ----------------------------------------------- |
| `400`  | Missing `projectId` or invalid query parameters |
| `403`  | Token is not scoped to the requested project    |
| `404`  | Contract not found                              |

### Example

```bash theme={null}
curl "https://api.royaltyport.com/v1/contracts/contract-123?projectId=a1b2c3d4-...&includes=entities,artists,royalties" \
  -H "Authorization: Bearer rp_your_token_here"
```