Getting Started with Cocobase

Welcome to Cocobase! This guide will help you set up and make your first API call in just a few minutes.

Prerequisites

Before you begin, make sure you have:

A Cocobase account - Sign up for free
An API key from your project dashboard
Your development environment set up for your preferred language

Installation

Choose your language and install the Cocobase SDK:

JavaScript
Dart
Go
Python
HTTP

npm

npm install cocobase

yarn

yarn add cocobase

pnpm

pnpm add cocobase

Add Cocobase to your pubspec.yaml:

dependencies:
  coco_base_flutter: ^latest_version

Then run:

flutter pub get

go get github.com/cocobase-team/cocobase-go

pip install cocobase

Configuration

Initialize Cocobase with your API key:

JavaScript
Dart
Go
Python
HTTP

import { Cocobase } from "cocobase";

const db = new Cocobase({
  apiKey: "YOUR_API_KEY",
});

For Next.js projects:

// lib/cocobase.ts
import { Cocobase } from "cocobase";

export const db = new Cocobase({
  apiKey: process.env.NEXT_PUBLIC_COCOBASE_API_KEY,
});

For React projects:

// src/lib/cocobase.ts
import { Cocobase } from "cocobase";

export const db = new Cocobase({
  apiKey: import.meta.env.VITE_COCOBASE_API_KEY,
});

import 'package:coco_base_flutter/coco_base_flutter.dart';

void main() {
  // Create configuration
  final config = CocobaseConfig(
    apiKey: "YOUR_API_KEY",
    baseUrl: "https://api.cocobase.cc", // Optional
  );

  // Initialize client
  final db = Cocobase(config);
}

For Flutter apps with environment variables:

import 'package:flutter_dotenv/flutter_dotenv.dart';

await dotenv.load();

final config = CocobaseConfig(
  apiKey: dotenv.env['COCOBASE_API_KEY']!,
);

package main

import (
    "context"
    "github.com/cocobase-team/cocobase-go"
)

func main() {
    // Create client
    client := cocobase.NewClient(cocobase.Config{
        APIKey: "YOUR_API_KEY",
    })

    // Create context
    ctx := context.Background()
}

With custom configuration:

client := cocobase.NewClient(cocobase.Config{
    APIKey:     os.Getenv("COCOBASE_API_KEY"),
    BaseURL:    "https://api.cocobase.cc",
    HTTPClient: &http.Client{Timeout: 30 * time.Second},
})

from cocobase import Cocobase

# Initialize client
db = Cocobase(api_key="YOUR_API_KEY")

With environment variables:

import os
from cocobase import Cocobase

db = Cocobase(api_key=os.getenv("COCOBASE_API_KEY"))

Set up your base URL and headers:Base URL:

https://api.cocobase.cc

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Your First Request

Let’s create a document in a collection called “users”:

JavaScript
Dart
Go
Python
HTTP

// Create a new user
const user = await db.createDocument("users", {
  name: "Alice Johnson",
  email: "alice@example.com",
  role: "developer",
});

console.log("Created user:", user);

Response:

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "role": "developer",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

// Create a new user
final user = await db.createDocument('users', {
  'name': 'Alice Johnson',
  'email': 'alice@example.com',
  'role': 'developer',
});

print('Created user: $user');

Response:

{
  'id': '507f1f77bcf86cd799439011',
  'name': 'Alice Johnson',
  'email': 'alice@example.com',
  'role': 'developer',
  'createdAt': '2024-01-15T10:30:00Z',
  'updatedAt': '2024-01-15T10:30:00Z'
}

