Create record

curl --request POST \
  --url https://api.rootkey.ai/api-v1/platform/records \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "ownerVault": "0xdf67CA8286510997567685c0385ECeAb11C23C92",
  "recordData": {
    "id": "prod-001",
    "name": "ACME Corp",
    "logoUrl": "https://media.example.com/acme.svg",
    "active": true
  }
}
'

import requests

url = "https://api.rootkey.ai/api-v1/platform/records"

payload = {
    "ownerVault": "0xdf67CA8286510997567685c0385ECeAb11C23C92",
    "recordData": {
        "id": "prod-001",
        "name": "ACME Corp",
        "logoUrl": "https://media.example.com/acme.svg",
        "active": True
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ownerVault: '0xdf67CA8286510997567685c0385ECeAb11C23C92',
    recordData: {
      id: 'prod-001',
      name: 'ACME Corp',
      logoUrl: 'https://media.example.com/acme.svg',
      active: true
    }
  })
};

fetch('https://api.rootkey.ai/api-v1/platform/records', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.rootkey.ai/api-v1/platform/records",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ownerVault' => '0xdf67CA8286510997567685c0385ECeAb11C23C92',
    'recordData' => [
        'id' => 'prod-001',
        'name' => 'ACME Corp',
        'logoUrl' => 'https://media.example.com/acme.svg',
        'active' => true
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rootkey.ai/api-v1/platform/records"

	payload := strings.NewReader("{\n  \"ownerVault\": \"0xdf67CA8286510997567685c0385ECeAb11C23C92\",\n  \"recordData\": {\n    \"id\": \"prod-001\",\n    \"name\": \"ACME Corp\",\n    \"logoUrl\": \"https://media.example.com/acme.svg\",\n    \"active\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.rootkey.ai/api-v1/platform/records")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ownerVault\": \"0xdf67CA8286510997567685c0385ECeAb11C23C92\",\n  \"recordData\": {\n    \"id\": \"prod-001\",\n    \"name\": \"ACME Corp\",\n    \"logoUrl\": \"https://media.example.com/acme.svg\",\n    \"active\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rootkey.ai/api-v1/platform/records")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ownerVault\": \"0xdf67CA8286510997567685c0385ECeAb11C23C92\",\n  \"recordData\": {\n    \"id\": \"prod-001\",\n    \"name\": \"ACME Corp\",\n    \"logoUrl\": \"https://media.example.com/acme.svg\",\n    \"active\": true\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "chainId": 137
}

{
  "error": {
    "requestId": "<string>",
    "message": "<string>",
    "errorCode": "<string>",
    "docUrl": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "requestId": "<string>",
    "message": "<string>",
    "errorCode": "<string>",
    "docUrl": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

Records

Create record

Creates a structured, integrity-hashed record inside a table.

This endpoint also creates versions. ROOTKey groups a record’s versions by the table’s primary key — the schema’s key column, which (until one is explicitly designated) is the first field, by convention an id.

If no record with that key value exists yet, the payload is stored as a new root record.
If a record with the same key value already exists, the payload is stored as a new version of that entity (a database-style update). The version’s parentId is set to the existing root automatically — you do not send it.

So to update an entity, simply POST the same primary key again — there is no separate version-creation endpoint; versioning is a built-in behaviour of this route.

Versioning only applies when the table has a schema and the payload is a keyed object with a non-empty key value; otherwise the record is stored as a standalone root.

Response: returns only { chainId }. The new record’s id is not returned here — read it from GET /platform/records (the __meta.id field of each item).

POST

platform

records

Create record

curl --request POST \
  --url https://api.rootkey.ai/api-v1/platform/records \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "ownerVault": "0xdf67CA8286510997567685c0385ECeAb11C23C92",
  "recordData": {
    "id": "prod-001",
    "name": "ACME Corp",
    "logoUrl": "https://media.example.com/acme.svg",
    "active": true
  }
}
'

import requests

url = "https://api.rootkey.ai/api-v1/platform/records"

payload = {
    "ownerVault": "0xdf67CA8286510997567685c0385ECeAb11C23C92",
    "recordData": {
        "id": "prod-001",
        "name": "ACME Corp",
        "logoUrl": "https://media.example.com/acme.svg",
        "active": True
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ownerVault: '0xdf67CA8286510997567685c0385ECeAb11C23C92',
    recordData: {
      id: 'prod-001',
      name: 'ACME Corp',
      logoUrl: 'https://media.example.com/acme.svg',
      active: true
    }
  })
};

