Quick Start Guide

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

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)

Sign up at app.ekodb.io
Click "Create Deployment" at the top of the dashboard page: app.ekodb.io/dashboard
Select your region (choose the region closest to your users)
Choose a machine tier (start with the free tier for testing)
Set your subdomain and environment:
- Environment Type: development
- Subdomain: my-first-db (or any unique name)
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").

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)
Direct API

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

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

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

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

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

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

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..."
}

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)
Direct API

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

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

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

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

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

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

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

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

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}")

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)

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"
}

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)
Direct API

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

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

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

print(record)

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

console.log(record);

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

console.log(record);

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

println(record)

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

fmt.Println(record)

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"
  }
}

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)
Direct API

let results = client.query("users", Query::new()
    .filter(Filter::condition("name", Operator::Equals, "Alice"))
).await?;

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

results = client.query('users', {
    'filter': {
        'field': 'name',
        'operator': 'eq',
        'value': 'Alice'
    }
})

print(results['records'])

const results = await client.query('users', {
  filter: {
    field: 'name',
    operator: 'eq',
    value: 'Alice'
  }
});

console.log(results.records);

const results = await client.query('users', {
  filter: {
    field: 'name',
    operator: 'eq',
    value: 'Alice'
  }
});

console.log(results.records);

val results = client.query("users", mapOf(
    "filter" to mapOf(
        "field" to "name",
        "operator" to "eq",
        "value" to "Alice"
    )
))

println(results.records)

results, err := client.Query("users", ekodb.QueryOptions{
    Filter: &ekodb.Filter{
        Field:    "name",
        Operator: "eq",
        Value:    "Alice",
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(results.Records)

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": {
      "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)
Direct API

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

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

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

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

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

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

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"
  }'

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:

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!

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": {
            "field": "role",
            "operator": "eq",
            "value": "designer"
        }
    })).await?;

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

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 = client.insert("users", {
    "name": "Bob",
    "email": "bob@example.com",
    "age": 25,
    "role": "designer"
})

# Query
users = client.find("users", {
    "filter": {
        "field": "role",
        "operator": "eq",
        "value": "designer"
    }
})

print(users)

npm install @ekodb/ekodb-client

import { EkoDBClient } 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 users = await client.find("users", {
  filter: {
    field: "role",
    operator: "eq",
    value: "designer"
  }
});

console.log(users);

npm install @ekodb/ekodb-client

const { EkoDBClient } = 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 users = await client.find("users", {
  filter: {
    field: "role",
    operator: "eq",
    value: "designer"
  }
});

console.log(users);

// 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 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
    users, err := client.Find("users", map[string]interface{}{
        "filter": map[string]interface{}{
            "field":    "role",
            "operator": "eq",
            "value":    "designer",
        },
    })
    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

Set up proper authentication: Authentication Guide
Define schemas: Add validation and constraints to your collections
Add indexes: Optimize query performance
Enable WebSockets: Real-time data updates
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! 🚀

Step 1: Deploy Your Database (2 minutes)​

Step 2: Your Database URL​

Step 3: Get Your Access Token (30 seconds)​

Step 4: Insert Your First Record (1 minute)​

Step 5: Get a Record (30 seconds)​

Step 6: Query with Filter (30 seconds)​

Step 7: Update a Record (30 seconds)​

Step 8: Use a Client Library (Recommended)​

What You Just Learned​

Next Steps​

📚 Learn by Example​

Choose Your Path​

Common Next Tasks​

Need Help?​