ZeroDB API Reference

Complete API documentation for ZeroDB integration in OpenCap Stack

Last Updated: 2026-02-02 API Version: v1 Base URL: https://api.ainative.studio/api/v1

Authentication
Project Management
Database Operations
Vector Search
Memory Management
Event Streaming
File Storage
Error Handling
Rate Limits

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Obtaining an API Token

Sign up at https://api.ainative.studio/
Navigate to Account Settings
Click "Generate API Token"
Copy the token and use it in all API requests

Request Format

curl -X GET "https://api.ainative.studio/api/v1/endpoint" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Project Management

Create Project

POST /projects/

Creates a new ZeroDB project for your application.

Request:

curl -X POST "https://api.ainative.studio/api/v1/projects/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenCap Production",
    "description": "Financial management system"
  }'

Request Body:

{
  "name": "string (required)",
  "description": "string (optional)"
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "OpenCap Production",
  "description": "Financial management system",
  "user_id": "user-uuid",
  "created_at": "2026-02-02T10:30:00.000Z",
  "updated_at": null
}

List Projects

GET /projects/

Retrieves all projects for the authenticated user.

Request:

curl -X GET "https://api.ainative.studio/api/v1/projects/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "OpenCap Production",
    "description": "Financial management system",
    "user_id": "user-uuid",
    "created_at": "2026-02-02T10:30:00.000Z",
    "updated_at": null
  }
]

Database Operations

Get Database Status

GET /projects/{project_id}/database/status

Check the status of your database and get usage statistics.

Request:

curl -X GET "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "enabled": true,
  "tables_count": 12,
  "vectors_count": 1500,
  "memory_records_count": 230,
  "events_count": 5400,
  "files_count": 87
}

Create Table

POST /projects/{project_id}/database/tables

Creates a new table in ZeroDB with specified schema.

Request:

curl -X POST "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/tables" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "companies",
    "schema_definition": {
      "id": "uuid",
      "name": "string",
      "type": "string",
      "founded_date": "timestamp",
      "valuation": "number",
      "metadata": "json"
    }
  }'

Request Body:

{
  "table_name": "string (required)",
  "schema_definition": {
    "field_name": "data_type",
    ...
  }
}

Supported Data Types:

string - Text data
number - Numeric values (int or float)
boolean - True/false values
timestamp - Date/time values
uuid - Unique identifiers
json - Complex nested objects
array - Lists of values

Response:

{
  "table_id": "table-uuid",
  "project_id": "project-uuid",
  "table_name": "companies",
  "schema_definition": { ... },
  "created_at": "2026-02-02T10:30:00.000Z"
}

List Tables

GET /projects/{project_id}/database/tables

Retrieves all tables in the project.

Request:

curl -X GET "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/tables" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

[
  {
    "table_id": "table-uuid",
    "project_id": "project-uuid",
    "table_name": "companies",
    "schema_definition": { ... },
    "created_at": "2026-02-02T10:30:00.000Z"
  }
]

Insert Row

POST /projects/{project_id}/database/tables/{table_name}/rows

Inserts a new row into the specified table.

Request:

curl -X POST "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/tables/companies/rows" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp",
      "type": "C-Corp",
      "founded_date": "2020-01-15T00:00:00Z",
      "valuation": 5000000
    }
  }'

Response:

{
  "row_id": "row-uuid",
  "table_name": "companies",
  "data": { ... },
  "created_at": "2026-02-02T10:30:00.000Z"
}

Query Rows

GET /projects/{project_id}/database/tables/{table_name}/rows

Queries rows from a table with optional filtering.

Request:

curl -X GET "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/tables/companies/rows?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters:

limit (integer, optional): Maximum rows to return (default: 100, max: 1000)
offset (integer, optional): Number of rows to skip (default: 0)
filter (json, optional): Filter criteria (e.g., {"type": "C-Corp"})
sort (string, optional): Sort field (e.g., created_at)
order (string, optional): Sort order (asc or desc)

Response:

{
  "rows": [
    {
      "row_id": "row-uuid",
      "data": {
        "id": "company-uuid",
        "name": "Acme Corp",
        "type": "C-Corp",
        ...
      },
      "created_at": "2026-02-02T10:30:00.000Z",
      "updated_at": "2026-02-02T11:00:00.000Z"
    }
  ],
  "total_count": 1,
  "limit": 10,
  "offset": 0
}

Update Row

PUT /projects/{project_id}/database/tables/{table_name}/rows/{row_id}

Updates an existing row in the table.

Request:

curl -X PUT "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/tables/companies/rows/ROW_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "valuation": 7500000,
      "updated_at": "2026-02-02T11:00:00Z"
    }
  }'

Response:

{
  "row_id": "row-uuid",
  "table_name": "companies",
  "data": { ... },
  "updated_at": "2026-02-02T11:00:00.000Z"
}

Delete Row

DELETE /projects/{project_id}/database/tables/{table_name}/rows/{row_id}

Deletes a row from the table.

