Basic Operations

Manage individual records using ekoDB's REST API. All operations support JSON payloads and return structured responses.

Authentication

All API requests require authentication via JWT tokens. Generate a token from your API key:

curl -X POST https://{EKODB_API_URL}/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}'

Response:

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

Use this token in all subsequent requests:

-H "Authorization: Bearer {YOUR_API_TOKEN}"

Token Expiration

Tokens expire after 24 hours by default. Generate a new token when needed.

Configuration

Update ekoDB instance configuration via the REST API.

PUT https://{EKODB_API_URL}/api/config
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "use_typed_values": true
}

# Response
{
  "status": "success",
  "use_typed_values": true
}

Configuration Options:

use_typed_values (boolean) - Enable typed field values (default: true)

Insert Record

Create a new record in a collection.

POST https://{EKODB_API_URL}/api/insert/{collection}
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

# Response
{
  "id": "record_id_123"
}

Working Examples

Prefer a client library? See examples in Rust, Python, TypeScript, Go, or Kotlin

Want to use the REST API directly? See examples in JavaScript, Python, Go, or Rust

Get Full Record After Insert

The insert operation returns only the record ID. To retrieve the full record with all fields, use a GET request with the returned ID.

Disable Real-Time Data Propagation (Ripples):

By default, all write operations (insert, update, delete) automatically propagate to configured peer nodes via the Ripple system. Use bypass_ripple=true to skip propagation for specific operations:

When to bypass:

Background jobs that process locally
Temporary data that doesn't need replication
Development/testing operations
Operations during maintenance windows

POST https://{EKODB_API_URL}/api/insert/{collection}?bypass_ripple=true
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "name": "Local Processing User",
  "email": "local@example.com"
}

Get Record by ID

Retrieve a specific record by its ID.

GET https://{EKODB_API_URL}/api/find/{collection}/{record_id}
Authorization: Bearer {YOUR_API_TOKEN}

# Response
{
  "id": "record_id_123",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "created_at": "2024-01-15T10:30:00Z"
}

Alternative POST Method:

POST https://{EKODB_API_URL}/api/find/{collection}/{record_id}
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

# Same response as GET

Query Records

Query records with filters, sorting, and pagination.

POST https://{EKODB_API_URL}/api/find/{collection}
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "filter": {
    "type": "expression",
    "content": {
      "field": "age",
      "operator": "GreaterThan",
      "value": 25
    }
  },
  "sort": {
    "field": "created_at",
    "order": "desc"
  },
  "limit": 10,
  "offset": 0
}

# Response
{
  "records": [
    {
      "id": "record_1",
      "name": "John Doe",
      "age": 30
    },
    {
      "id": "record_2",
      "name": "Jane Smith",
      "age": 28
    }
  ],
  "total": 2
}

Query Operators:

Equals - Exact match
NotEquals - Not equal to
GreaterThan - Greater than
LessThan - Less than
GreaterThanOrEqual - Greater than or equal
LessThanOrEqual - Less than or equal
Contains - String contains (case-insensitive)
StartsWith - String starts with
EndsWith - String ends with

Combine Filters with AND:

{
  "filter": {
    "type": "and",
    "content": [
      {
        "type": "expression",
        "content": {
          "field": "age",
          "operator": "GreaterThan",
          "value": 25
        }
      },
      {
        "type": "expression",
        "content": {
          "field": "status",
          "operator": "Equals",
          "value": "active"
        }
      }
    ]
  }
}

Combine Filters with OR:

{
  "filter": {
    "type": "or",
    "content": [
      {
        "type": "expression",
        "content": {
          "field": "role",
          "operator": "Equals",
          "value": "admin"
        }
      },
      {
        "type": "expression",
        "content": {
          "field": "role",
          "operator": "Equals",
          "value": "moderator"
        }
      }
    ]
  }
}

Complex Nested Filters:

Find active users who are either admins OR (have age > 25 AND verified):

