Getting Started
This guide walks you through the basic operations of KVNode: health checks, collection management, and key-value operations.
Health Check
Verify the node is running:
curl "https://api.hola.cloud/healthz"GET /healthz HTTP/1.1
Host: api.hola.cloud
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api.hola.cloud/healthz", nil)
if err != nil {
panic(err)
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/healthz',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
response = requests.request(
"GET",
"https://api.hola.cloud/healthz"
)
print(response.text)
const response = await fetch("https://api.hola.cloud/healthz", {
method: "GET"
});
console.log(await response.text());
const response = await fetch("https://api.hola.cloud/healthz", {
method: "GET"
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/healthz"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Expected response:
1{"ok":true,"node":"node-1","role":"primary"}
Readiness Check
Check if the node is ready to serve traffic (verifies parent connection for replicas):
curl "https://api.hola.cloud/readyz"GET /readyz HTTP/1.1
Host: api.hola.cloud
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api.hola.cloud/readyz", nil)
if err != nil {
panic(err)
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/readyz',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
response = requests.request(
"GET",
"https://api.hola.cloud/readyz"
)
print(response.text)
const response = await fetch("https://api.hola.cloud/readyz", {
method: "GET"
});
console.log(await response.text());
const response = await fetch("https://api.hola.cloud/readyz", {
method: "GET"
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/readyz"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Expected response when ready:
1{"ok":true,"node":"node-1","role":"primary","ready":true,"checks":{"wal_replayed":true,"parent_connected":true}}
Create a Collection
Collections are containers for key-value pairs. Create one with a POST request:
curl -X POST "https://api.hola.cloud/v1/collections" \
-H "apikey: your-api-key" \
-H "secret: your-api-secret" \
-d '{"name": "my-collection"}'POST /v1/collections HTTP/1.1
Host: api.hola.cloud
apikey: your-api-key
secret: your-api-secret
{"name": "my-collection"}package main
import (
"fmt"
"io"
"net/http"
"encoding/json"
"strings"
)
func main() {
payload := map[string]any{"name": "my-collection"}
bodyBytes, err := json.Marshal(payload)
if err != nil {
panic(err)
}
body := string(bodyBytes)
req, err := http.NewRequest("POST", "https://api.hola.cloud/v1/collections", strings.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("apikey", "your-api-key")
req.Header.Set("secret", "your-api-secret")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$payload = ['name' => 'my-collection'];
$body = json_encode($payload);
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/v1/collections',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
'apikey: your-api-key',
'secret: your-api-secret',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
import json
headers = {
"apikey": "your-api-key",
"secret": "your-api-secret",
}
payload = {"name": "my-collection"}
body = json.dumps(payload)
response = requests.request(
"POST",
"https://api.hola.cloud/v1/collections",
headers=headers,
data=body
)
print(response.text)
const payload = {"name": "my-collection"};
const response = await fetch("https://api.hola.cloud/v1/collections", {
method: "POST",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
},
body: JSON.stringify(payload)
});
console.log(await response.text());
const payload = {"name": "my-collection"};
const response = await fetch("https://api.hola.cloud/v1/collections", {
method: "POST",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
},
body: JSON.stringify(payload)
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.List;
public class Main {
public static void main(String[] args) throws Exception {
var payload = Map.of("name", "my-collection");
var body = new ObjectMapper().writeValueAsString(payload);
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/v1/collections"))
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.header("apikey", "your-api-key")
.header("secret", "your-api-secret")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Expected response:
1{"ok":true,"collection":"my-collection"}
Set a Key-Value Pair
Store a JSON value under a key inside a collection:
curl -X POST "https://api.hola.cloud/v1/collections/my-collection/keys/*" \
-H "apikey: your-api-key" \
-H "secret: your-api-secret" \
-d '{"value": {"user": "alice", "role": "admin"}}'POST /v1/collections/my-collection/keys/* HTTP/1.1
Host: api.hola.cloud
apikey: your-api-key
secret: your-api-secret
{"value": {"user": "alice", "role": "admin"}}package main
import (
"fmt"
"io"
"net/http"
"encoding/json"
"strings"
)
func main() {
payload := map[string]any{"value": map[string]any{"role": "admin", "user": "alice"}}
bodyBytes, err := json.Marshal(payload)
if err != nil {
panic(err)
}
body := string(bodyBytes)
req, err := http.NewRequest("POST", "https://api.hola.cloud/v1/collections/my-collection/keys/*", strings.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("apikey", "your-api-key")
req.Header.Set("secret", "your-api-secret")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$payload = ['value' => ['role' => 'admin', 'user' => 'alice']];
$body = json_encode($payload);
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/v1/collections/my-collection/keys/*',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
'apikey: your-api-key',
'secret: your-api-secret',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
import json
headers = {
"apikey": "your-api-key",
"secret": "your-api-secret",
}
payload = {"value": {"role": "admin", "user": "alice"}}
body = json.dumps(payload)
response = requests.request(
"POST",
"https://api.hola.cloud/v1/collections/my-collection/keys/*",
headers=headers,
data=body
)
print(response.text)
const payload = {"value": {"role": "admin", "user": "alice"}};
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys/*", {
method: "POST",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
},
body: JSON.stringify(payload)
});
console.log(await response.text());
const payload = {"value": {"role": "admin", "user": "alice"}};
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys/*", {
method: "POST",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
},
body: JSON.stringify(payload)
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.List;
public class Main {
public static void main(String[] args) throws Exception {
var payload = Map.of("value", Map.of("role", "admin", "user", "alice"));
var body = new ObjectMapper().writeValueAsString(payload);
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/v1/collections/my-collection/keys/*"))
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.header("apikey", "your-api-key")
.header("secret", "your-api-secret")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}The * path segment captures the key name. To set the key user:alice, use:
curl -X POST "https://api.hola.cloud/v1/collections/my-collection/keys/user:alice" \
-H "apikey: your-api-key" \
-H "secret: your-api-secret" \
-d '{"value": {"user": "alice", "role": "admin"}}'POST /v1/collections/my-collection/keys/user:alice HTTP/1.1
Host: api.hola.cloud
apikey: your-api-key
secret: your-api-secret
{"value": {"user": "alice", "role": "admin"}}package main
import (
"fmt"
"io"
"net/http"
"encoding/json"
"strings"
)
func main() {
payload := map[string]any{"value": map[string]any{"role": "admin", "user": "alice"}}
bodyBytes, err := json.Marshal(payload)
if err != nil {
panic(err)
}
body := string(bodyBytes)
req, err := http.NewRequest("POST", "https://api.hola.cloud/v1/collections/my-collection/keys/user:alice", strings.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("apikey", "your-api-key")
req.Header.Set("secret", "your-api-secret")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$payload = ['value' => ['role' => 'admin', 'user' => 'alice']];
$body = json_encode($payload);
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/v1/collections/my-collection/keys/user:alice',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
'apikey: your-api-key',
'secret: your-api-secret',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
import json
headers = {
"apikey": "your-api-key",
"secret": "your-api-secret",
}
payload = {"value": {"role": "admin", "user": "alice"}}
body = json.dumps(payload)
response = requests.request(
"POST",
"https://api.hola.cloud/v1/collections/my-collection/keys/user:alice",
headers=headers,
data=body
)
print(response.text)
const payload = {"value": {"role": "admin", "user": "alice"}};
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys/user:alice", {
method: "POST",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
},
body: JSON.stringify(payload)
});
console.log(await response.text());
const payload = {"value": {"role": "admin", "user": "alice"}};
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys/user:alice", {
method: "POST",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
},
body: JSON.stringify(payload)
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.List;
public class Main {
public static void main(String[] args) throws Exception {
var payload = Map.of("value", Map.of("role", "admin", "user", "alice"));
var body = new ObjectMapper().writeValueAsString(payload);
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/v1/collections/my-collection/keys/user:alice"))
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.header("apikey", "your-api-key")
.header("secret", "your-api-secret")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Expected response:
1{"ok":true,"seq":1,"version":1}
Get a Key
Retrieve the value for a specific key:
curl "https://api.hola.cloud/v1/collections/my-collection/keys/user:alice" \
-H "apikey: your-api-key" \
-H "secret: your-api-secret"GET /v1/collections/my-collection/keys/user:alice HTTP/1.1
Host: api.hola.cloud
apikey: your-api-key
secret: your-api-secret
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api.hola.cloud/v1/collections/my-collection/keys/user:alice", nil)
if err != nil {
panic(err)
}
req.Header.Set("apikey", "your-api-key")
req.Header.Set("secret", "your-api-secret")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/v1/collections/my-collection/keys/user:alice',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'apikey: your-api-key',
'secret: your-api-secret',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
headers = {
"apikey": "your-api-key",
"secret": "your-api-secret",
}
response = requests.request(
"GET",
"https://api.hola.cloud/v1/collections/my-collection/keys/user:alice",
headers=headers
)
print(response.text)
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys/user:alice", {
method: "GET",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
}
});
console.log(await response.text());
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys/user:alice", {
method: "GET",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
}
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/v1/collections/my-collection/keys/user:alice"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.header("apikey", "your-api-key")
.header("secret", "your-api-secret")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Expected response:
1{"key":"user:alice","value":{"user":"alice","role":"admin"},"version":1,"updatedAt":"2025-01-01T00:00:00Z"}
List Keys with Prefix
List all keys in a collection, optionally filtered by prefix and limited in count:
curl "https://api.hola.cloud/v1/collections/my-collection/keys?prefix=user:&limit=10" \
-H "apikey: your-api-key" \
-H "secret: your-api-secret"GET /v1/collections/my-collection/keys?prefix=user:&limit=10 HTTP/1.1
Host: api.hola.cloud
apikey: your-api-key
secret: your-api-secret
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api.hola.cloud/v1/collections/my-collection/keys?prefix=user:&limit=10", nil)
if err != nil {
panic(err)
}
req.Header.Set("apikey", "your-api-key")
req.Header.Set("secret", "your-api-secret")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/v1/collections/my-collection/keys?prefix=user:&limit=10',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'apikey: your-api-key',
'secret: your-api-secret',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
headers = {
"apikey": "your-api-key",
"secret": "your-api-secret",
}
response = requests.request(
"GET",
"https://api.hola.cloud/v1/collections/my-collection/keys?prefix=user:&limit=10",
headers=headers
)
print(response.text)
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys?prefix=user:&limit=10", {
method: "GET",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
}
});
console.log(await response.text());
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys?prefix=user:&limit=10", {
method: "GET",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
}
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/v1/collections/my-collection/keys?prefix=user:&limit=10"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.header("apikey", "your-api-key")
.header("secret", "your-api-secret")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Expected response:
1[{"key":"user:alice","value":{"user":"alice","role":"admin"},"version":1}]
Delete a Key
Remove a key from a collection:
curl -X DELETE "https://api.hola.cloud/v1/collections/my-collection/keys/user:alice" \
-H "apikey: your-api-key" \
-H "secret: your-api-secret"DELETE /v1/collections/my-collection/keys/user:alice HTTP/1.1
Host: api.hola.cloud
apikey: your-api-key
secret: your-api-secret
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("DELETE", "https://api.hola.cloud/v1/collections/my-collection/keys/user:alice", nil)
if err != nil {
panic(err)
}
req.Header.Set("apikey", "your-api-key")
req.Header.Set("secret", "your-api-secret")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/v1/collections/my-collection/keys/user:alice',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'apikey: your-api-key',
'secret: your-api-secret',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
headers = {
"apikey": "your-api-key",
"secret": "your-api-secret",
}
response = requests.request(
"DELETE",
"https://api.hola.cloud/v1/collections/my-collection/keys/user:alice",
headers=headers
)
print(response.text)
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys/user:alice", {
method: "DELETE",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
}
});
console.log(await response.text());
const response = await fetch("https://api.hola.cloud/v1/collections/my-collection/keys/user:alice", {
method: "DELETE",
headers: {
"apikey": "your-api-key",
"secret": "your-api-secret"
}
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/v1/collections/my-collection/keys/user:alice"))
.method("DELETE", HttpRequest.BodyPublishers.noBody())
.header("apikey", "your-api-key")
.header("secret", "your-api-secret")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Expected response:
1{"ok":true,"seq":2,"version":2}
Summary
You have now performed the basic KVNode operations: health checks, collection creation, and full CRUD on key-value pairs. From here, explore replication configuration and multi-language SDK integration.
Comments