// Create a new user
user, err := client.CreateDocument(ctx, "users", map[string]any{
    "name":  "Alice Johnson",
    "email": "alice@example.com",
    "role":  "developer",
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Created user: %+v\n", user)

Response:

map[string]interface{}{
    "id":       "507f1f77bcf86cd799439011",
    "name":      "Alice Johnson",
    "email":     "alice@example.com",
    "role":      "developer",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
}

# Create a new user
user = db.create_document("users", {
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "developer"
})

print(f"Created user: {user}")

Response:

{
    "id": "507f1f77bcf86cd799439011",
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "developer",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
}

curl -X POST https://api.cocobase.cc/collections/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "developer"
  }'

Response:

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "role": "developer",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Reading Data

Now let’s retrieve the document we just created:

JavaScript
Dart
Go
Python
HTTP

// Get all users
const users = await db.listDocuments("users");
console.log("All users:", users);

// Get a specific user by ID
const user = await db.getDocument("users", "507f1f77bcf86cd799439011");
console.log("User:", user);

// Get all users
final users = await db.listDocuments('users');
print('All users: $users');

// Get a specific user by ID
final user = await db.getDocument('users', '507f1f77bcf86cd799439011');
print('User: $user');

// Get all users
users, err := client.ListDocuments(ctx, "users", nil)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("All users: %+v\n", users)

// Get a specific user by ID
user, err := client.GetDocument(ctx, "users", "507f1f77bcf86cd799439011")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("User: %+v\n", user)

# Get all users
users = db.list_documents("users")
print(f"All users: {users}")

# Get a specific user by ID
user = db.get_document("users", "507f1f77bcf86cd799439011")
print(f"User: {user}")

# Get all users
curl -X GET https://api.cocobase.cc/collections/users \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get a specific user by ID
curl -X GET https://api.cocobase.cc/collections/users/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer YOUR_API_KEY"

Environment Variables

For security, always use environment variables for your API key:

JavaScript
Dart
Go
Python
HTTP

Create a .env.local file:

NEXT_PUBLIC_COCOBASE_API_KEY=your_api_key_here
# or for Vite/React
VITE_COCOBASE_API_KEY=your_api_key_here

Create a .env file:

COCOBASE_API_KEY=your_api_key_here

Add to pubspec.yaml:

dependencies:
  flutter_dotenv: ^5.0.2

Create a .env file:

COCOBASE_API_KEY=your_api_key_here

Use with a package like godotenv:

import "github.com/joho/godotenv"

godotenv.Load()
apiKey := os.Getenv("COCOBASE_API_KEY")

Create a .env file:

COCOBASE_API_KEY=your_api_key_here

Use with python-dotenv:

from dotenv import load_dotenv
load_dotenv()

Never commit your .env files to version control. Add them to .gitignore: bash .env .env.local .env*.local

Next Steps

Now that you’ve made your first request, explore these features:

Authentication

Add user registration and login to your app

Query & Filtering

Learn to filter and search your data

Real-time Updates

Subscribe to live data changes

File Storage

Upload and manage files

Common Issues

Authentication Error: Invalid API Key

Make sure your API key is correct and active. You can find it in your Cocobase dashboard.

CORS Error in Browser

Add your domain to the allowed origins in your Cocobase project settings.

TypeScript Types Not Working

Make sure you’re using TypeScript 4.5+ and have @types/node installed.

Need Help?

Join our Discord community
Check out code examples
Email us at hello@cocobase.cc

Getting Started

Core Concepts

Features

Cloud Functions

SDK Reference

Guides

API Reference

Getting Started

Getting Started with Cocobase

Prerequisites

Installation

Configuration

Your First Request

Reading Data

Environment Variables

Next Steps

Authentication

Query & Filtering

Real-time Updates

File Storage

Common Issues

Need Help?

Getting Started

Core Concepts

Features

Cloud Functions

SDK Reference

Guides

API Reference

Documentation Index

​Getting Started with Cocobase

​Prerequisites

​Installation

​Configuration

​Your First Request

​Reading Data

​Environment Variables

​Next Steps

Authentication

Query & Filtering

Real-time Updates

File Storage

​Common Issues

​Need Help?

Getting Started with Cocobase

Prerequisites

Installation

Configuration

Your First Request

Reading Data

Environment Variables

Next Steps

Common Issues

Need Help?