Projects

List Projects

Returns all projects accessible to the authenticated token.

Organization-scoped tokens return all projects. Project-scoped tokens return only their assigned project. See Token Scope for details.

Request

GET /v1/projects

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <token>`

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Record Label Ltd",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-02-20T08:15:00Z"
    }
  ]
}

Example

curl https://api.royaltyport.com/v1/projects \
  -H "Authorization: Bearer rp_your_token_here"

Get Project

Returns a single project by ID.

Request

GET /v1/projects/{project_id}

Path Parameters

Parameter	Type	Required	Description
`project_id`	UUID	Yes	The project ID

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <token>`

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Record Label Ltd",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-20T08:15:00Z"
  }
}

Errors

Status	Description
`404`	Project not found or does not belong to the token’s organization

Example

curl https://api.royaltyport.com/v1/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer rp_your_token_here"

Search Project

Search across all resources in a project — contracts, entities, artists, writers, recordings, and compositions.

Request

GET /v1/projects/{project_id}/search

Path Parameters

Parameter	Type	Required	Description
`project_id`	UUID	Yes	The project ID

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (1–500 characters)

Headers

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

Response

Results are grouped by resource type. data is an object keyed by resource — recordings, compositions, contracts, entities, artists, and writers — and each key holds an array of matches for that type. Every key is always present; a type with no matches returns an empty array. Matched text (names, file names, matched keywords) is highlighted by wrapping the matching span in <<…>>.

{
  "data": {
    "recordings": [
      {
        "id": "rec-1",
        "name": "Rolling in the Deep",
        "duration_ms": 228000,
        "artists": ["Adele"],
        "matched_keywords": "Album: <<21>>",
        "is_metadata_match": true,
        "rank": 7.0
      }
    ],
    "compositions": [
      {
        "id": "comp-1",
        "name": "<<Rolling>> in the Deep",
        "writers": ["Adele Adkins", "Paul Epworth"],
        "artists": ["Adele"],
        "matched_keywords": "<<Rolling>> in the Deep",
        "is_metadata_match": false,
        "rank": 9.0
      }
    ],
    "contracts": [
      {
        "id": "contract-123",
        "matched_file_name": "Distribution Agreement - <<Sony Music>>.pdf",
        "matched_keywords": "…exclusive distribution rights granted to <<Sony Music>> for the term…",
        "is_content_match": true,
        "rank": 0.0952381
      }
    ],
    "entities": [
      { "id": "entity-1", "name": "<<Sony Music>> Entertainment" }
    ],
    "artists": [
      { "id": "artist-456", "name": "<<Sony Music>>" }
    ],
    "writers": [
      { "id": "writer-1", "name": "Max Martin" }
    ]
  }
}

Response Fields

Item shapes differ by resource type:

Resource	Item fields
`recordings`	`id`, `name`, `duration_ms`, `artists`, `matched_keywords`, `is_metadata_match`, `rank`
`compositions`	`id`, `name`, `writers`, `artists`, `matched_keywords`, `is_metadata_match`, `rank`
`contracts`	`id`, `matched_file_name`, `matched_keywords`, `is_content_match`, `rank`
`entities`	`id`, `name`
`artists`	`id`, `name`
`writers`	`id`, `name`

rank is a relevance score (higher is more relevant) — there is no score field, and results are not returned as a flat array with a type field.

Errors

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

Example

curl "https://api.royaltyport.com/v1/projects/a1b2c3d4-.../search?q=Sony%20Music" \
  -H "Authorization: Bearer rp_your_token_here"

Getting Started

REST API

List Projects

Request

Headers

Response

Example

Get Project

Request

Path Parameters

Headers

Response

Errors

Example

Search Project

Request

Path Parameters

Query Parameters

Headers

Response

Response Fields

Errors

Example

​List Projects

​Request

​Headers

​Response

​Example

​Get Project

​Request

​Path Parameters

​Headers

​Response

​Errors

​Example

​Search Project

​Request

​Path Parameters

​Query Parameters

​Headers

​Response

​Response Fields

​Errors

​Example

List Projects

Request

Headers

Response

Example

Get Project

Request

Path Parameters

Headers

Response

Errors

Example

Search Project

Request

Path Parameters

Query Parameters

Headers

Response

Response Fields

Errors

Example