Quick Start Guide

Get your first ekoDB database running and make your first API call in under 5 minutes!

:::tip New to ekoDB? Read the Overview to learn what ekoDB is and why it's different. Ready to dive in? Let's get you up and running! :::

Step 1: Deploy Your Database (2 minutes)

1. Sign up at app.ekodb.io
2. Click "Create Deployment" at the top of the dashboard page: app.ekodb.io/dashboard
3. Select your region (choose the region closest to your users)
4. Choose a machine tier (start with the free tier for testing)
5. Set your subdomain and environment:
   • Environment Type: development
   • Subdomain: my-first-db (or any unique name)
6. Click Create Deployment

Your database will be ready in a few minutes. You'll receive an email once it's live.

Step 2: Your Database URL

Once properly up and running, your deployment's status will show as "Running". Your database URL will be:

https://my-first-db.development.{provider}.ekodb.net

Replace {provider} with your selected cloud provider (ex. "google").

:::info Viewing Your Deployments View all of your deployments at app.ekodb.io/deployments.

Click on your deployment to navigate to that deployment's information page.

That deployment's database URL can be found at the top under the subdomain (shown with "/api").

Here you can also find this deployment's API keys. You will need the Admin API key for the next step.

To copy the Admin API key: Select your deployment → "Keys" tab → Click "Load Keys" → Copy the Admin API key :::

Step 3: Get Your Access Token (30 seconds)

First, generate an access token using your API key:

Client Libraries (Recommended)

🦀 Rust

use ekodb_client::Client;

let client = Client::builder()
    .base_url("https://my-first-db.development.google.ekodb.net")
    .api_key("YOUR_API_KEY")
    .build()?;

// Token is automatically managed by the client

🐍 Python

from ekodb_client import Client

client = Client.new(
    'https://my-first-db.development.google.ekodb.net',
    'YOUR_API_KEY'
)

# Token is automatically managed by the client

📘 TypeScript

import { EkoDBClient } from '@ekodb/ekodb-client';

const client = new EkoDBClient({
  baseURL: 'https://my-first-db.development.google.ekodb.net',
  apiKey: 'YOUR_API_KEY'
});
await client.init();

// Token is automatically managed by the client

📦 JavaScript

const { EkoDBClient } = require('@ekodb/ekodb-client');

const client = new EkoDBClient({
  baseURL: 'https://my-first-db.development.google.ekodb.net',
  apiKey: 'YOUR_API_KEY'
});
await client.init();

// Token is automatically managed by the client

🟣 Kotlin

import io.ekodb.client.EkoDBClient

val client = EkoDBClient.builder()
    .baseUrl("https://my-first-db.development.google.ekodb.net")
    .apiKey("YOUR_API_KEY")
    .build()

// Token is automatically managed by the client

🔷 Go

import ekodb "github.com/ekoDB/ekodb-client-go"

client := ekodb.NewClient(
    "https://my-first-db.development.google.ekodb.net",
    "YOUR_API_KEY",
)

// Token is automatically managed by the client

Direct API

curl -X POST https://my-first-db.development.{provider}.ekodb.net/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

:::tip Save Your Token Save this token for subsequent requests. Tokens are valid for a limited time (default: 1 hour). Client libraries handle token refresh automatically. :::

Step 4: Insert Your First Record (1 minute)

Let's create a user record:

Client Libraries (Recommended)

🦀 Rust

let result = client.insert("users", serde_json::json!({
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30,
    "role": "developer"
})).await?;

println!("Record ID: {}", result.id);

🐍 Python

result = await client.insert('users', {
    'name': 'Alice',
    'email': 'alice@example.com',
    'age': 30,
    'role': 'developer'
})

print('Record ID:', result['id'])

📘 TypeScript

const result = await client.insert('users', {
  name: 'Alice',
  email: 'alice@example.com',
  age: 30,
  role: 'developer'
});

console.log('Record ID:', result.id);

📦 JavaScript

const result = await client.insert('users', {
  name: 'Alice',
  email: 'alice@example.com',
  age: 30,
  role: 'developer'
});

console.log('Record ID:', result.id);

🟣 Kotlin

val result = client.insert("users", mapOf(
    "name" to "Alice",
    "email" to "alice@example.com",
    "age" to 30,
    "role" to "developer"
))

println("Record ID: ${result.id}")

🔷 Go

