Registration API

Esta página aún no está disponible en tu idioma.

The Registration API allows you to register provenance claims through Royal’s infrastructure. This guide will help you understand and implement the API effectively.

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 have:

Registrar Setup

A Royal registrar account configured in the Royal Console
Your application secret key for authentication
Webhook endpoints configured (if using webhooks)

User Identity and Delegation

The user must have delegated authority to your registrar 🔗
You need the user’s Royal ID

All of this can of course be done manually, but we recommend you offload all of this to Royals IDV flow where this is all taken care of for you.

Getting User Authorization

To obtain user authorization:

Redirect users to the IDV flow: https://royal.io/idv/<your-registrar-username>
After successful IDV, you’ll receive:
- The user’s Royal ID
- Confirmation of delegation
- A signed token for verification
Store the user’s Royal ID for use in registration calls

See the IDV Documentation for detailed implementation guidance.

Quick Start

curl -X POST https://api.royal.io/v0/provenance/register \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "originator_id": "123",
    "file_url": "https://example.com/content.jpg",
    "name": "My Content",
    "description": "Description of my content"
  }'

Authentication

All API requests require authentication using your application secret key:

Authorization: Bearer ryl_sk_YOUR_SECRET_KEY

You can find your secret key in the Royal Console 🔗 under Services > Indexer Configuration.

API Endpoints

POST https://api.royal.io/v0/provenance/register

Request Format

Headers

Content-Type: application/json
Authorization: Bearer ryl_sk_YOUR_SECRET_KEY

Request Body

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 of the content (hex encoded, no 0x 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	URL to an image representing the content
`multimedia_url`	string	No	URL to multimedia attachment or interactive content
`metadata`	object	No	Additional metadata for the NFT
`provenance_attributes`	array	No	Additional attributes about the claim
`context`	object	No	Additional context passed through to webhooks

* Either file_url or content_hash must be provided

Example Request

{
  "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..."
        }
      }
    }
  ]
}

Provenance Attributes

You should include provenance attributes 🔗 in your metadata to describe the content and information related to it’s provenance.

Response Format

Success Response (201 Created)

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

The response includes:

HTTP Status: 201 Created
Header: x-request-id - Protocol-level identifier
Body: Contains API-level identifier

Error Response

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

Best Practices

Early Registration: Register claims as close to creation time as possible to establish the strongest provenance.
Content Access: When using file_url, ensure the content remains accessible at that URL for Royal to hash it.
Rich Metadata: Include comprehensive metadata and attributes to provide context about the creation process.
Webhook Integration: Implement webhook handlers to track registration status and handle failures gracefully.

Support

Need help? Contact us: