Introduction Beta Select developers only

Welcome to the Cerebro API documentation. Cerebro provides a universal commerce API that lets you integrate bookings, products, and services into your application. Access thousands of verified businesses through a single integration.

Quick Start

Get started with Cerebro in three simple steps:

1. Install the SDK

Install the Cerebro SDK using your preferred package manager:

# npm
npm install @cerebro/sdk

# pip
pip install cerebro

# gem
gem install cerebro

2. Initialize the client

Create a new Cerebro client with your API key:

import Cerebro from '@cerebro/sdk';

const cerebro = new Cerebro({
  apiKey: process.env.CEREBRO_KEY
});

3. Make your first request

Search for available inventory and create a booking:

// Search for inventory
const results = await cerebro.search({
  category: 'restaurant',
  location: 'Santo Domingo',
  date: '2025-10-15T20:00:00Z'
});

// Create a booking with error handling
try {
  const booking = await cerebro.bookings.create({
    businessId: results[0].id,
    inventoryId: 'vip-table-8',
    date: '2025-10-15T20:00:00Z',
    partySize: 4,
    customerId: 'user_123'
  });

  console.log('Booking confirmed:', booking.confirmationCode);

} catch (error) {
  if (error.code === 'inventory_unavailable') {
    // Show alternative options to user
    const alternatives = await cerebro.search({ /* ... */ });
  } else if (error.code === 'payment_failed') {
    // Handle payment error
    console.error('Payment failed:', error.message);
  }
}

Real-World Use Cases

See how developers are using Cerebro to build commerce into their applications:

Dating App Integration

Automatically suggest date spots based on match preferences and location:

const matches = await getMatches(userId);

// Find restaurants that match their preferences
const restaurants = await cerebro.search({
  category: 'restaurant',
  location: matches[0].city,
  cuisine: matches[0].preferences.food,
  priceRange: '$',
  date: 'tonight'
});

// Show suggestions: "We found 12 Italian spots you both might love"
displayDateSuggestions(restaurants);

Spotify Context-Aware Bookings

Book venues based on what users are currently listening to:

const nowPlaying = await spotify.getCurrentTrack();

if (nowPlaying.genre === 'bachata') {
  const clubs = await cerebro.search({
    category: 'nightclub',
    location: user.city,
    musicType: 'bachata',
    date: 'tonight',
    availability: 'tables'
  });

  // "Loving bachata? 5 clubs playing it tonight 🎵"
  showInAppNotification(clubs);
}

Fitness App Post-Workout Services

Offer recovery services immediately after workouts:

const workoutComplete = true;

const recovery = await cerebro.search({
  category: 'services',
  type: ['massage', 'physical-therapy', 'cryotherapy'],
  location: user.city,
  availability: 'today',
  distance: '5km'
});

// "Great workout! Book a massage nearby?"
offerRecoveryBooking(recovery);

Authentication

All API requests require authentication using Bearer tokens. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Testing & Sandbox

Use test API keys to develop and test your integration without processing real transactions or affecting live data.

Sandbox Environment

Initialize the SDK with a test API key to use the sandbox environment:

const cerebro = new Cerebro({
  apiKey: 'test_sk_123456',
  environment: 'sandbox'
});

Test Mode Features

• Fake businesses with predictable, consistent data
• Simulated booking confirmations and cancellations
• Webhook testing tools with request logs
• No real charges or payment processing
• Unlimited API requests for testing

Test Data

The sandbox includes pre-populated test businesses you can use immediately:

// Search returns consistent test data
const businesses = await cerebro.search({
  location: 'test_city',
  category: 'restaurant'
});

// Returns: Test Restaurant 1, Test Restaurant 2, etc.

Rate Limits

API rate limits are designed to ensure fair usage and platform stability. Limits are applied per API key.

Request Limits

• Standard Tier: 1,000 requests per minute
• Professional Tier: 5,000 requests per minute
• Enterprise Tier: 10,000 requests per minute

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1634567890

Best Practices

• Use webhooks instead of polling for real-time updates
• Implement exponential backoff for retry logic
• Cache frequently accessed data on your side
• Monitor the X-RateLimit-Remaining header

Inventory Model

Cerebro aggregates inventory from thousands of businesses into a unified API. Your application can search and display available products, services, and bookings from any business on the platform—all through a single endpoint.

What You Can Access

• Products - Physical goods from e-commerce businesses
• Services - Appointments from salons, fitness, professionals
• Tables - Restaurant reservations at local venues
• Tickets - Event access, concerts, shows
• Rooms - Hotel and accommodation bookings

Bookings

When a user in your application books something, Cerebro handles the transaction, payment processing, and confirmation. You receive webhooks for all booking events so your app stays in sync.

Booking States

• pending - Booking requested but not confirmed
• confirmed - Booking confirmed and payment captured
• completed - Service rendered or product delivered
• cancelled - Booking cancelled by customer or business

Real-time Sync

Cerebro sends webhooks to your application whenever bookings are created, updated, or cancelled. This keeps your app in sync with real-time changes without polling.

// Configure webhook endpoint
const webhook = await cerebro.webhooks.create({
  url: 'https://your-app.com/webhooks',
  events: ['booking.created', 'booking.updated']
});

Businesses API

Search and retrieve business information. Access details about restaurants, hotels, services, and more on the Cerebro platform.

List Businesses

GET /v1/businesses?location=Santo%20Domingo&type=restaurant

// Response
{
  "businesses": [
    {
      "id": "bus_123",
      "name": "Restaurant XYZ",
      "type": "restaurant",
      "location": "Santo Domingo"
    }
  ]
}

Inventory API

Search available inventory from any business on the platform. Filter by category, location, date, and price to find exactly what your users need.

Search Inventory

GET /v1/inventory/search?category=restaurant&location=Santo%20Domingo

// Response
{
  "results": [
    {
      "id": "inv_456",
      "businessId": "bus_123",
      "name": "VIP Table",
      "capacity": 8,
      "price": 500.00
    }
  ]
}

Bookings API

Create bookings on behalf of your users. When your app creates a booking, Cerebro handles payment processing, confirmation, and notifications to both the user and the business.

Create a Booking

POST /v1/bookings

{
  "businessId": "bus_123",
  "inventoryId": "inv_456",
  "date": "2025-10-15T20:00:00Z",
  "partySize": 4,
  "customerId": "user_789"
}

Payments API

Cerebro handles all payment processing automatically. Your application doesn't need to touch payment details—we handle PCI compliance, fraud detection, and payouts.

How It Works

1. User books through your app
2. Cerebro processes payment securely
3. Business receives payout (minus commission)
4. You receive your revenue share automatically

JavaScript SDK

The official JavaScript/TypeScript SDK for Node.js and browser environments. Type-safe, fully documented, and production-ready.

npm install @cerebro/sdk

Python SDK

The official Python SDK with async/await support. Perfect for Django, Flask, FastAPI, and any Python web framework.

pip install cerebro

Ruby SDK

The official Ruby SDK designed for Rails and Sinatra applications. Idiomatic Ruby with full ActiveRecord integration.

gem install cerebro