Request:

curl -X DELETE "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/tables/companies/rows/ROW_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "deleted": true,
  "row_id": "row-uuid"
}

Vector Search

Upsert Vector

POST /projects/{project_id}/database/vectors/upsert

Stores or updates a vector embedding with associated metadata.

Request:

curl -X POST "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/vectors/upsert" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vector_embedding": [0.1, 0.2, 0.3, ..., 0.768],
    "namespace": "documents",
    "vector_metadata": {
      "document_id": "doc-123",
      "type": "financial_report",
      "category": "annual_report"
    },
    "document": "Full text of the document for reference",
    "source": "document_upload"
  }'

Request Body:

{
  "vector_embedding": [array of floats] (required),
  "namespace": "string" (optional, default: "default"),
  "vector_metadata": {object} (optional),
  "document": "string" (optional),
  "source": "string" (optional)
}

Response:

{
  "vector_id": "vector-uuid",
  "project_id": "project-uuid",
  "namespace": "documents",
  "vector_embedding": [0.1, 0.2, ...],
  "vector_metadata": { ... },
  "document": "Full text...",
  "source": "document_upload",
  "created_at": "2026-02-02T10:30:00.000Z"
}

Search Vectors

POST /projects/{project_id}/database/vectors/search

Performs similarity search to find vectors closest to a query vector.

Request:

curl -X POST "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/vectors/search" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query_vector": [0.1, 0.2, 0.3, ..., 0.768],
    "limit": 10,
    "namespace": "documents",
    "filter": {
      "type": "financial_report"
    }
  }'

Request Body:

{
  "query_vector": [array of floats] (required),
  "limit": integer (required, max: 100),
  "namespace": "string" (optional),
  "filter": {object} (optional)
}

Response:

{
  "vectors": [
    {
      "vector_id": "vector-uuid",
      "similarity_score": 0.95,
      "vector_embedding": [0.1, 0.2, ...],
      "vector_metadata": { ... },
      "document": "Full text...",
      "source": "document_upload"
    }
  ],
  "total_count": 10,
  "search_time_ms": 15.3
}

List Vectors

GET /projects/{project_id}/database/vectors

Retrieves vectors with optional filtering by namespace.

Request:

curl -X GET "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/vectors?namespace=documents&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters:

namespace (string, optional): Filter by namespace
limit (integer, optional): Maximum vectors to return (default: 100)
offset (integer, optional): Number of vectors to skip

Response:

{
  "vectors": [ ... ],
  "total_count": 1500,
  "limit": 50,
  "offset": 0
}

Memory Management

Store Memory

POST /projects/{project_id}/database/memory/store

Stores agent memory for context retention across sessions.

Request:

curl -X POST "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/memory/store" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-uuid",
    "session_id": "session-uuid",
    "role": "user",
    "content": "What is the current valuation of Acme Corp?",
    "memory_metadata": {
      "context": "financial_query",
      "importance": "high"
    }
  }'

Request Body:

{
  "agent_id": "uuid" (optional),
  "session_id": "uuid" (optional),
  "role": "string" (optional: user, assistant, system),
  "content": "string" (required),
  "memory_metadata": {object} (optional)
}

Response:

{
  "memory_id": "memory-uuid",
  "project_id": "project-uuid",
  "agent_id": "agent-uuid",
  "session_id": "session-uuid",
  "role": "user",
  "content": "What is the current valuation...",
  "embedding": [0.1, 0.2, ...],
  "memory_metadata": { ... },
  "created_at": "2026-02-02T10:30:00.000Z"
}

List Memory

GET /projects/{project_id}/database/memory

Retrieves memory records with filtering options.

Request:

curl -X GET "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/memory?agent_id=AGENT_ID&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters:

agent_id (uuid, optional): Filter by agent
session_id (uuid, optional): Filter by session
role (string, optional): Filter by role
limit (integer, optional): Maximum records (default: 100)
offset (integer, optional): Skip records

Response:

{
  "memory_records": [ ... ],
  "total_count": 230,
  "limit": 20,
  "offset": 0
}

Event Streaming

Publish Event

POST /projects/{project_id}/database/events/publish

Publishes an event to the event stream.

Request:

curl -X POST "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/events/publish" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "financial_transaction",
    "event_payload": {
      "transaction_id": "txn-123",
      "type": "investment",
      "amount": 100000,
      "investor_id": "investor-456",
      "timestamp": "2026-02-02T10:30:00Z"
    }
  }'

Request Body:

{
  "topic": "string" (required),
  "event_payload": {object} (required)
}

Response:

{
  "event_id": "event-uuid",
  "project_id": "project-uuid",
  "topic": "financial_transaction",
  "event_payload": { ... },
  "published_at": "2026-02-02T10:30:00.000Z"
}

List Events

GET /projects/{project_id}/database/events

Retrieves events from the event stream.

Request:

curl -X GET "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/events?topic=financial_transaction&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters:

