Search API

This page describes the Search API endpoints for searching provenance claims and accounts through Royal’s infrastructure. For authentication details, please refer to the Authentication page, and for overall API best practices, see API Guidelines.

Overview

The Search API enables you to:

Search for provenance claims by content hash, name, or other metadata
Search for accounts by username or ID
Perform combined searches across multiple entity types
Paginate through search results

Prerequisites

Before you can use the Search API, you need to:

Follow the Authentication guide to authenticate your requests.
Follow the API Guidelines for all REST API requests.

API Endpoints

Perform Search

POST /v0/provenance/search

This endpoint allows you to search for accounts and provenance claims based on provided search parameters.

Request Headers

Header	Value	Required	Description
Content-Type	application/json	Yes	The format of the request body
Authorization	Bearer {YOUR_API_KEY}	Yes	Your Royal API key

Request Body

The request body should contain a JSON object with the following structure:

{
  "searchParameters": {
    "q": "search term",
    "query_by": "field1,field2",
    "filter_by": "type:account",
    "sort_by": "field:desc",
    "page": 1,
    "per_page": 10
    // Additional search parameters
  },
  "options": {
    // Optional search options
  }
}

Important Search Parameters

Parameter	Type	Required	Description
`q`	string	Yes	The search query term
`query_by`	string	Yes	Comma-separated list of fields to search against
`filter_by`	string	No	Filter conditions for results
`sort_by`	string	No	Fields to sort by, with direction
`page`	number	No	Page number (default: 1)
`per_page`	number	No	Number of results per page (default: 10, max: 250)

For a comprehensive list of available search parameters, refer to the Typesense Search Parameters section.

Response Format

The API returns a raw Typesense response object with the following structure:

{
  "facet_counts": [],
  "found": 42,
  "hits": [
    {
      "document": {
        "id": "account:123",
        "type": "account",
        "username": "user123",
        "custody": "0x1234567890abcdef",
        "psqlId": "123",
        "provenanceClaimCount": 5,
        "dayBucket": 1726012800,
        "hourBucket": 1726088400,
        "createdAt": "1726089465",
        "updatedAt": "1726089465"
        // Additional fields
      },
      "highlights": [
        {
          "field": "username",
          "matched_tokens": ["user123"],
          "snippet": "<mark>user123</mark>"
        }
      ],
      "text_match": 578730123365712000,
      "text_match_info": {
        "best_field_score": "1108091339008",
        "best_field_weight": 15,
        "fields_matched": 1,
        "score": "578730123365711993",
        "tokens_matched": 1
      }
    }
    // More hits
  ],
  "out_of": 7359,
  "page": 1,
  "request_params": {
    "collection_name": "provenanceEntities",
    "per_page": 10,
    "q": "user123"
  },
  "search_time_ms": 1
}

Note: This is the raw Typesense response format. The SearchClient class in the TypeScript SDK simplifies this response by transforming it into a more accessible structure with data, total, and numPages properties.

Example Request

curl -X POST "https://api.royal.io/v0/provenance/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -d '{
    "searchParameters": {
      "q": "Alice",
      "query_by": "username,psqlId,contentHash,metadata.name,custody",
      "page": 1,
      "per_page": 10
    }
  }'

Example Response

{
  "facet_counts": [],
  "found": 2,
  "hits": [
    {
      "document": {
        "id": "account:abc123",
        "type": "account",
        "username": "alice",
        "custody": "0x1234567890abcdef",
        "provenanceClaimCount": 5,
        "originatedProvenanceClaimCount": 3,
        "registeredProvenanceClaimCount": 2,
        "psqlId": "10001",
        "recovery": "recovery_string",
        "dayBucket": 1675612800,
        "hourBucket": 1675612800,
        "createdAt": "1673793751",
        "updatedAt": "1676889917"
      },
      "highlights": [
        {
          "field": "username",
          "matched_tokens": ["alice"],
          "snippet": "<mark>alice</mark>"
        }
      ],
      "text_match": 578730123365712000,
      "text_match_info": {
        "best_field_score": "1108091339008",
        "best_field_weight": 15,
        "fields_matched": 1,
        "score": "578730123365711993",
        "tokens_matched": 1
      }
    },
    {
      "document": {
        "id": "provenanceClaim:def456",
        "type": "provenanceClaim",
        "psqlId": "20001",
        "originatorId": "abc123",
        "originatorUsername": "alice",
        "registrarId": "xyz789",
        "originatorAddress": "0x1234567890abcdef",
        "registrarAddress": "0x0987654321fedcba",
        "registrarUsername": "registrar01",
        "contentHash": "0f72c9b3a4141c769bf6dc69962f221c2cb5bf860487f3257c97781fa4cf323b",
        "metadata": {
          "name": "Digital Artwork #1",
          "description": "An original artwork created by Alice"
        },
        "dayBucket": 1678435200,
        "hourBucket": 1678435200,
        "createdAt": "1678446765",
        "updatedAt": "1678446765"
      },
      "highlights": [
        {
          "field": "originatorUsername",
          "matched_tokens": ["alice"],
          "snippet": "<mark>alice</mark>"
        }
      ],
      "text_match": 478730123365712000,
      "text_match_info": {
        "best_field_score": "908091339008",
        "best_field_weight": 10,
        "fields_matched": 1,
        "score": "478730123365711993",
        "tokens_matched": 1
      }
    }
  ],
  "out_of": 7359,
  "page": 1,
  "request_params": {
    "collection_name": "provenanceEntities",
    "per_page": 10,
    "q": "alice"
  },
  "search_time_ms": 2
}

