Getting Started with Singlebase

Singlebase provides a complete backend-as-a-service platform with APIs for data storage, authentication, AI processing, and file management. This guide will get you up and running in minutes.

Account Setup

1. Sign Up and Create Project

1. Visit Singlebase Console
2. Sign up with your email and password
3. Create a new project
4. Note your credentials:
   • API-Key: Found in Project Settings → API Keys
   • Project-ID: Displayed in your project dashboard

Singlebase API Structure

Single API Endpoint

All Singlebase services use one unified API endpoint:

[POST] https://cloud.singlebaseapis.com/api/<$PROJECT-ID>

Instead of multiple endpoints for different operations, everything goes through this single URL using different op (operation) parameters in the request body.

DDO: (Data Directive Object)

Singlebase provides a modern, unified Data Directive Object (DDO) language inspired by MongoDB but designed for clarity and comprehensive functionality across your entire application stack.

DDO uses a core data structure - a simple dictionary/JSON that describes what you want to do across your application. Whether you're querying and mutating document-based databases, handling authentication, managing file uploads, performing vector database operations, integrating AI services, or executing other application functions, you express your intentions through these structured objects that form the foundation of all DDO operations.

DDO uses simple dictionary structures that describe what you want to do with your data. Every request is a DDO containing an op field that specifies the operation:

{
  "op": "collection.find",     // The operation to perform
  "collection": "users",       // Operation-specific parameters
  "match": { "status": "active" },
  "limit": 10
}

DDO Benefits:

• Consistent: Same request format across all APIs
• Simple: Plain JSON objects, no complex query syntax
• Powerful: Supports complex filtering with operators like $gt, $in, $regex
• Familiar: Similar to MongoDB query syntax but streamlined

Authentication Headers

All API requests require these headers:

X-API-KEY: your_project_api_key
Authorization: Bearer your_jwt_token
Content-Type: application/json

Authentication Headers

All API requests require these headers:

X-API-KEY: your_project_api_key
Authorization: Bearer your_jwt_token
Content-Type: application/json

Core Concepts

Collections and Documents

Collections are containers for related data (like tables in SQL). Documents are JSON objects stored within collections. Every document has these automatic properties:

{
  "_key": "550e8400e29b41d4a716446655440000",  // UUID4 without dashes
  "_userkey": "user_abc123",                    // Owner (current user)
  "_created_at": "2024-01-15T10:30:00.000Z",   // Creation timestamp
  "_modified_at": "2024-01-15T10:30:00.000Z",  // Last modified timestamp
  
  // Your custom fields
  "name": "John Doe",
  "email": "john@example.com"
}

Privacy: Documents are private to their owner (_userkey) by default. Users can only access documents they created.

API Examples

Datastore API

Store and query JSON documents with powerful filtering capabilities.

Insert a document:

const response = await fetch('https://cloud.singlebaseapis.com/api/collection.insert', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'collection.insert',
    collection: 'users',
    data: {
      name: 'John Doe',
      email: 'john@example.com',
      role: 'developer'
    }
  })
});

Find documents:

const response = await fetch('https://cloud.singlebaseapis.com/api/collection.find', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'collection.find',
    collection: 'users',
    match: { role: 'developer' },
    limit: 10
  })
});

Auth API

Complete user authentication and management system.

Sign up a user:

const response = await fetch('https://cloud.singlebaseapis.com/api/auth.signup', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'auth.signup',
    email: 'user@example.com',
    password: 'securePassword123',
    display_name: 'John Doe'
  })
});

Sign in a user:

const response = await fetch('https://cloud.singlebaseapis.com/api/auth.signin', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'auth.signin',
    grant_type: 'password',
    email: 'user@example.com',
    password: 'securePassword123'
  })
});

// Response includes JWT tokens for subsequent API calls
// Use response.data.id_token in Authorization header

Storage API

Secure file upload and management with automatic processing.

Get presigned upload URL:

const response = await fetch('https://cloud.singlebaseapis.com/api/file.presign_upload', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'file.presign_upload',
    filename: 'profile.jpg',
    content_type: 'image/jpeg',
    public_read: true
  })
});

