Registration

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

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.