Search Accounts

To search specifically for accounts, you can use the same endpoint with a filter:

curl -X POST "https://api.royal.io/v0/provenance/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -d '{
    "searchParameters": {
      "q": "alice",
      "query_by": "username,psqlId,custody",
      "filter_by": "type:account",
      "page": 1,
      "per_page": 10
    }
  }'

Search Provenance Claims

To search specifically for provenance claims:

curl -X POST "https://api.royal.io/v0/provenance/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -d '{
    "searchParameters": {
      "q": "artwork",
      "query_by": "metadata.name,originatorUsername,psqlId,contentHash",
      "filter_by": "type:provenanceClaim",
      "page": 1,
      "per_page": 10
    }
  }'

Search by Content Hash

To find a specific provenance claim by its content hash:

curl -X POST "https://api.royal.io/v0/provenance/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -d '{
    "searchParameters": {
      "q": "0f72c9b3a4141c769bf6dc69962f221c2cb5bf860487f3257c97781fa4cf323b",
      "query_by": "contentHash",
      "filter_by": "type:provenanceClaim",
      "page": 1,
      "per_page": 10
    }
  }'

Search Claims by Originator

To find all claims created by a specific originator:

curl -X POST "https://api.royal.io/v0/provenance/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -d '{
    "searchParameters": {
      "q": "*",
      "query_by": "originatorId,registrarId",
      "filter_by": "type:provenanceClaim && originatorId:123",
      "sort_by": "psqlId:desc",
      "page": 1,
      "per_page": 10
    }
  }'

Error Handling

The Search API will return appropriate HTTP status codes based on the nature of any errors:

400 Bad Request: The request was improperly formatted or had invalid parameters
401 Unauthorized: Authentication failed (invalid API key)
403 Forbidden: Permission denied for the requested operation
404 Not Found: The requested resource was not found
500 Internal Server Error: An unexpected error occurred on the server

When errors occur, the response body will contain more details:

{
  "error": {
    "type": "validation_error",
    "message": "Search parameter 'q' is required"
  }
}

Typesense Search Parameters

Since the Search API is built on Typesense, you can use a wide range of search parameters to customize your queries. Below are some of the most commonly used parameters:

Query Parameters

Parameter	Required	Description
`q`	Yes	The query text to search for
`query_by`	Yes	Fields to search against, comma-separated
`filter_by`	No	Filter conditions for refining results
`sort_by`	No	Fields to sort by, with optional direction (:asc or :desc)
`facet_by`	No	Fields to facet by, comma-separated
`max_facet_values`	No	Maximum number of facet values to return (default: 10)
`facet_query`	No	Filter facet values returned

Pagination Parameters

Parameter	Required	Description
`page`	No	Page number, starting from 1 (default: 1)
`per_page`	No	Number of results per page (default: 10, max: 250)
`offset`	No	Alternative to page, specifies starting point
`limit`	No	Alternative to per_page, specifies max results

Typo Tolerance Parameters

Parameter	Required	Description
`num_typos`	No	Maximum number of typographical errors allowed (0, 1, or 2)
`min_len_1typo`	No	Minimum word length for 1-typo correction
`min_len_2typo`	No	Minimum word length for 2-typo correction

Ranking Parameters

Parameter	Required	Description
`query_by_weights`	No	Relative importance of fields specified in query_by
`prioritize_exact_match`	No	Whether exact matches should be ranked higher
`prioritize_token_position`	No	Whether tokens appearing earlier should be ranked higher
`text_match_type`	No	How text relevancy is calculated (max_score or sum_score)

For a comprehensive list of all available parameters and detailed descriptions, refer to the Typesense Search API documentation 🔗.