Getting Started

Get up and running with Singlebase in minutes. Singlebase provides a complete backend platform with APIs for data storage, authentication, AI processing, and file management - all powered by BaseQL, our unified query language.

Sign Up

1. Visit Singlebase Console
2. Create an account with your email
3. You'll automatically get a Workspace created for you

---

Understanding Workspaces and Projects

Workspaces

A Workspace is the top-level container that groups projects and team members together. Think of it as your organization's space within Singlebase.

Key features:

• Contains multiple projects
• Shared by team members/developers
• Unified billing across all projects
• Shared rate limits and access policies
• Centralized team management

Multiple users can be assigned to a workspace, giving them access to all projects within it. This makes collaboration seamless - your entire team works with the same resources.

Projects

A Project is where your backend lives. Each project is a complete, isolated backend environment with its own resources.

What's included in a project:

• Authentication system (user management, sign-in/sign-up)
• Document Database (NoSQL JSON storage)
• Vector Database (AI-powered semantic search)
• File Storage (secure file uploads and management)
• AI Services (content generation, analysis)

Each project has its own unique API endpoint and API key, keeping your applications separate and secure.

---

Create a Project

1. In your workspace, create a new project
2. Go to Settings to find your project credentials:
   • API Endpoint - Your unique project endpoint URL
   • API Key - Required for all API requests

Finding your credentials: Workspace → Select Project → Settings → API Endpoint & API Key

---

BaseQL

All Singlebase APIs use BaseQL - a simple, MongoDB-inspired query language that works consistently across all operations.

One endpoint for everything:

POST https://cloud.singlebaseapis.com/api/<YOUR_ENDPOINT_KEY>

Key benefits:

• Single endpoint for all operations (Database, Auth, Storage, AI, Vectors)
• Familiar MongoDB-style operators
• Clean, inline syntax
• Powerful expressions and transformations

Learn more about BaseQL →

---

Making API Requests

Required Headers

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

• Content-Type - Always application/json
• X-API-KEY - Your project API key from Settings (required for all requests)
• Authorization - JWT token (required for authenticated operations)

---

Request Format

All requests use BaseQL with op (operation) as the required field:

{
  "op": "operation_name",
  "param1": "value1",
  "param2": "value2"
}

The op field specifies what operation to perform:

• Document Database: db.find, db.insert, db.update, db.delete
• Authentication: auth.signup, auth.signin, auth.signout
• Vector Database: vdb.search, vdb.insert, vdb.delete
• File Storage: file.get, file.update, file.presign_upload, file.finalize_upload
• AI Services: baseai.write, baseai.analyze_sentiment, baseai.summarize

Example - Insert a document:

await fetch('https://cloud.singlebaseapis.com/api/<YOUR_ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key',
    'Authorization': 'Bearer your_jwt_token'
  },
  body: JSON.stringify({
    op: 'db.insert',
    collection: 'users',
    data: {
      name: 'John Doe',
      email: 'john@example.com'
    }
  })
});

Example - Query with filter:

await fetch('https://cloud.singlebaseapis.com/api/<YOUR_ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key',
    'Authorization': 'Bearer your_jwt_token'
  },
  body: JSON.stringify({
    op: 'db.find',
    collection: 'users',
    filter: { 'role': 'developer' },
    limit: 10
  })
});

---

Response Format

All responses are in JSON format with a consistent structure:

Success response:

{
  "data": {
    // Operation result (object, array, or primitive value)
  },
  "meta": {
    "pagination": {
      // Pagination info for list operations
    }
  }
}

Error response:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

Response fields:

• data - Contains the result of the operation
• meta - Optional metadata including pagination details
• error - Present only when the request fails

---

Complete Example

// 1. Sign up a user
await fetch('https://cloud.singlebaseapis.com/api/<YOUR_ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key'
  },
  body: JSON.stringify({
    op: 'auth.signup',
    email: 'user@example.com',
    password: 'securePassword123',
    display_name: 'John Doe'
  })
});

// 2. Sign in and get token
const signInResponse = await fetch('https://cloud.singlebaseapis.com/api/<YOUR_ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key'
  },
  body: JSON.stringify({
    op: 'auth.signin',
    grant_type: 'password',
    email: 'user@example.com',
    password: 'securePassword123'
  })
});

const { id_token } = (await signInResponse.json()).data;

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

// Insert data
await fetch('https://cloud.singlebaseapis.com/api/<YOUR_ENDPOINT_KEY>', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    op: 'db.insert',
    collection: 'tasks',
    data: { title: 'Learn Singlebase', completed: false }
  })
});

// Query data
const tasksResponse = await fetch('https://cloud.singlebaseapis.com/api/<YOUR_ENDPOINT_KEY>', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    op: 'db.find',
    collection: 'tasks',
    filter: { 'completed': false }
  })
});

const tasks = await tasksResponse.json();

---

BaseQL Examples

Database Operations

Insert:

{
  "op": "db.insert",
  "collection": "products",
  "data": { "name": "Widget", "price": 29.99 }
}

Query with filter:

{
  "op": "db.find",
  "collection": "products",
  "filter": { "price:$lt": 50 },
  "sort": "price asc"
}

Update:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": { "score:$incr": 10 }
}

Authentication

Sign up:

{
  "op": "auth.signup",
  "email": "user@example.com",
  "password": "securePass123"
}

Sign in:

{
  "op": "auth.signin",
  "grant_type": "password",
  "email": "user@example.com",
  "password": "securePass123"
}

Vector Search

Semantic search:

{
  "op": "vdb.search",
  "query": "machine learning tutorials",
  "collection": "docs"
}

AI Text

Generate content:

{
  "op": "baseai.create",
  "input": "Write a blog post about AI",
  "content_length": 500
}

---

Available APIs

API	Purpose	Operations
Database	Store and query JSON documents	db.*
Auth	User authentication and management	auth.*
Files	File upload and management	file.*
Vectors	AI-powered semantic search	vdb.*
BaseAI	Content generation and analysis	baseai.*

---

Next Steps

Learn BaseQL:

• BaseQL Documentation - Unified query language
• Filter Operators - Query and match documents
• Data Operators - Transform data
• Template Expressions - Dynamic values

Explore APIs:

• Document Database - Store and query data
• Authentication - Manage users and sessions
• File Storage - Upload and manage files
• Vector Database - Semantic search
• BaseAI - AI-powered features

Resources:

• Developer Guide - Complete feature overview
• API Reference - All operations
• Rate Limits - Usage limits
• Pagination - Handle large datasets