Registration

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

Overview

The Registration API enables you to:

• Register provenance claims 🔗 for digital content
• Attach metadata and attributes to claims
• Link claims to NFTs 🔗
• Track registration status through webhooks

Prerequisites

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

• Complete the prerequisites for using the Registrar section.
• Follow the Authentication guide to authenticate your requests.
• Follow the API Guidelines for all REST API requests.

Quick Start

Initiate a file upload with the file’s name and size:

curl -X POST https://api.royal.io/v0/files/upload \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "epic-meme.jpg",
    "size": 13716
  }'

The response will include an upload ID and a URL where you can PUT the file’s contents to upload it:

{
  "id":"01949a3a-c589-7fab-be22-10ae1de60b0d",
  "url":"https://royal-prod-ballmer-inbox.s3-accelerate.amazonaws.com/app/[...truncated...]"
}

Upload the file’s contents to the URL provided in the response:

curl -X PUT https://royal-prod-ballmer-inbox.s3-accelerate.amazonaws.com/app/[...truncated...] \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: image/jpeg" \
  -H "Content-Length: 13716" \
  -d @epic-meme.jpg

Once uploaded, you can do a GET /v0/files/:id to see if the file has been fully ingested. If so, a 200 OK response will be returned with the file’s content hash:

{
  "id":"01949a3a-c589-7fab-be22-10ae1de60b0d",
  "content_hash":"0f72c9b3a4141c769bf6dc69962f221c2cb5bf860487f3257c97781fa4cf323b"
}

Otherwise a 404 is returned.

API Endpoints

Register Provenance Claim

POST /v0/provenance/register

Request Format

Body Fields

Field	Type	Required	Description
originator_id	string	Yes	The Royal ID of the content creator
file_url	string	No*	URL where the content can be accessed
content_hash	string	No*	Blake3 hash (hex encoded, without prefix)
name	string	Yes	Name of the content
description	string	Yes	Description of the content (supports Markdown)
external_url	string	No	URL where users can view the content
image	string	No	Image URL representing the content
multimedia_url	string	No	URL for multimedia or interactive content
metadata	object	No	Additional metadata for the NFT
provenance_attributes	array	No	Additional attributes about the claim
context	object	No	Any additional context passed through to webhooks

• Either file_url or content_hash must be provided.

Example Request Payload

{
  "originator_id": "123",
  "file_url": "https://example.com/content.jpg",
  "name": "Digital Artwork #1",
  "description": "An original digital artwork created with...",
  "external_url": "https://gallery.example.com/artwork/1",
  "image": "https://example.com/preview.jpg",
  "metadata": {
    "artist": "Jane Smith",
    "medium": "Digital",
    "year": 2024
  },
  "provenance_attributes": [
    {
      "type": "ai",
      "data": {
        "service": {
          "account_id": "456",
          "name": "Midjourney",
          "url": "https://midjourney.com"
        },
        "metadata": {
          "prompt": "A serene landscape..."
        }
      }
    }
  ]
}

Response Formats

Success (201 Created)

{
  "id": "reg_123abc..."
}

• HTTP Status: 201 Created
• Header: x-request-id (protocol-level identifier)

Error Response

{
  "error": {
    "type": "validation_error",
    "message": "file_url or content_hash must be provided"
  }
}

Fetch Provenance Claim Status

Endpoint

GET /v0/provenance/register/:id

Description

This endpoint retrieves the status of a provenance claim request by its ID. The request must be authorized for your application, as specified in the authorization header.

Success Response

• Status: 200 OK

• Response Body:

  {
    "app_id": integer,
    "chain_events": [
      {
        // chain event fields without "tags"
      }
    ],
    "content_hash": string,
    "context": object,
    "file_url": string,
    "id": integer,
    "inserted_at": string,
    "state": string,
    "transaction_hash": string,
    "updated_at": string,
    "originator_id": string,
    "nft_metadata": object | null,
    "transaction_receipt": {
      "blockHash": string,
      "blockNumber": integer,
      "contractAddress": string,
      "cumulativeGasUsed": integer,
      "effectiveGasPrice": integer,
      "from": string,
      "gasUsed": integer,
      "logs": [
        {
          "address": string,
          "blockHash": string,
          "blockNumber": integer,
          "data": string,
          "logIndex": integer,
          "removed": boolean,
          "topics": [string],
          "transactionHash": string,
          "transactionIndex": integer
        }
      ],
      "logsBloom": string,
      "status": integer,
      "to": string,
      "transactionHash": string,
      "transactionIndex": integer,
      "type": integer
    }
  }

Error Responses

• 404 Not Found: The specified ID does not exist.
• 401 Unauthorized: The request is not authorized.
• 429 Too Many Requests: Rate limit exceeded.
• 500 Internal Server Error: An error occurred on the server.

Additional Information

For complete API integration tips, please refer to the API Guidelines.

---

Note: This documentation covers only the REST API for registering claims. For general registrar flows like Identity Verification (IDV) and Webhooks, please see the IDV and Webhooks sections in the Registrar documentation.