Get file information:

const response = await fetch('https://cloud.singlebaseapis.com/api/file.info', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'file.info',
    _key: 'file_abc123xyz789'
  })
});

VectorStore API

AI-powered semantic search and content similarity matching.

Insert content for vector search:

const response = await fetch('https://cloud.singlebaseapis.com/api/vdb.insert', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'vdb.insert',
    collection: 'knowledge_base',
    data: [
      {
        content: 'Machine learning is a subset of artificial intelligence that enables computers to learn from data.',
        content_type: 'text',
        metadata: {
          category: 'ai',
          tags: ['machine-learning', 'ai']
        }
      }
    ]
  })
});

Search with natural language:

const response = await fetch('https://cloud.singlebaseapis.com/api/vdb.search', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'vdb.search',
    query: 'What is machine learning?',
    collection: 'knowledge_base'
  })
});

XAI API

AI-powered content generation, analysis, and processing.

Generate content:

const response = await fetch('https://cloud.singlebaseapis.com/api/xai.generate', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'xai.generate',
    user_input: 'Write a brief introduction to cloud computing',
    options: {
      content_length: 200,
      content_style: 'professional'
    }
  })
});

Analyze sentiment:

const response = await fetch('https://cloud.singlebaseapis.com/api/xai.sentiment', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'xai.sentiment',
    content: 'I absolutely love this new product! It works perfectly and exceeded my expectations.',
    options: {
      analysis_depth: 'detailed'
    }
  })
});

Quick Start Workflow

1. Authentication Flow

// 1. Sign up user
const signup = await fetch('/api/auth.signup', { /* signup data */ });

// 2. Sign in to get tokens
const signin = await fetch('/api/auth.signin', { /* signin data */ });
const { id_token } = signin.data;

// 3. Use token for subsequent requests
const headers = {
  'X-API-KEY': 'your-api-key',
  'Authorization': `Bearer ${id_token}`,
  'Content-Type': 'application/json'
};

2. Data Storage

// Create user profile
const profile = await fetch('/api/collection.insert', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    op: 'collection.insert',
    collection: 'profiles',
    data: { name: 'John', preferences: { theme: 'dark' } }
  })
});

// Query user data
const userData = await fetch('/api/collection.find', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    op: 'collection.find',
    collection: 'profiles',
    match: { name: 'John' }
  })
});

3. File Upload

// Get upload URL
const presign = await fetch('/api/file.presign_upload', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    op: 'file.presign_upload',
    filename: 'avatar.jpg',
    content_type: 'image/jpeg'
  })
});

// Upload file to presigned URL
const formData = new FormData();
Object.entries(presign.data.presigned_data.fields).forEach(([key, value]) => {
  formData.append(key, value);
});
formData.append('file', fileBlob);

await fetch(presign.data.presigned_data.url, {
  method: 'POST',
  body: formData
});

// Complete upload
await fetch('/api/file.postsign_upload', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    op: 'file.postsign_upload',
    _key: presign.data.info._key,
    presigned_data: presign.data.presigned_data
  })
});

Common Patterns

Error Handling

async function apiRequest(endpoint, data) {
  try {
    const response = await fetch(`https://cloud.singlebaseapis.com/api/${endpoint}`, {
      method: 'POST',
      headers: {
        'X-API-KEY': 'your-api-key',
        'Authorization': 'Bearer your-jwt-token',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('API Error:', error.message);
    throw error;
  }
}

Pagination

async function getAllUsers() {
  let page = 1;
  let allUsers = [];
  let hasMore = true;

  while (hasMore) {
    const response = await apiRequest('collection.find', {
      op: 'collection.find',
      collection: 'users',
      page: page,
      per_page: 100
    });

    allUsers.push(...response.data);
    hasMore = response.meta.pagination.has_next;
    page++;
  }

  return allUsers;
}

SDKs and Tools

Singlebase works with any HTTP client. Popular choices:

• JavaScript: fetch, axios, or our official SDK
• Python: requests library or official SDK
• cURL: For testing and automation
• Postman: For API exploration and testing