result, err := client.Insert("users", map[string]interface{}{
    "name":  "Alice",
    "email": "alice@example.com",
    "age":   30,
    "role":  "developer",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println("Record ID:", result.ID)

Direct API

curl -X POST https://my-first-db.development.{provider}.ekodb.net/api/insert/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30,
    "role": "developer"
  }'

Response:

{
  "id": "encrypted_record_id_here"
}

:::tip Important The id returned is an encrypted record ID. Save this ID - you'll need it to fetch, update, or delete this specific record. :::

Step 5: Get a Record (30 seconds)

Retrieve the record you just created:

Client Libraries (Recommended)

🦀 Rust

let record = client.get("users", &record_id).await?;

println!("{:?}", record);

🐍 Python

record = client.get('users', record_id)

print(record)

📘 TypeScript

const record = await client.get('users', recordId);

console.log(record);

📦 JavaScript

const record = await client.get('users', recordId);

console.log(record);

🟣 Kotlin

val record = client.get("users", recordId)

println(record)

🔷 Go

record, err := client.Get("users", recordID)
if err != nil {
    log.Fatal(err)
}

fmt.Println(record)

Direct API

curl -X GET https://my-first-db.development.{provider}.ekodb.net/api/find/users/{record_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Replace {record_id} with the id from the insert response.

Response (Default - Typed):

{
  "id": {
    "type": "String",
    "value": "encrypted_record_id_here"
  },
  "name": {
    "type": "String",
    "value": "Alice"
  },
  "email": {
    "type": "String",
    "value": "alice@example.com"
  },
  "age": {
    "type": "Integer",
    "value": 30
  },
  "role": {
    "type": "String",
    "value": "developer"
  }
}

:::info Typed Responses By default, ekoDB returns typed responses with type metadata. This provides type safety and explicit type information.

Want simpler JSON? You can switch to non-typed responses:

• Via App: app.ekodb.io/deployments → Select your deployment → Configurations → Edit → Toggle "Use Typed Values"
• Via API: PUT /api/config with {"use_typed_values": false}

Non-typed response example:

{
  "id": "encrypted_record_id_here",
  "name": "Alice",
  "email": "alice@example.com",
  "age": 30,
  "role": "developer"
}

:::

Step 6: Query with Filter (30 seconds)

You can also query records using filters instead of IDs:

Client Libraries (Recommended)

🦀 Rust

use ekodb_client::QueryBuilder;

let query = QueryBuilder::new().eq("name", "Alice").build();
let results = client.find("users", query, None).await?;

println!("{:?}", results);

🐍 Python

from ekodb_client import QueryBuilder

query = QueryBuilder().eq("name", "Alice").build()
results = await client.find("users", query)

print(results)

📘 TypeScript

import { QueryBuilder } from '@ekodb/ekodb-client';

const query = new QueryBuilder().eq("name", "Alice").build();
const results = await client.find("users", query);

console.log(results);

📦 JavaScript

const { QueryBuilder } = require('@ekodb/ekodb-client');

const query = new QueryBuilder().eq("name", "Alice").build();
const results = await client.find("users", query);

console.log(results);

🟣 Kotlin

val query = QueryBuilder().eq("name", "Alice").build()
val results = client.find("users", query)

println(results)

🔷 Go

query := ekodb.NewQueryBuilder().Eq("name", "Alice").Build()
results, err := client.Find("users", query)
if err != nil {
    log.Fatal(err)
}

fmt.Println(results)

Direct API

curl -X POST https://my-first-db.development.{provider}.ekodb.net/api/find/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "filter": {
      "type": "Condition",
      "content": {
        "field": "name",
        "operator": "Eq",
        "value": "Alice"
      }
    }
  }'

Response (Typed):

{
  "records": [
    {
      "id": {
        "type": "String",
        "value": "encrypted_record_id_here"
      },
      "name": {
        "type": "String",
        "value": "Alice"
      },
      "email": {
        "type": "String",
        "value": "alice@example.com"
      },
      "age": {
        "type": "Integer",
        "value": 30
      },
      "role": {
        "type": "String",
        "value": "developer"
      }
    }
  ],
  "count": 1
}

Step 7: Update a Record (30 seconds)

Update Alice's role using the encrypted ID:

Client Libraries (Recommended)

🦀 Rust

client.update("users", &record_id, serde_json::json!({
    "role": "senior developer"
})).await?;

🐍 Python

await client.update('users', record_id, {
    'role': 'senior developer'
})

📘 TypeScript

await client.update('users', recordId, {
  role: 'senior developer'
});

📦 JavaScript

await client.update('users', recordId, {
  role: 'senior developer'
});

🟣 Kotlin

client.update("users", recordId, mapOf(
    "role" to "senior developer"
))

🔷 Go

_, err := client.Update("users", recordID, map[string]interface{}{
    "role": "senior developer",
})
if err != nil {
    log.Fatal(err)
}

Direct API

curl -X PUT https://my-first-db.development.{provider}.ekodb.net/api/update/users/{record_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "role": "senior developer"
  }'

:::note Using Record IDs Replace {record_id} with the actual id from your insert response. This is the encrypted record ID that ekoDB uses to identify specific records. :::

Step 8: Use a Client Library (Recommended)

While direct API calls work great, we recommend using our official client libraries for a better developer experience:

:::tip No Token Management Required Client libraries automatically handle token generation and refresh for you. Simply provide your API key once, and the client manages authentication behind the scenes! :::

🦀 Rust

cargo add ekodb_client
# Optional: Add tokio if using #[tokio::main] in your code
# cargo add tokio --features macros

