Compositions

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

{
  "data": {
    "items": [
      {
        "id": "comp-1",
        "name": "Rolling in the Deep",
        "type": "song",
        "writers": ["Adele Adkins", "Paul Epworth"],
        "artists": ["Adele"],
        "creators": [
          { "name": "Adele Adkins", "role": "writer" },
          { "name": "Paul Epworth", "role": "writer" }
        ],
        "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"],
            "store": "Spotify"
          }
        ]
      }
    ],
    "total_count": 42,
    "page": 1,
    "per_page": 20
  }
}

The products array only appears when includeProducts=true.

Errors

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

Example

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 its numeric id or its internal_uuid.

Request

GET /v1/compositions/{composition_id}

Path Parameters

Parameter	Type	Required	Description
`composition_id`	string	Yes	The composition’s numeric `id` or its `internal_uuid`

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

{
  "data": {
    "id": "comp-1",
    "name": "Rolling in the Deep",
    "type": "song",
    "writers": ["Adele Adkins", "Paul Epworth"],
    "artists": ["Adele"],
    "creators": [
      { "name": "Adele Adkins", "role": "writer" },
      { "name": "Paul Epworth", "role": "writer" }
    ],
    "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"],
        "store": "Spotify"
      }
    ]
  }
}

Errors

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

Example

curl "https://api.royaltyport.com/v1/compositions/comp-1?projectId=a1b2c3d4-..." \
  -H "Authorization: Bearer rp_your_token_here"

Getting Started

REST API

List Compositions

Request

Query Parameters

Headers

Response

Errors

Example

Get Composition

Request

Path Parameters

Query Parameters

Headers

Response

Errors

Example

​List Compositions

​Request

​Query Parameters

​Headers

​Response

​Errors

​Example

​Get Composition

​Request

​Path Parameters

​Query Parameters

​Headers

​Response

​Errors

​Example

List Compositions

Request

Query Parameters

Headers

Response

Errors

Example

Get Composition

Request

Path Parameters

Query Parameters

Headers

Response

Errors

Example