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

# Compositions

> List and retrieve compositions (musical works) for a project.

## List Compositions

Returns a paginated list of compositions for a project. Compositions represent musical works (songs, soundtracks, etc.) extracted from contract documents.

### Request

```
GET /v1/compositions
```

### Query Parameters

| Parameter         | Type    | Required | Default | Description                                                       |
| ----------------- | ------- | -------- | ------- | ----------------------------------------------------------------- |
| `projectId`       | UUID    | Yes      | —       | The project to list compositions for                              |
| `page`            | integer | No       | `1`     | Page number (1-indexed)                                           |
| `perPage`         | integer | No       | `20`    | Items per page (1–100)                                            |
| `includeProducts` | string  | No       | `false` | Set to `true` to include associated products for each composition |

### Headers

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

### Response

```json theme={null}
{
  "data": {
    "items": [
      {
        "id": "comp-1",
        "name": "Rolling in the Deep",
        "type": "song",
        "writers": ["Adele Adkins", "Paul Epworth"],
        "artists": ["Adele"],
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-06-01T12:00:00Z",
        "products": [
          {
            "name": "21",
            "upc": "123456789012",
            "release_date": "2011-01-24",
            "artists": ["Adele"],
            "source": "spotify",
            "store": "Spotify"
          }
        ]
      }
    ],
    "total_count": 42,
    "page": 1,
    "per_page": 20
  }
}
```

<Note>
  The `products` array only appears when `includeProducts=true`.
</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/compositions?projectId=a1b2c3d4-...&page=1&perPage=50" \
  -H "Authorization: Bearer rp_your_token_here"
```

***

## Get Composition

Returns a single composition by ID.

### Request

```
GET /v1/compositions/{composition_id}
```

### Path Parameters

| Parameter        | Type   | Required | Description        |
| ---------------- | ------ | -------- | ------------------ |
| `composition_id` | string | Yes      | The composition ID |

### Query Parameters

| Parameter         | Type   | Required | Default | Description                                  |
| ----------------- | ------ | -------- | ------- | -------------------------------------------- |
| `projectId`       | UUID   | Yes      | —       | The project the composition belongs to       |
| `includeProducts` | string | No       | `false` | Set to `true` to include associated products |

### Headers

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

### Response

```json theme={null}
{
  "data": {
    "id": "comp-1",
    "name": "Rolling in the Deep",
    "type": "song",
    "writers": ["Adele Adkins", "Paul Epworth"],
    "artists": ["Adele"],
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-06-01T12:00:00Z",
    "products": [
      {
        "name": "21",
        "upc": "123456789012",
        "release_date": "2011-01-24",
        "artists": ["Adele"],
        "source": "spotify",
        "store": "Spotify"
      }
    ]
  }
}
```

### Errors

| Status | Description                                  |
| ------ | -------------------------------------------- |
| `400`  | Missing `projectId`                          |
| `403`  | Token is not scoped to the requested project |
| `404`  | Composition not found                        |

### Example

```bash theme={null}
curl "https://api.royaltyport.com/v1/compositions/comp-1?projectId=a1b2c3d4-..." \
  -H "Authorization: Bearer rp_your_token_here"
```