ZeroDB Platform Developer Guide: Complete API Reference and Tutorial

# ZeroDB Platform Developer Guide > **Last Updated:** December 13, 2025 --- ## 🚀 Quick Start (5 Minutes) Get started with ZeroDB in 5 minutes. This example creates a project, stores a document with AI embeddings, and performs semantic search. > **💡 Tip:** Free tier allows 3 projects. If you already have projects, jump to [Option B](#option-b-use-existing-project) in Step 2. --- ### Step 1: Get Your API Key 1. Sign up at [https://ainative.studio/signup](https://ainative.studio/signup) 2. Navigate to **Developer Settings → API Keys** 3. Click **Create API Key** and copy it **Example:** ``` Your API Key: kLPiP0bzgKJ0CnNYVt1wq3qxbs2QgDeF2XwyUnxBEOM ``` --- ### Step 2: Get a Project ID You need a project ID for all API calls. Choose Option A or B: #### Option A: Create New Project ```bash curl -X POST "https://api.ainative.studio/v1/public/projects" \ -H "X-API-Key: YOUR_API_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{ "name": "My First Project", "description": "Getting started with ZeroDB", "tier": "free", "database_enabled": true }' ``` **Success Response:** ```json { "id": "a9b717be-f449-43c6-abb4-18a1a6a0c70e", "name": "My First Project", "tier": "free", "status": "ACTIVE" } ``` **✅ Success Check:** Look for `"status": "ACTIVE"`. Copy the `id` value! **Error Response (Project Limit):** ```json { "detail": "Project limit reached for free tier (3 max)" } ``` **❌ Got this error?** Use Option B instead ↓ --- #### Option B: Use Existing Project ```bash # List your existing projects curl "https://api.ainative.studio/v1/public/projects" \ -H "X-API-Key: YOUR_API_KEY_HERE" ``` **Response:** ```json { "items": [ { "id": "f3bd73fe-8e0b-42b7-8fa1-02951bf7724f", "name": "My Existing Project", "status": "ACTIVE" } ] } ``` **✅ Success Check:** Copy any `id` from the list. --- **💡 IMPORTANT: You now have your `PROJECT_ID`. Let's use it!** **Example values we'll use:** - `PROJECT_ID`: `a9b717be-f449-43c6-abb4-18a1a6a0c70e` - `API_KEY`: `kLPiP0bzgKJ0CnNYVt1wq3qxbs2QgDeF2XwyUnxBEOM` --- ### Step 3: Store a Document with Embeddings Now replace `YOUR_PROJECT_ID` and `YOUR_API_KEY` with your actual values: **Template:** ```bash curl -X POST "https://api.ainative.studio/v1/public/YOUR_PROJECT_ID/embeddings/embed-and-store" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "documents": [ { "id": "doc_1", "text": "ZeroDB is a unified database platform with PostgreSQL, vectors, and AI.", "metadata": { "category": "documentation", "tags": ["database", "ai"] } } ], "namespace": "knowledge_base", "upsert": true }' ``` **Success Response:** ```json { "success": true, "vectors_stored": 1, "embeddings_generated": 1, "model": "BAAI/bge-small-en-v1.5", "dimensions": 384 } ``` **✅ Success Check:** Look for `"success": true` and `"dimensions": 384`. --- ### Step 4: Search Your Knowledge Base ```bash curl -X POST "https://api.ainative.studio/v1/public/YOUR_PROJECT_ID/embeddings/search" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "What is ZeroDB?", "top_k": 5, "namespace": "knowledge_base" }' ``` **Response:** ```json { "results": [ { "id": "doc_1", "score": 0.92, "text": "ZeroDB is a unified database platform with PostgreSQL, vectors, and AI.", "metadata": { "category": "documentation", "tags": ["database", "ai"] } } ], "total_results": 1, "model": "BAAI/bge-small-en-v1.5" } ``` **✅ Success Check:** Look for `"total_results": 1` and a score near 0.9. --- ### 🎉 Congratulations! You Did It! You've completed your first ZeroDB integration: - ✅ Got a project ID (created new or used existing) - ✅ Stored a document with AI embeddings (384 dimensions) - ✅ Performed semantic search using natural language --- ### 🚀 What's Next? | Path | Description | Time | |------|-------------|------| | **Build a RAG System** | Create a chatbot that answers from your docs | 10 min | | **Manage Customer Data** | Store and query with NoSQL tables | 10 min | | **Track Analytics** | Real-time event tracking | 10 min | | **Explore API** | Browse all 40+ endpoints | - | --- ## 📋 Prerequisites & Setup ### What You Need | Requirement | Where to Get It | Time | |-------------|-----------------|------| | **Account** | [Sign up here](https://ainative.studio/signup) | 1 min | | **API Key** | Settings → API Keys → Create | 1 min | | **Project ID** | See Quick Start | 1 min | | **HTTP Client** | curl, Postman, or any language | Already installed | ### Authentication: Which Method? **Option 1: API Key (Recommended)** ```bash -H "X-API-Key: YOUR_API_KEY_HERE" ``` **When to use:** - ✅ Production applications - ✅ Server-to-server communication - ✅ Scripts and automation - ✅ Backend services **When NOT to use:** - ❌ Browser-based apps (exposes your key) - ❌ Mobile apps (key can be extracted) --- **Option 2: JWT Bearer Token** ```bash # Step 1: Get token curl -X POST "https://api.ainative.studio/v1/public/auth/login" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=your@email.com&password=YourPassword123" # Response: {"access_token": "eyJhbGci...", "token_type": "bearer"} # Step 2: Use token curl "https://api.ainative.studio/v1/public/projects" \ -H "Authorization: Bearer eyJhbGci..." ``` **When to use:** - ✅ User-specific sessions - ✅ Mobile applications - ✅ Temporary access --- ### Understanding Projects Every API call needs a `project_id`. Projects provide: - **Data Isolation** - Your data never mixes with other projects - **Resource Limits** - Based on tier (free: 10K vectors, pro: 100K) - **Billing Scope** - Usage tracked per project **Get your projects:** ```bash curl "https://api.ainative.studio/v1/public/projects" \ -H "X-API-Key: YOUR_API_KEY" ``` --- ### API Endpoint Structure All ZeroDB endpoints follow this pattern: ``` https://api.ainative.studio/v1/public/{project_id}/{resource}/{action} ``` **Examples:** ``` /v1/public/a9b717be.../embeddings/search /v1/public/a9b717be.../database/vectors/upsert /v1/public/a9b717be.../database/tables/customers/rows ``` --- ## 💡 Common Use Cases ### Use Case 1: RAG System **Goal:** Build a chatbot that answers questions using your documents. ```python import requests # Configuration API_KEY = "your_api_key" PROJECT_ID = "your_project_id" BASE_URL = "https://api.ainative.studio/v1/public" headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"} # Step 1: Load your knowledge base documents = [ { "id": "faq_1", "text": "How do I reset my password? Click 'Forgot Password' on the login page.", "metadata": {"type": "faq", "category": "authentication"} }, { "id": "faq_2", "text": "How do I upgrade my plan? Visit Settings > Billing > Change Plan.", "metadata": {"type": "faq", "category": "billing"} } ] response = requests.post( f"{BASE_URL}/{PROJECT_ID}/embeddings/embed-and-store", headers=headers, json={ "documents": documents, "namespace": "customer_support", "upsert": True } ) print(f"✅ Stored {response.json()['vectors_stored']} documents") # Step 2: Search when user asks user_question = "I can't log in to my account" search_response = requests.post( f"{BASE_URL}/{PROJECT_ID}/embeddings/search", headers=headers, json={ "query": user_question, "top_k": 3, "namespace": "customer_support", "similarity_threshold": 0.7 } ) print(f"🔍 Question: {user_question}") print("📚 Relevant answers:") for result in search_response.json()['results']: print(f" • Score: {result['score']:.2f} - {result['text']}") ``` **Output:** ``` ✅ Stored 2 documents 🔍 Question: I can't log in to my account 📚 Relevant answers: • Score: 0.88 - How do I reset my password? Click 'Forgot Password'... ``` --- ### Use Case 2: Customer Data Management **Goal:** Store and query customer data with NoSQL tables. ```bash export API_KEY="your_api_key" export PROJECT_ID="your_project_id" # Create table curl -X POST "https://api.ainative.studio/v1/public/${PROJECT_ID}/database/tables" \ -H "X-API-Key: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "name": "customers", "schema": { "id": "UUID PRIMARY KEY", "name": "TEXT NOT NULL", "email": "TEXT UNIQUE", "tier": "TEXT" } }' # Insert customer curl -X POST "https://api.ainative.studio/v1/public/${PROJECT_ID}/database/tables/customers/rows" \ -H "X-API-Key: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "row_data": { "name": "John Doe", "email": "john@example.com", "tier": "pro" } }' # Query customers curl "https://api.ainative.studio/v1/public/${PROJECT_ID}/database/tables/customers/rows?limit=100" \ -H "X-API-Key: ${API_KEY}" ``` --- ### Use Case 3: Real-Time Event Tracking **Goal:** Track user events for analytics. ```python import requests from datetime import datetime API_KEY = "your_api_key" PROJECT_ID = "your_project_id" BASE_URL = "https://api.ainative.studio/v1/public" headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"} def track_event(event_type, user_id, data): response = requests.post( f"{BASE_URL}/{PROJECT_ID}/database/events", headers=headers, json={ "event_type": event_type, "data": {"user_id": user_id, **data}, "timestamp": datetime.utcnow().isoformat() + "Z" } ) if response.status_code == 200: print(f"✅ Tracked: {event_type} for user {user_id}") # Track events track_event("page_view", "user_123", {"page": "/dashboard"}) track_event("purchase", "user_456", {"amount": 99.99}) ``` --- ## 🎯 API Overview **Platform:** ZeroDB Unified Database **Base URL:** `https://api.ainative.studio` **Version:** v1 **Status:** ✅ Production Ready ### 🚨 Critical Requirements | Requirement | Details | Why It Matters | |-------------|---------|----------------| | **Embeddings Model** | `BAAI/bge-small-en-v1.5` | Using `custom-1536` causes 500 errors | | **Vector Dimensions** | **384** (NOT 1536) | Mismatches cause errors | | **Vector Endpoint** | `/database/` prefix required | Without it: 404 errors | | **Table Row Param** | `row_data` (NOT `rows`) | Using `rows` causes 422 errors | --- ## 📖 Complete API Reference ### Projects API #### Create Project **Endpoint:** `POST /v1/public/projects` **Request:** ```bash curl -X POST "https://api.ainative.studio/v1/public/projects" \ -H "X-API-Key: your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "My AI Project", "tier": "pro", "database_enabled": true }' ``` **Parameters:** | Parameter | Type | Required | Default | |-----------|------|----------|---------| | `name` | string | ✅ Yes | - | | `tier` | string | No | `"free"` | | `database_enabled` | boolean | No | `true` | **Success (201):** ```json { "id": "a9b717be-f449-43c6-abb4-18a1a6a0c70e", "name": "My AI Project", "status": "ACTIVE" } ``` **Errors:** - `400` - Invalid tier - `403` - Project limit exceeded - `401` - Invalid API key --- #### List Projects **Endpoint:** `GET /v1/public/projects` ```bash curl "https://api.ainative.studio/v1/public/projects?skip=0&limit=100" \ -H "X-API-Key: your_api_key" ``` **Response:** ```json { "items": [ { "id": "a9b717be...", "name": "My Project", "status": "ACTIVE" } ], "total": 1 } ``` --- ### Embeddings API Generate 384-dimension vectors using BAAI/bge-small-en-v1.5. **Model Details:** - **Dimensions:** 384 (NOT 1536) - **Performance:** ~380ms per request - **Cost:** FREE - **Max Batch:** 100 texts > ⚠️ **CRITICAL**: Always use **384 dimensions** --- #### Generate Embeddings **Endpoint:** `POST /v1/public/{project_id}/embeddings/generate` ```bash curl -X POST "https://api.ainative.studio/v1/public/YOUR_PROJECT_ID/embeddings/generate" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "texts": ["How to deploy?", "API security?"], "model": "BAAI/bge-small-en-v1.5" }' ``` **Response:** ```json { "embeddings": [[0.123, -0.456, ...], [0.234, ...]], "model": "BAAI/bge-small-en-v1.5", "dimensions": 384, "count": 2 } ``` --- #### Embed and Store **Endpoint:** `POST /v1/public/{project_id}/embeddings/embed-and-store` Generates embeddings AND stores them. **Recommended for RAG.** ```bash curl -X POST "https://api.ainative.studio/v1/public/YOUR_PROJECT_ID/embeddings/embed-and-store" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "documents": [ { "id": "doc_1", "text": "FastAPI is a modern Python framework.", "metadata": {"category": "docs"} } ], "namespace": "knowledge_base", "upsert": true }' ``` **Response:** ```json { "success": true, "vectors_stored": 1, "model": "BAAI/bge-small-en-v1.5", "dimensions": 384 } ``` --- #### Semantic Search **Endpoint:** `POST /v1/public/{project_id}/embeddings/search` ```bash curl -X POST "https://api.ainative.studio/v1/public/YOUR_PROJECT_ID/embeddings/search" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "How to build APIs in Python?", "top_k": 5, "namespace": "knowledge_base", "similarity_threshold": 0.7 }' ``` **Parameters:** | Parameter | Type | Default | |-----------|------|---------| | `query` | string | Required | | `top_k` | integer | `10` | | `namespace` | string | `null` | | `similarity_threshold` | number | `0.0` | **Response:** ```json { "results": [ { "id": "doc_1", "score": 0.92, "text": "FastAPI is...", "metadata": {"category": "docs"} } ], "total_results": 1 } ``` --- ### Vector Operations > ⚠️ **CRITICAL**: Use `/database/` prefix: > - ✅ `/v1/public/{id}/database/vectors/upsert` > - ❌ `/v1/public/{id}/vectors/upsert` (404) #### Upsert Vector ```bash curl -X POST "https://api.ainative.studio/v1/public/YOUR_PROJECT_ID/database/vectors/upsert" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "doc_123", "vector": [0.1, 0.2, ... (384 total)], "metadata": {"title": "AI Healthcare"}, "namespace": "documents" }' ``` **⚠️ Vector must be 384 dimensions** --- ### Tables API #### Create Table ```bash curl -X POST "https://api.ainative.studio/v1/public/YOUR_PROJECT_ID/database/tables" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "customers", "schema": { "id": "UUID PRIMARY KEY", "name": "TEXT NOT NULL", "email": "TEXT UNIQUE" } }' ``` --- #### Insert Row ```bash curl -X POST "https://api.ainative.studio/v1/public/YOUR_PROJECT_ID/database/tables/customers/rows" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "row_data": { "name": "John Doe", "email": "john@example.com" } }' ``` **⚠️ Use `row_data` (NOT `data` or `rows`)** --- ## 🔍 Troubleshooting ### ❌ "Embedding model 'custom-1536' not found" **Status:** 500 Internal Server Error **Solution:** ```json { "model": "BAAI/bge-small-en-v1.5" } ``` --- ### ❌ "Vector dimension mismatch. Expected 384, got 1536" **Status:** 500 Internal Server Error **Solution:** Generate embeddings first: ```python # Generate 384-dim embeddings response = requests.post( f"{BASE_URL}/{PROJECT_ID}/embeddings/generate", headers=headers, json={"texts": ["text"], "model": "BAAI/bge-small-en-v1.5"} ) embedding = response.json()['embeddings'][0] # 384 dims # Use in vector ops requests.post( f"{BASE_URL}/{PROJECT_ID}/database/vectors/upsert", headers=headers, json={"id": "doc_1", "vector": embedding} ) ``` --- ### ❌ "404 Not Found" on vectors endpoint **Status:** 404 Not Found **Wrong:** ``` POST /v1/public/{id}/vectors/upsert ``` **Correct:** ``` POST /v1/public/{id}/database/vectors/upsert ``` --- ### ❌ "Field 'row_data' required" **Status:** 422 Unprocessable Entity **Wrong:** ```json {"data": {"name": "John"}} ``` **Correct:** ```json {"row_data": {"name": "John"}} ``` --- ### ❌ "401 Unauthorized" **Solution:** 1. Verify API key in dashboard 2. Generate new key if needed 3. Check `X-API-Key` header --- ### ❌ "403 Project limit reached" **Tiers:** - Free: 3 projects - Pro: 10 projects - Scale: 50 projects **Solution:** Delete unused projects or upgrade --- ## 🚀 Best Practices ### 1. Embeddings & Vectors **✅ DO:** - Use **384 dimensions** (BAAI/bge-small-en-v1.5) - Batch up to 100 texts per request - Use namespaces for organization - Set `similarity_threshold: 0.7` **❌ DON'T:** - Don't use 1536 dimensions - Don't send single texts in loops - Don't mix embedding models --- ### 2. Security **✅ DO:** - Use API keys for production - Store in environment variables - Rotate every 90 days - Separate dev/staging/prod keys **❌ DON'T:** - Don't commit keys to git - Don't expose in client code - Don't share between team members --- ### 3. Error Handling ```python def api_call_with_retry(url, headers, data, max_retries=3): for attempt in range(max_retries): try: response = requests.post(url, headers=headers, json=data, timeout=30) if response.status_code == 200: return response.json() elif response.status_code == 429: sleep(2 ** attempt) # Exponential backoff continue except requests.exceptions.Timeout: if attempt < max_retries - 1: sleep(2 ** attempt) return None ``` --- ### 4. Performance **✅ DO:** - Implement pagination (max 1000) - Use metadata filters - Cache embeddings - Batch operations **Example:** ```python # ✅ Batch insert requests.post( f"{BASE_URL}/{PROJECT_ID}/database/vectors/upsert-batch", json={"vectors": [v1, v2, v3]} # Up to 1000 ) # ❌ Individual inserts for vector in vectors: requests.post(...) # Slow! ``` --- ## 📊 Usage Limits | Tier | Projects | Vectors | Requests/hr | Storage | |------|----------|---------|-------------|---------| | **Free** | 3 | 10K | 1K | 1 GB | | **Pro** | 10 | 100K | 10K | 10 GB | | **Scale** | 50 | 1M | 100K | 100 GB | | **Enterprise** | ∞ | ∞ | Custom | Custom | --- ## 🔗 Resources - **Interactive Docs:** [https://api.ainative.studio/docs](https://api.ainative.studio/docs) - **Dashboard:** [https://dashboard.ainative.studio](https://dashboard.ainative.studio) - **Support:** support@ainative.studio - **Status:** [https://status.ainative.studio](https://status.ainative.studio) --- **Ready to build?** [Get started now →](https://ainative.studio/signup)

ZeroDB Platform Developer Guide: Complete API Reference and Tutorial

Check your site's AX Score