Global search across all entities

curl --request GET \
  --url https://api.royalti.io/search \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.royalti.io/search', 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/search",
  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/search"

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

}

require 'uri'
require 'net/http'

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

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

{
  "status": "success",
  "message": "Search results retrieved",
  "data": {
    "results": [
      {
        "entity_type": "artist",
        "entity_id": "550e8400-e29b-41d4-a716-446655440000",
        "display_title": "Drake",
        "display_subtitle": "OVO Sound",
        "metadata": {
          "artistImg": "https://storage.googleapis.com/example.jpg"
        },
        "rank": 0.95
      },
      {
        "entity_type": "asset",
        "entity_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "display_title": "Drake - Hotline Bling",
        "display_subtitle": "Drake",
        "metadata": {
          "type": "Audio"
        },
        "rank": 0.72
      },
      {
        "entity_type": "product",
        "entity_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "display_title": "Views",
        "display_subtitle": "Drake",
        "metadata": {
          "format": "Album",
          "status": "active",
          "type": "Audio"
        },
        "rank": 0.65
      }
    ],
    "total": 3
  }
}

GET

Global search across all entities

curl --request GET \
  --url https://api.royalti.io/search \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.royalti.io/search', 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/search",
  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/search"

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

}

require 'uri'
require 'net/http'

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

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

{
  "status": "success",
  "message": "Search results retrieved",
  "data": {
    "results": [
      {
        "entity_type": "artist",
        "entity_id": "550e8400-e29b-41d4-a716-446655440000",
        "display_title": "Drake",
        "display_subtitle": "OVO Sound",
        "metadata": {
          "artistImg": "https://storage.googleapis.com/example.jpg"
        },
        "rank": 0.95
      },
      {
        "entity_type": "asset",
        "entity_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "display_title": "Drake - Hotline Bling",
        "display_subtitle": "Drake",
        "metadata": {
          "type": "Audio"
        },
        "rank": 0.72
      },
      {
        "entity_type": "product",
        "entity_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "display_title": "Views",
        "display_subtitle": "Drake",
        "metadata": {
          "format": "Album",
          "status": "active",
          "type": "Audio"
        },
        "rank": 0.65
      }
    ],
    "total": 3
  }
}

This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

Results are ranked by relevance with weighted fields:

Weight A (highest): Title/name fields (artist name, track title, product title)
Weight B: Identifiers (ISRC, UPC, external ID, catalog number)
Weight C: Metadata (genre, label, format, publisher)

The search uses English stemming by default. If no exact matches are found, it automatically falls back to prefix matching (e.g., typing “dra” will match “Drake”). Results are cached for 60 seconds per tenant/query combination. Authorization:

Required role: user or higher

Code Examples

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

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

import requests

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

data = response.json()
print(data)

curl -X GET https://api.royalti.io/search \
  -H "Authorization: Bearer YOUR_TOKEN" \

Authorizations

Authorization

string

header

required

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

Query Parameters

string

required

Search query (minimum 2 characters)

Minimum string length: 2

types

enum<string>[]

Comma-separated list of entity types to filter results. If omitted, all types are searched.

Available options:

artist,

asset,

product,

label,

split,

release,

work,

writer,

publisher,

user

limit

integer

default:20

Maximum number of results to return (default 20, max 100)

Required range: 1 <= x <= 100

offset

integer

default:0

Number of results to skip for pagination (default 0)

Required range: x >= 0

Response

Search results retrieved successfully

status

string

Example:

"success"

message

string

Example:

"Search results retrieved"

data

object

Show child attributes

​Description

​Code Examples

Authorizations

Query Parameters

Response

Description

Code Examples