API Documentation

Authentication API

Endpoints for user registration, login, and token management. These endpoints are the entry point for interacting with DataCube.

Register User

Create a new user account. A verification email will be sent upon successful registration.

POST /core/register

Request Body

{
    "email": "developer@example.com",
    "firstName": "Alex",
    "lastName": "Dev",
    "password": "a-strong-and-secure-password"
}

Example Response

{
    "message": "User registered successfully. Please check your email to verify your account."
}

Login (Get JWT)

Authenticate with your email and password to receive a short-lived Access Token and a long-lived Refresh Token.

POST /core/login

Request Body

{
    "email": "developer@example.com",
    "password": "a-strong-and-secure-password"
}

Example Response

{
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJI...",
    "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJI..."
}

Management API

Endpoints for managing your account, databases, and API keys. All requests to this API group must be authenticated using a JWT Bearer Token obtained from the Login endpoint.

Authentication Header

Authorization: Api-Key <YOUR_API_KEY>

Create Database

Create a new logical database with its initial collections and schema.

POST /api/create_database

Request Body

{
    "db_name": "my_customer_project",
    "collections": [
        {
            "name": "users",
            "fields": [
                {"name": "email", "type": "string"},
                {"name": "signup_date", "type": "date"}
            ]
        }
    ]
}

Example Response

{
    "success": true,
    "database": {
        "id": "60c72b2f9b1d8b1a2d3e4567",
        "name": "my_customer_project"
    },
    "collections": [ ... ]
}

List Databases

Retrieve a paginated list of all logical databases you own.

GET /api/list_databases

Query Parameters

page=1&page_size=10&search=customer

Example Response

{
    "success": true,
    "data": [
        {
            "id": "60c72b2f9b1d8b1a2d3e4567",
            "name": "my_customer_project",
            "num_collections": 1
        }
    ],
    "pagination": { ... }
}

Get Database Metadata

Fetch the complete metadata document for a single database, including its schema.

GET /api/get_metadata

Query Parameters

database_id=60c72b2f9b1d8b1a2d3e4567

Example Response

{
    "success": true,
    "data": {
        "_id": "60c72b2f9b1d8b1a2d3e4567",
        "user_id": "...",
        "displayName": "my_customer_project",
        "dbName": "my_customer_project_689547_V2",
        "collections": [ ... ]
    }
}

List Collections

Retrieve all collections in a database along with their live document counts.

GET /api/list_collections

Query Parameters

database_id=60c72b2f9b1d8b1a2d3e4567

Example Response

{
    "success": true,
    "collections": [
        {"name": "users", "num_documents": 152},
        {"name": "products", "num_documents": 840}
    ]
}

Drop Database

Permanently delete a logical database and all of its collections and documents.

DELETE /api/drop_database

Request Body

{
    "database_id": "60c72b2f9b1d8b1a2d3e4567",
    "confirmation": "my_customer_project"
}

Example Response

{
    "success": true,
    "message": "Database 'my_customer_project' was successfully dropped."
}

Drop Collections

Permanently delete one or more collections from a database.

DELETE /api/drop_collections

Request Body

{
    "database_id": "60c72b2f9b1d8b1a2d3e4567",
    "collection_names": ["old_logs", "temporary_users"]
}

Example Response

{
    "success": true,
    "dropped_collections": ["old_logs", "temporary_users"]
}

Import Data (File Upload)

Bulk import documents into a collection from a JSON file.

POST /api/import_data

Request Body

# This is a multipart/form-data request
{
    "database_id": "60c72b2f9b1d8b1a2d3e4567",
    "collection_name": "events",  # optional
    "json_file": (binary content of your .json file)
}

Example Response

{
    "success": true,
    "collection": "events",
    "inserted_count": 5210
}

Data API

Endpoints for all programmatic Create, Read, Update, and Delete (CRUD) operations on your documents. All requests to this API group must be authenticated using an API Key.

Authentication Header

Authorization: Api-Key <YOUR_API_KEY>

API Keys can be generated in your user dashboard after logging in. They are long-lived and designed for use in your backend services, scripts, and applications.

CRUD Documents

Perform operations on documents within a specific collection.

POST (Create) /api/crud

Request Body

{
    "database_id": "60c72b2f9b1d8b1a2d3e4567",
    "collection_name": "users",
    "data": [
        {"email": "alice@example.com", "signup_date": "2023-10-27T10:00:00Z"},
        {"email": "bob@example.com", "signup_date": "2023-10-27T11:00:00Z"}
    ]
}

Example Response

{
    "success": true,
    "inserted_ids": ["..."]
}

GET (Read) /api/crud

Query Parameters

database_id=...&collection_name=...&filters={"email": "alice@example.com"}

Example Response

{
    "success": true,
    "data": [ ... ],
    "pagination": { ... }
}

PUT (Update) /api/crud

Request Body

{
    "database_id": "60c72b2f9b1d8b1a2d3e4567",
    "collection_name": "users",
    "filters": {"email": "alice@example.com"},
    "update_data": {"newsletter_subscribed": true}
}

Example Response

{
    "success": true,
    "modified_count": 1
}