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:

1curl "https://api.hola.cloud/healthz"

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):

1curl "https://api.hola.cloud/readyz"

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:

1curl -X POST "https://api.hola.cloud/v1/collections" \
2  -H "apikey: your-api-key" \
3  -H "secret: your-api-secret" \
4  -d '{"name": "my-collection"}'

Expected response:

1{"ok":true,"collection":"my-collection"}

Set a Key-Value Pair

Store a JSON value under a key inside a collection:

1curl -X POST "https://api.hola.cloud/v1/collections/my-collection/keys/*" \
2  -H "apikey: your-api-key" \
3  -H "secret: your-api-secret" \
4  -d '{"value": {"user": "alice", "role": "admin"}}'

The * path segment captures the key name. To set the key user:alice, use:

1curl -X POST "https://api.hola.cloud/v1/collections/my-collection/keys/user:alice" \
2  -H "apikey: your-api-key" \
3  -H "secret: your-api-secret" \
4  -d '{"value": {"user": "alice", "role": "admin"}}'

Expected response:

1{"ok":true,"seq":1,"version":1}

Get a Key

Retrieve the value for a specific key:

1curl "https://api.hola.cloud/v1/collections/my-collection/keys/user:alice" \
2  -H "apikey: your-api-key" \
3  -H "secret: your-api-secret"

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:

1curl "https://api.hola.cloud/v1/collections/my-collection/keys?prefix=user:&limit=10" \
2  -H "apikey: your-api-key" \
3  -H "secret: your-api-secret"

Expected response:

1[{"key":"user:alice","value":{"user":"alice","role":"admin"},"version":1}]

Delete a Key

Remove a key from a collection:

1curl -X DELETE "https://api.hola.cloud/v1/collections/my-collection/keys/user:alice" \
2  -H "apikey: your-api-key" \
3  -H "secret: your-api-secret"

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.