{
  "filter": {
    "type": "and",
    "content": [
      {
        "type": "expression",
        "content": {
          "field": "status",
          "operator": "Equals",
          "value": "active"
        }
      },
      {
        "type": "or",
        "content": [
          {
            "type": "expression",
            "content": {
              "field": "role",
              "operator": "Equals",
              "value": "admin"
            }
          },
          {
            "type": "and",
            "content": [
              {
                "type": "expression",
                "content": {
                  "field": "age",
                  "operator": "GreaterThan",
                  "value": 25
                }
              },
              {
                "type": "expression",
                "content": {
                  "field": "verified",
                  "operator": "Equals",
                  "value": true
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Advanced Queries

For complex queries with nested filters and advanced operations, see the Query Expressions reference. Using a client library? See Client Libraries - Querying with Filters.

Update Record

Update an existing record by ID.

PUT https://{EKODB_API_URL}/api/update/{collection}/{record_id}
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "status": "active",
  "updated_at": "2024-01-15T11:00:00Z"
}

# Response
{
  "id": "record_id_123",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "status": "active",
  "updated_at": "2024-01-15T11:00:00Z"
}

Partial Updates:

Only the fields provided in the request body are updated. Existing fields remain unchanged.

Disable Real-Time Sync:

PUT https://{EKODB_API_URL}/api/update/{collection}/{record_id}?bypass_ripple=true
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "status": "processed"
}

Search Records

Full-text and semantic search across records.

POST https://{EKODB_API_URL}/api/search/{collection}
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "query": "software engineer",
  "limit": 10,
  "offset": 0
}

# Response
{
  "results": [
    {
      "record": {
        "id": "record_1",
        "name": "John Doe",
        "title": "Senior Software Engineer"
      },
      "score": 0.95
    }
  ],
  "total": 1
}

Search with Vector Similarity:

POST https://{EKODB_API_URL}/api/search/{collection}
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "query": "machine learning",
  "vector_field": "embedding",
  "limit": 5,
  "similarity_threshold": 0.8
}

GET Alternative:

GET https://{EKODB_API_URL}/api/search/{collection}?query=software%20engineer&limit=10
Authorization: Bearer {YOUR_API_TOKEN}

Delete Record

Delete a record by ID (moves to trash for 30 days before permanent deletion).

DELETE https://{EKODB_API_URL}/api/delete/{collection}/{record_id}
Authorization: Bearer {YOUR_API_TOKEN}

# Response
{
  "id": "record_id_123",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

Deleted Record Returned

The delete operation returns the full deleted record, useful for undo operations or audit logs.

Disable Real-Time Sync:

DELETE https://{EKODB_API_URL}/api/delete/{collection}/{record_id}?bypass_ripple=true
Authorization: Bearer {YOUR_API_TOKEN}

Collection-Level Operations

Full Collection Management

For complete schema definitions, field types, and advanced collection configuration, see Collections & Schemas.

Create Collection

Create a new collection with an optional schema.

POST https://{EKODB_API_URL}/api/collections/{collection}
Content-Type: application/json
Authorization: Bearer {ADMIN_TOKEN}

{
  "fields": {
    "name": {
      "type": "string",
      "required": true
    },
    "email": {
      "type": "string",
      "required": true
    },
    "age": {
      "type": "number"
    }
  }
}

# Response
{
  "status": "success",
  "message": "Collection initialized successfully"
}

Working Examples

Want to use the REST API directly? See examples in JavaScript, Python, Go, or Rust

Prefer a client library? See examples in Rust, Python, TypeScript, Go, or Kotlin

List Collections

Get a list of all collections in the database.

GET https://{EKODB_API_URL}/api/collections
Authorization: Bearer {YOUR_API_TOKEN}

# Response
{
  "collections": [
    {
      "name": "users",
      "record_count": 1234,
      "created_at": "2024-01-10T08:00:00Z"
    },
    {
      "name": "products",
      "record_count": 567,
      "created_at": "2024-01-12T10:30:00Z"
    }
  ]
}

Get Collection Info

Retrieve information about a specific collection.

GET https://{EKODB_API_URL}/api/collections/{collection}
Authorization: Bearer {YOUR_API_TOKEN}

# Response
{
  "name": "users",
  "record_count": 1234,
  "schema": { ... },
  "created_at": "2024-01-10T08:00:00Z"
}

Update Schema

Update validation constraints for an existing collection schema.

PUT https://{EKODB_API_URL}/api/schemas/{collection}
Content-Type: application/json
Authorization: Bearer {ADMIN_TOKEN}

{
  "constraints": {
    "email": {
      "required": true,
      "unique": true
    }
  }
}

# Response
{
  "status": "success",
  "message": "Schema constraints updated successfully"
}

Schema Updates

Schema updates only affect new records. Existing records are not automatically migrated or validated against the new schema.

Delete Collection

DELETE https://{EKODB_API_URL}/api/collections/{collection}
Authorization: Bearer {ADMIN_TOKEN}

Restore from Trash

# Restore single record
POST https://{EKODB_API_URL}/api/trash/{collection}/{record_id}
Authorization: Bearer {ADMIN_TOKEN}

# Restore all records in collection
POST https://{EKODB_API_URL}/api/trash/{collection}
Authorization: Bearer {ADMIN_TOKEN}

Full Details

For complete Delete and Restore documentation including response formats and trash retention policies, see Collections & Schemas - Delete Collection.

Using Operations Within Transactions

All write operations (insert, update, delete) can be performed within a transaction by adding the transaction_id query parameter. Operations are tracked and can be committed or rolled back together.

Insert Within Transaction:

POST https://{EKODB_API_URL}/api/insert/users?transaction_id=tx-001
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "name": "John Doe",
  "email": "john@example.com"
}

Update Within Transaction:

PUT https://{EKODB_API_URL}/api/update/users/user_123?transaction_id=tx-001
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "status": "active"
}

Delete Within Transaction:

DELETE https://{EKODB_API_URL}/api/delete/users/user_123?transaction_id=tx-001
Authorization: Bearer {YOUR_API_TOKEN}

Complete Transaction Example:

# 1. Begin transaction
tx_id=$(curl -s -X POST https://{EKODB_API_URL}/api/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{"isolation_level": "Serializable"}' | jq -r '.transaction_id')

# 2. Insert record in transaction
curl -X POST https://{EKODB_API_URL}/api/insert/users?transaction_id=$tx_id \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{"name": "Jane Doe", "email": "jane@example.com"}'

# 3. Update record in transaction
curl -X PUT https://{EKODB_API_URL}/api/update/users/user_456?transaction_id=$tx_id \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{"status": "verified"}'

# 4. Commit transaction (or rollback if needed)
curl -X POST https://{EKODB_API_URL}/api/transactions/$tx_id/commit \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

Transaction Support

For full transaction management including savepoints and rollback capabilities, see the Transactions documentation.

Complete Example

Here's a complete workflow for creating and managing a user:

# 1. Insert user
curl -X POST https://{EKODB_API_URL}/api/insert/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30,
    "status": "pending"
  }'
# Response: {"id": "user_123", ...}

# 2. Get user by ID
curl -X GET https://{EKODB_API_URL}/api/find/users/user_123 \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

# 3. Update user status
curl -X PUT https://{EKODB_API_URL}/api/update/users/user_123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{
    "status": "active",
    "activated_at": "2024-01-15T11:00:00Z"
  }'

# 4. Query active users
curl -X POST https://{EKODB_API_URL}/api/find/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{
    "filter": {
      "type": "expression",
      "content": {
        "field": "status",
        "operator": "Equals",
        "value": "active"
      }
    },
    "limit": 10
  }'

# 5. Search users
curl -X POST https://{EKODB_API_URL}/api/search/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{
    "query": "john",
    "limit": 5
  }'

# 6. Delete user
curl -X DELETE https://{EKODB_API_URL}/api/delete/users/user_123 \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

Best Practices

Use Appropriate HTTP Methods

# Create - POST
POST /api/insert/{collection}

# Read - GET
GET /api/find/{collection}/{id}

# Update - PUT
PUT /api/update/{collection}/{id}

# Delete - DELETE
DELETE /api/delete/{collection}/{id}

Handle Errors Gracefully

# Check status code
response=$(curl -s -w "\n%{http_code}" -X GET .../api/find/users/user_123)
status_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

if [ "$status_code" != "200" ]; then
  echo "Error: $body"
fi

Use Filters for Efficient Queries

# Good: Filter on indexed fields
POST /api/find/users
{"filter": {"field": "status", "operator": "Equals", "value": "active"}}

# Good: Limit results
POST /api/find/users
{"filter": {...}, "limit": 100}

# Avoid: Fetching all records without filter
POST /api/find/users
{"limit": 10000}  # Use pagination instead

Pagination for Large Result Sets

# Page 1
POST /api/find/users
{"limit": 100, "offset": 0}

# Page 2
POST /api/find/users
{"limit": 100, "offset": 100}

# Page 3
POST /api/find/users
{"limit": 100, "offset": 200}

Query Examples

Simple Equality Query

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

Range Query (Age Between 18 and 65)

curl -X POST https://your-db.ekodb.net/api/find/users \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "Logical",
      "content": {
        "operator": "And",
        "expressions": [
          {
            "type": "Condition",
            "content": {
              "field": "age",
              "operator": "Gte",
              "value": 18
            }
          },
          {
            "type": "Condition",
            "content": {
              "field": "age",
              "operator": "Lte",
              "value": 65
            }
          }
        ]
      }
    },
    "sort": [
      {
        "field": "age",
        "ascending": true
      }
    ],
    "limit": 50
  }'

