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

info

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:

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: 24 hours).

Step 4: Your First Insert (30 seconds)

Now let's insert your first record using the token:

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

🎉 Congratulations! You just inserted your first record into ekoDB!

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: Fetch by ID (30 seconds)

Now let's fetch the record you just created using its ID:

curl -X GET https://my-first-db.development.{provider}.ekodb.net/api/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:

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:

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

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!

🦀 Rust
🐍 Python
📘 TypeScript
🟣 Kotlin
🔷 Go

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::new(
        "https://my-first-db.development.{provider}.ekodb.net",
        "YOUR_API_KEY"
    )?;

    // 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-client

import { EkoDBClient } from 'ekodb-client';

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

// 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.4.0")
}

import io.ekodb.client.EkoDBClient

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

    // 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"
    "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 (coming soon in docs)
→ 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?

🐛 Issues: GitHub Issues
💬 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: Your First Insert (30 seconds)​

Step 5: Fetch by ID (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?​