Skip to main content
GET
/
work
/
works
List works
curl --request GET \
  --url https://api.royalti.io/work/works \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.royalti.io/work/works"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.royalti.io/work/works', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.royalti.io/work/works",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.royalti.io/work/works"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "Bearer <token>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.royalti.io/work/works")
.header("Authorization", "Bearer <token>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.royalti.io/work/works")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tenantId": 123,
    "workTitle": "<string>",
    "alternativeTitles": [
      {}
    ],
    "iswc": "<string>",
    "libraryCatalogueName": "<string>",
    "originalWorkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "languageCode": "<string>",
    "musicalWorkDistributionCategory": "<string>",
    "duration": 123,
    "recorded": true,
    "versionType": "<string>",
    "excerptType": "<string>",
    "compositeType": "<string>",
    "musicArrangement": "<string>",
    "lyricAdaptation": "<string>",
    "performers": [
      {}
    ],
    "recordings": [
      {}
    ],
    "copyrightDate": "2023-12-25",
    "copyrightNumber": "<string>",
    "grandRights": true,
    "compositePart": true,
    "compositeWorkId": "<string>",
    "compositeWorkTitle": "<string>",
    "compositeWorkIswc": "<string>",
    "compositeWorkDuration": 123,
    "compositeWorkShare": 123,
    "metadata": {},
    "workType": "<string>",
    "arrangementType": "<string>",
    "instrumentation": [
      "<string>"
    ],
    "componentType": "<string>",
    "isArrangement": true,
    "isAdaptation": true,
    "hasLyricModification": true,
    "isNonLyricModification": true,
    "submitterWorkNumber": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "writerCount": 123,
    "publishingStatus": {
      "isSkeleton": true,
      "writerCount": 123,
      "missingShares": true,
      "seededDefaults": [
        "<string>"
      ]
    },
    "registrations": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "registrationStatus": "<string>",
        "societyCode": "<string>",
        "statusDate": "2023-11-07T05:31:56Z"
      }
    ],
    "workWriters": [
      {
        "writerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "writerRole": "<string>"
      }
    ]
  }
]
{
"status": "error",
"message": "<string>",
"code": "<string>",
"details": {}
}
{
"status": "error",
"message": "<string>",
"code": "<string>",
"details": {}
}
{
"status": "error",
"message": "<string>",
"code": "<string>",
"details": {}
}
This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

GET /work/works Description: Lists the tenant’s CWRWork rows. Response is a BARE ARRAY (not an envelope) — existing FE and cross-tenant consumers depend on that shape. Each row is annotated with a computed writerCount and publishingStatus. Supports free-text search/q (title, ISWC, submitter work number), writerId scoping (only that writer’s works, with the writer’s role surfaced per row), workType exact filter, and registrationStatus facet (any WorkRegistration status value, or unregistered for works with no registration row at all). Optional page/size (default 20, capped at 100). Authorization:
  • Required role: user or higher
Method: GET

Code Examples

const response = await fetch('https://api.royalti.io/work/works', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const data = await response.json();
console.log(data);
import requests

response = requests.get(
  'https://api.royalti.io/work/works',
  headers={
    'Authorization': f'Bearer {token}'
  },
)

data = response.json()
print(data)
curl -X GET https://api.royalti.io/work/works \
  -H "Authorization: Bearer YOUR_TOKEN" \

Authorizations

Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Query Parameters

Matches workTitle, iswc, or submitterWorkNumber (case-insensitive). q is accepted as an alias.

writerId
string<uuid>
workType
string
registrationStatus
enum<string>
Available options:
pending,
submitted,
registered,
rejected,
conflict,
cancelled,
unregistered
page
integer
size
integer

Response

Works retrieved

id
string<uuid>
tenantId
integer
workTitle
string
alternativeTitles
object[]
iswc
string | null

International Standard Musical Work Code (max 13 chars)

libraryCatalogueName
string | null
originalWorkId
string<uuid> | null
languageCode
string
musicalWorkDistributionCategory
string
duration
integer

Seconds

recorded
boolean
versionType
string
excerptType
string
compositeType
string
musicArrangement
string
lyricAdaptation
string
performers
object[]
recordings
object[]

CWR "recording detail" blocks embedded on the work (distinct from the WorkRecording junction table / WorkRecordings below)

grandRights
boolean
compositePart
boolean
compositeWorkId
string | null
compositeWorkTitle
string | null
compositeWorkIswc
string | null
compositeWorkDuration
integer | null
compositeWorkShare
number | null
metadata
object

Includes completeness (complete/skeleton), source (e.g. publishing-bootstrap), seededDefaults, origin.library

workType
string
arrangementType
string
instrumentation
string[]
componentType
string
isArrangement
boolean
isAdaptation
boolean
hasLyricModification
boolean
isNonLyricModification
boolean
submitterWorkNumber
string | null
createdAt
string<date-time>
updatedAt
string<date-time>
writerCount
integer
publishingStatus
object

Derived, response-only publishing-readiness signal (WP-P4). Computed from CWRWork.metadata and the work's writer links — never persisted as a column.

registrations
object[]

Society registrations for the work (id, registrationStatus, societyCode, statusDate only)

workWriters
object[]

Present only when the request is scoped with ?writerId= — that writer's role on this work