String Contains Query

curl -X POST https://your-db.ekodb.net/api/find/users \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "Condition",
      "content": {
        "field": "email",
        "operator": "Contains",
        "value": "@gmail.com"
      }
    }
  }'

IN Array Query

curl -X POST https://your-db.ekodb.net/api/find/users \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "Condition",
      "content": {
        "field": "role",
        "operator": "In",
        "value": ["admin", "moderator", "editor"]
      }
    }
  }'

Query Expression Reference

For a complete reference of all operators and query patterns, see Query Expressions.

Query Expressions - Complete query operators reference
Batch Operations - Bulk operations for multiple records
Transactions - ACID transactions for atomicity
Collections & Schemas - Create and manage collections
KV Store - Simple key-value operations
Client Libraries - Language-specific client libraries
Authentication - API key and JWT authentication

Example Code

Direct HTTP/REST API Examples

Raw HTTP examples demonstrating the REST API directly:

JavaScript - simple_crud.js
Python - simple_crud.py
Go - simple_crud.go
Rust - simple_crud.rs

Client Library Examples

Production-ready examples using official client libraries:

Rust - client_simple_crud.rs
Python - client_simple_crud.py
TypeScript - client_simple_crud.ts
Go - client_simple_crud.go
Kotlin - ClientSimpleCrud.kt
JavaScript - client_simple_crud.js

Authentication​

Configuration​

Insert Record​

Get Record by ID​

Query Records​

Update Record​

Search Records​

Delete Record​

Collection-Level Operations​

Create Collection​

List Collections​

Get Collection Info​

Update Schema​

Delete Collection​

Restore from Trash​

Using Operations Within Transactions​

Complete Example​

Best Practices​

Use Appropriate HTTP Methods​

Handle Errors Gracefully​

Use Filters for Efficient Queries​

Pagination for Large Result Sets​

Query Examples​

Simple Equality Query​

Range Query (Age Between 18 and 65)​

String Contains Query​

IN Array Query​

Related Documentation​

Example Code​

Direct HTTP/REST API Examples​

Client Library Examples​