use ekodb_client::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder()
        .base_url("https://my-first-db.development.{provider}.ekodb.net")
        .api_key("YOUR_API_KEY")
        .build()?;

    // Insert
    let user = client.insert("users", serde_json::json!({
        "name": "Bob",
        "email": "bob@example.com",
        "age": 25,
        "role": "designer"
    })).await?;

    // Query
    let users = client.find("users", serde_json::json!({
        "filter": {
            "type": "Condition",
            "content": {
                "field": "role",
                "operator": "Eq",
                "value": "designer"
            }
        }
    })).await?;

    println!("{:?}", users);
    Ok(())
}

🐍 Python

pip install ekodb-client

from ekodb_client import Client

client = Client.new(
    "https://my-first-db.development.{provider}.ekodb.net",
    "YOUR_API_KEY"
)

# Insert
user = await client.insert("users", {
    "name": "Bob",
    "email": "bob@example.com",
    "age": 25,
    "role": "designer"
})

# Query
users = await client.find("users", {
    "filter": {
        "type": "Condition",
        "content": {
            "field": "role",
            "operator": "Eq",
            "value": "designer"
        }
    }
})

print(users)

📘 TypeScript

npm install @ekodb/ekodb-client

import { EkoDBClient, QueryBuilder } from '@ekodb/ekodb-client';

const client = new EkoDBClient({
  baseURL: "https://my-first-db.development.{provider}.ekodb.net",
  apiKey: "YOUR_API_KEY"
});
await client.init();

// Insert
const user = await client.insert("users", {
  name: "Bob",
  email: "bob@example.com",
  age: 25,
  role: "designer"
});

// Query
const query = new QueryBuilder().eq("role", "designer").build();
const users = await client.find("users", query);

console.log(users);

📦 JavaScript

npm install @ekodb/ekodb-client

const { EkoDBClient, QueryBuilder } = require('@ekodb/ekodb-client');

const client = new EkoDBClient({
  baseURL: "https://my-first-db.development.{provider}.ekodb.net",
  apiKey: "YOUR_API_KEY"
});
await client.init();

// Insert
const user = await client.insert("users", {
  name: "Bob",
  email: "bob@example.com",
  age: 25,
  role: "designer"
});

// Query
const query = new QueryBuilder().eq("role", "designer").build();
const users = await client.find("users", query);

console.log(users);

🟣 Kotlin

// Add to build.gradle.kts
dependencies {
    implementation("io.ekodb:ekodb-client-kt:0.10.0")
}

import io.ekodb.client.EkoDBClient

suspend fun main() {
    val client = EkoDBClient.builder()
        .baseUrl("https://my-first-db.development.{provider}.ekodb.net")
        .apiKey("YOUR_API_KEY")
        .build()

    // Insert
    val user = client.insert("users", mapOf(
        "name" to "Bob",
        "email" to "bob@example.com",
        "age" to 25,
        "role" to "designer"
    ))

    // Query
    val users = client.find("users", mapOf(
        "filter" to mapOf(
            "field" to "role",
            "operator" to "eq",
            "value" to "designer"
        )
    ))

    println(users)
}

🔷 Go

go get github.com/ekoDB/ekodb-client-go

package main

import (
    "fmt"
    ekodb "github.com/ekoDB/ekodb-client-go"
)

func main() {
    client := ekodb.NewClient(
        "https://my-first-db.development.{provider}.ekodb.net",
        "YOUR_API_KEY",
    )

    // Insert
    user, err := client.Insert("users", map[string]interface{}{
        "name":  "Bob",
        "email": "bob@example.com",
        "age":   25,
        "role":  "designer",
    })
    if err != nil {
        panic(err)
    }

    // Query
    query := ekodb.NewQueryBuilder().Eq("role", "designer").Build()
    users, err := client.Find("users", query)
    if err != nil {
        panic(err)
    }

    fmt.Println(users)
}

What You Just Learned

✅ How to deploy an ekoDB database
✅ How to insert records
✅ How to query data
✅ How to update records
✅ How to use client libraries

Next Steps

Now that you have ekoDB running, here's what to explore next:

📚 Learn by Example

GitHub Examples Repository - 129 in all languages:

• Rust, Python, TypeScript, JavaScript, Go, Kotlin
• Client library examples (using official SDKs) and direct HTTP examples (raw REST API calls)
• CRUD operations, search, batch operations, functions, and more
• Complete working code you can copy and run

Choose Your Path

Building a Web/Mobile App? → Client Libraries Guide - Type-safe SDKs for your language

Using REST API Directly? → Basic Operations - Complete API reference

Need Advanced Features? → Batch Operations - High-performance bulk operations
→ Transactions - ACID-compliant multi-document transactions
→ Functions - Stored procedures

Building an AI Application? → Vector Search & Embeddings - Semantic similarity search
→ Search - Full-text search capabilities

Want to Understand the Architecture? → White Paper - Deep dive into ekoDB's design

Common Next Tasks

1. Set up proper authentication: Authentication Guide
2. Define schemas: Add validation and constraints to your collections
3. Add indexes: Optimize query performance
4. Enable WebSockets: Real-time data updates
5. Set up Ripple: Multi-region replication

Need Help?

• 💬 Support: app.ekodb.io/support
• 📧 Email: support@ekodb.io

---

Ready to build something amazing? Let's go! 🚀