fetch('https://api.rootkey.ai/api-v1/platform/records', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.rootkey.ai/api-v1/platform/records",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ownerVault' => '0xdf67CA8286510997567685c0385ECeAb11C23C92',
    'recordData' => [
        'id' => 'prod-001',
        'name' => 'ACME Corp',
        'logoUrl' => 'https://media.example.com/acme.svg',
        'active' => true
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rootkey.ai/api-v1/platform/records"

	payload := strings.NewReader("{\n  \"ownerVault\": \"0xdf67CA8286510997567685c0385ECeAb11C23C92\",\n  \"recordData\": {\n    \"id\": \"prod-001\",\n    \"name\": \"ACME Corp\",\n    \"logoUrl\": \"https://media.example.com/acme.svg\",\n    \"active\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.rootkey.ai/api-v1/platform/records")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ownerVault\": \"0xdf67CA8286510997567685c0385ECeAb11C23C92\",\n  \"recordData\": {\n    \"id\": \"prod-001\",\n    \"name\": \"ACME Corp\",\n    \"logoUrl\": \"https://media.example.com/acme.svg\",\n    \"active\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rootkey.ai/api-v1/platform/records")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ownerVault\": \"0xdf67CA8286510997567685c0385ECeAb11C23C92\",\n  \"recordData\": {\n    \"id\": \"prod-001\",\n    \"name\": \"ACME Corp\",\n    \"logoUrl\": \"https://media.example.com/acme.svg\",\n    \"active\": true\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "chainId": 137
}

{
  "error": {
    "requestId": "<string>",
    "message": "<string>",
    "errorCode": "<string>",
    "docUrl": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "requestId": "<string>",
    "message": "<string>",
    "errorCode": "<string>",
    "docUrl": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

This endpoint also creates versions. ROOTKey groups a record’s versions by the table’s primary key (the schema’s key column — by default the first field, e.g. id).

New primary-key value → new record.
Primary-key value that already exists → a new version of that record (a database-style update). The new version’s parentId is set to the existing entity’s root record automatically — you don’t send it.

So to update an entity, simply POST the same primary key again — there is no separate version-creation endpoint. Versioning is a built-in behaviour of this route, driven entirely by the primary key.See the Records overview → Versioning for the full model and how to read a record’s id back.

Authorizations

x-api-key

string

header

required

ROOTKey API key (rk_live_... for production, rk_test_... for the test network).

Body

application/json

ownerVault

string

required

Address of the table that will own the record. (ownerWallet is accepted as an alias.)

Example:

"0xdf67CA8286510997567685c0385ECeAb11C23C92"

recordData

object

required

The record's columns as a JSON object. Values are primitives (string, number, boolean, ISO date, null) or nested objects/arrays within limits: 1 MB per record, 64 KB per string, 100 properties, 10 levels of nesting, 1,000 array elements. Keys beginning with __ (and prototype-polluting keys) are stripped on ingest. The value of the schema's key column (the primary key) determines version grouping — see the endpoint description.

expirationDate

string<date-time>

Optional expiry date-time for the record.

Response

Record created (or a new version, if its primary key already existed)

Record create/version response. Note: unlike files, record creation does not return a transactionHash or the new record id — obtain the id from GET /platform/records (__meta.id).

chainId

number

required

Polygon chain ID (137 in production, 80002 on the Amoy testnet).

Example:

137

API Documentation

Status

Files

Vaults

Records

Data Recovery

Create record

Authorizations

Body

Response