Skip to main content

​
Overview

The ROOTKey REST API is the default integration model and the fastest path from zero to production. It exposes a JSON API over HTTPS with API key authentication and consistent error schemas, available across dedicated development and production endpoints. No infrastructure setup is required on the client side. Authentication, protocol routing, and blockchain anchoring are handled by ROOTKey’s cloud infrastructure. This model is appropriate for any team building web-native, cloud-native, or service-oriented architectures - and for organisations that want to validate ROOTKey capabilities quickly before committing to a more embedded deployment.

​
Architecture Overview

All API calls are authenticated using an x-api-key header. Test and live keys use the same base URL; the key decides whether a request works on your organization’s test data or its live data. See Test and Live Data for details.

​
Integration Characteristics

​
Typical Use Cases

SaaS Platform Integration

Embed ROOTKey data integrity capabilities directly into a SaaS product - attach proof-of-existence to user-generated content, contracts, or records at creation time.

Backend Microservices

Add tamper-evident logging or validation to individual services within a distributed architecture without additional infrastructure.

Web Application Backends

Validate and anchor documents, forms, or records submitted through web applications - with an audit trail that outlasts the application itself.

Automated Compliance Workflows

Integrate ROOTKey into CI/CD pipelines, data processing jobs, or scheduled compliance tasks - anchoring artefacts at every stage.

​
Integration Considerations

Authentication and key management API keys should be stored as environment secrets and rotated regularly. Test and live keys are distinct and work on separate data, so keep them as separate secrets and never use a test key where a live one is expected. Rate limits and plan quotas Each plan has its own API rate limit, in requests per minute, and some operations, such as listing and restoring deleted items, have limits of their own. Over a rate limit the API answers 429 Too Many Requests with a Retry-After header. Your plan also sets quotas, such as a monthly number of API requests: a request over a quota is refused with usage_limit_exceeded, and sending it again does not help until the quota resets or the plan changes. See Rate Limits for which limits apply. Error handling The API returns structured error responses with machine-readable codes. Branch on errorCode to decide whether to retry, and do not retry every 5xx with backoff. A 429 or a 503 says in its Retry-After header how long to wait; wait that long, then retry. A 500 is different: an upload that failed with a 500 may still have been anchored, and creation_outcome_unknown must never be retried automatically. Retrying a failed request lists which failures are safe to retry and what to check first for an upload; the rest of the Error Reference has the full error schema. Idempotency Operations that anchor data to the blockchain are not inherently idempotent - duplicate submissions result in separate on-chain records. Client-side deduplication should be implemented where appropriate. Asynchronous anchoring Anchoring a file on the blockchain completes after the API call returns: the file starts as PENDING and becomes REGISTERED once the transaction is confirmed. Read the file’s status to follow it - see Anchoring Status.

​
Getting Started

1

Create a ROOTKey account

Sign up at app.rootkey.ai and create your first workspace.
2

Generate an API key

From the dashboard, generate a test API key to begin testing. See API Keys for step-by-step instructions.
3

Make your first API call

Follow the Quickstart guide to create a vault and anchor your first file against https://api.rootkey.ai using your test key.
4

Switch to production

Generate a live API key and update the key in your environment configuration. The base URL stays https://api.rootkey.ai.

Start for free

Start with a test API key, then go live with a live key. No commitment required.

View API Reference

Full endpoint documentation, request schemas, and response examples.