Skip to main content

​
Overview

The Records API is the structured-data counterpart to Files. Where a file anchors an opaque binary blob, a record anchors a row of typed key/value data — a partner logo entry, an inventory item, a testimonial, an audit event — inside a table. Every record write produces a cryptographic integrity hash and a tamper-evident, per-entity version history, giving you row-level auditability for compliance, forensic, and operational use cases.
Records live in a table — a schema-defined container for structured rows. A table is not a vault: vaults are folders that store files (Files API), whereas tables store records. A table’s schema defines its columns and — critically — its primary key, which drives versioning (see Versioning).

​
Before you start: the two-place setup

Getting records working is a two-place setup — you configure the table in the ROOTKey platform UI first, then use its address + an API key from your application. This is the single most common onboarding snag, so follow it in order.
1

Create a table and define its schema (platform UI)

In the ROOTKey platform, create a table and configure its schema: add each column and pick its type.
The first column is automatically the primary key. It is what groups a record’s versions together (see Versioning). There is currently no way to designate a different column as the key after creation, so choose your first column deliberately — it should be a stable, unique identifier (e.g. id, slug, sku).
2

Copy the table address

Copy the table’s address (0x…). You pass this on every API call — as ownerVault when writing and as vaultAddress when reading.
3

Create an API key (platform UI)

Go to Developer Tools → API Keys, create a key, and copy it. The key is shown only once. See API Keys for details.
4

Wire it into your app

Put the table address and the API key into your application config/environment. You are now ready to POST and GET records against /platform/records.

​
Authentication

All record endpoints authenticate with your API key in the x-api-key header and are scoped to the organization that owns the key.
Test-mode keys operate on an isolated test dataset; see Environments.

​
Versioning

Records use a primary-key versioning model — you don’t need to track version numbers yourself.
  • The table’s primary key is its schema’s key column (until one is explicitly designated, this is the first field, by convention an id).
  • When you POST a record, ROOTKey hashes the value of that key field.
  • If no record with that key exists yet, the record is stored as a new root entity.
  • If a record with the same key already exists, the new write is automatically stored as a new version of that entity — a database-style update. The version’s parentId points to the entity’s root record.
So the simplest — and only — way to create a version is to POST the same primary key again to POST /platform/records. There is no separate version-creation endpoint; versioning is a built-in behaviour of the create route, driven entirely by the primary key.
Versioning only kicks in when the table has a schema and the payload is a keyed object with a non-empty key value. A payload with no key value (or a table with no schema) is stored as a standalone root record.

​
Working with record IDs

POST /platform/records returns { "chainId": … } and does not return the new record’s id. To obtain a record’s id — which you need for versions, history, validations, and delete — read it from List Records: every item carries a reserved __meta object:
Use __meta.id as the parentId for versions, and as the recordId for history / validations / delete.

​
Record data

  • recordData is a JSON object of the columns you want to store. Values are primitives (string, number, boolean, ISO date, null) or nested objects / arrays within the limits below.
  • Limits per record: 1 MB total, 64 KB per string value, 100 properties, 10 levels of nesting, 1,000 elements per array.
  • Keys beginning with __ (and prototype-polluting keys such as __proto__, constructor, prototype) are stripped on ingest — __meta is reserved for ROOTKey.

​
Endpoints

Deletes a record. Provide the recordId (path) and the table’s ownerAddress (query). Once deleted, the record no longer appears in list or fetch responses.

​
Key capabilities

  • Anchor structured, schema-defined rows with row-level integrity hashing.
  • Automatic primary-key versioning — re-writing the same key creates a new version.
  • Full version history, activity/audit history, and validation history per record.
  • Cursor-based pagination and filtering (name, date range, status) on listings.
  • Delete records you no longer need.
  • Files — anchor unstructured documents instead of structured rows.
  • Vaults — a separate concept: vaults store files, tables store records.
  • API Keys — create and scope the key used for the x-api-key header.
  • Protocols — how anchoring behaves under the configured protocol.