topic (string, optional): Filter by topic
limit (integer, optional): Maximum events (default: 100)
offset (integer, optional): Skip events
start_time (timestamp, optional): Filter by start time
end_time (timestamp, optional): Filter by end time

Response:

{
  "events": [ ... ],
  "total_count": 5400,
  "limit": 50,
  "offset": 0
}

File Storage

Upload File Metadata

POST /projects/{project_id}/database/files/upload

Registers file metadata (not the file itself - use S3 or similar for actual file storage).

Request:

curl -X POST "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/files/upload" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_key": "documents/2026/annual_report.pdf",
    "file_name": "annual_report_2025.pdf",
    "content_type": "application/pdf",
    "size_bytes": 2048576,
    "file_metadata": {
      "company_id": "company-123",
      "year": 2025,
      "category": "annual_report",
      "uploaded_by": "user-456"
    }
  }'

Request Body:

{
  "file_key": "string" (required),
  "file_name": "string" (optional),
  "content_type": "string" (optional),
  "size_bytes": integer (optional),
  "file_metadata": {object} (optional)
}

Response:

{
  "file_id": "file-uuid",
  "project_id": "project-uuid",
  "file_key": "documents/2026/annual_report.pdf",
  "file_name": "annual_report_2025.pdf",
  "content_type": "application/pdf",
  "size_bytes": 2048576,
  "file_metadata": { ... },
  "created_at": "2026-02-02T10:30:00.000Z"
}

List Files

GET /projects/{project_id}/database/files

Retrieves file metadata records.

Request:

curl -X GET "https://api.ainative.studio/api/v1/projects/PROJECT_ID/database/files?limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters:

limit (integer, optional): Maximum files (default: 100)
offset (integer, optional): Skip files

Response:

{
  "files": [ ... ],
  "total_count": 87,
  "limit": 20,
  "offset": 0
}

Error Handling

HTTP Status Codes

200 OK - Request succeeded
201 Created - Resource created successfully
400 Bad Request - Invalid request parameters
401 Unauthorized - Missing or invalid authentication
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
422 Unprocessable Entity - Validation error
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "vector_embedding",
      "reason": "Must be an array of floats"
    }
  }
}

Common Error Codes

AUTH_ERROR - Authentication failure
VALIDATION_ERROR - Request validation failed
NOT_FOUND - Resource not found
RATE_LIMIT_EXCEEDED - Too many requests
INTERNAL_ERROR - Server error

Rate Limits

Current Limits

Requests per second: 100
Requests per minute: 5000
Concurrent connections: 50

Rate Limit Headers

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4850
X-RateLimit-Reset: 1643800000

Handling Rate Limits

When you receive a 429 response:

Check the X-RateLimit-Reset header
Wait until the reset time
Implement exponential backoff
Batch your requests where possible

Best Practices

Performance Optimization

Batch Operations: Group multiple inserts/updates when possible
Use Pagination: Always paginate large result sets
Cache Results: Cache frequently accessed data
Index Fields: Create indexes on frequently queried fields

Security

Never Expose API Keys: Keep tokens secure, never commit to git
Use Environment Variables: Store credentials in .env files
Implement Token Rotation: Rotate API tokens regularly
Monitor Access: Track API usage and unusual patterns

Data Integrity

Validate Input: Always validate data before sending
Handle Errors: Implement proper error handling
Use Transactions: Use atomic operations when possible
Backup Data: Maintain regular backups

SDK and Libraries

Node.js Service

OpenCap Stack includes a built-in ZeroDB service:

const zerodbService = require('./services/zerodbService');

// Initialize
await zerodbService.initialize();

// Create table
await zerodbService.createTable('companies', schema);

// Insert row
await zerodbService.insertRow('companies', data);

// Query rows
const results = await zerodbService.queryTable('companies', { type: 'C-Corp' });

// Vector search
const similar = await zerodbService.searchVectors(queryVector, 10, 'documents');

Support

Documentation: https://docs.ainative.studio/
API Status: https://status.ainative.studio/
Email: support@ainative.studio
GitHub Issues: https://github.com/Open-Cap-Stack/opencap/issues

API Version: 1.0 Last Updated: 2026-02-02

Uh oh!

FilesExpand file tree

zerodb-api-reference.md

Latest commit

History

zerodb-api-reference.md

File metadata and controls

ZeroDB API Reference

Table of Contents

Authentication

Obtaining an API Token

Request Format

Project Management

Create Project

List Projects

Database Operations

Get Database Status

Create Table

List Tables

Insert Row

Query Rows

Update Row

Delete Row

Vector Search

Upsert Vector

Search Vectors

List Vectors

Memory Management

Store Memory

List Memory

Event Streaming

Publish Event

List Events

File Storage

Upload File Metadata

List Files

Error Handling

HTTP Status Codes

Error Response Format

Common Error Codes

Rate Limits

Current Limits

Rate Limit Headers

Handling Rate Limits

Best Practices

Performance Optimization

Security

Data Integrity

SDK and Libraries

Node.js Service

Support