Skip to main content
GET
/
search
Global search across all entities
curl --request GET \
  --url https://api.royalti.io/search \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.royalti.io/search"

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

}
HttpResponse<String> response = Unirest.get("https://api.royalti.io/search")
  .header("Authorization", "Bearer <token>")
  .asString();
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

​
q
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