Create Client - CyborgDB Docs

The Client class provides an interface to connect to the CyborgDB service and manage encrypted indexes. It allows you to create, list, and interact with encrypted indexes through the CyborgDB REST API.

Creating the Client

To create the client, provide the service URL. An API key is only needed when the service has authentication enabled (see API Key Authentication below); against a service running with auth disabled — the default — you can omit it:

from cyborgdb import Client

# Auth disabled (default): no API key needed
client = Client(base_url='http://localhost:8000')

# Auth enabled: pass the root key or a cdbk_ user token
client = Client(
    base_url='http://localhost:8000', 
    api_key='your-api-key'
)

import { Client } from 'cyborgdb';

// Create client with API key
const client = new Client({ 
    baseUrl: 'http://localhost:8000', 
    apiKey: 'your-api-key' 
});

import { Client } from 'cyborgdb';

// Create client with API key
const client = new Client({ 
    baseUrl: 'http://localhost:8000', 
    apiKey: 'your-api-key' 
});

package main

import (
    "log"
    
    "github.com/cyborginc/cyborgdb-go"
)

func main() {
    // Create client with API key
    client, err := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
    if err != nil {
        log.Fatal(err)
    }
}

# Test connection with health check
curl -X GET "http://localhost:8000/v1/health"

# All subsequent API calls will use this pattern:
# curl -H "X-API-Key: your-api-key" "http://localhost:8000/v1/..."

If using the REST API directly, you don’t need to create a client. You can make HTTP requests directly to the service endpoints.

API Key Authentication

Request authentication is controlled by the service, not the client. When the service is started with CYBORGDB_SERVICE_ROOT_KEY set, every request must carry a credential in the X-API-Key header: either that root key or a per-user cdbk_ token minted under it. When the service runs without CYBORGDB_SERVICE_ROOT_KEY (the default), authentication is disabled and the api_key argument can be omitted. Pass the credential as api_key at construction and the client attaches the X-API-Key header to every request automatically. Note this is distinct from the service’s CYBORGDB_API_KEY license key, which is not an authentication credential. See Managing Keys for how to mint user tokens.

Health Checking

You can verify the service connection and health:

# Check service health
try:
    health = client.get_health()
    print("Service status:", health["status"])
except Exception as e:
    print(f"Service unavailable: {e}")

// Check service health
try {
    const health = await client.getHealth();
    console.log('Service status:', health);
} catch (error) {
    console.error('Service unavailable:', error.message);
}

// Check service health
try {
    const health = await client.getHealth();
    console.log('Service status:', health);
} catch (error) {
    console.error('Service unavailable:', error.message);
}

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/cyborginc/cyborgdb-go"
)

func main() {
    // Create client
    client, err := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
    if err != nil {
        log.Fatal(err)
    }
    
    // Check service health
    ctx := context.Background()
    health, err := client.GetHealth(ctx)
    if err != nil {
        fmt.Printf("Service unavailable: %v\n", err)
        return
    }
    fmt.Printf("Service status: %+v\n", health)
}

# Check service health (no API key required)
curl -X GET "http://localhost:8000/v1/health"

# Expected response:
# {"status": "healthy", "api_version": "v1", "version": "0.17.0"}

API Reference

For more information on the Client class, refer to the API Reference:

Python SDK Reference

API reference for Client in Python

JS/TS SDK Reference

API reference for Client in JavaScript/TypeScript

Go SDK Reference

API reference for Client in Go

​Creating the Client

​API Key Authentication

​Health Checking

​API Reference

Python SDK Reference

JS/TS SDK Reference

Go SDK Reference

Creating the Client

API Key Authentication

Health Checking

API Reference