Skip to content

Node.js Quick Start

Build an Express API powered by Centrali in 5 minutes. You'll create REST endpoints that use Centrali as your data layer.

Prerequisites

  • A Centrali account with a workspace (Account Setup)
  • Service account credentials (client ID and secret), added to the workspace_administrators or workspace_developers group so they may create a collection
  • Node.js 20+

Which credential?

This guide uses a service account, which only ever runs server-side. A publishable key cannot create a collection — the platform rejects every non-GET /collections request made with one.

1. Set Up the Project

mkdir my-centrali-api && cd my-centrali-api
npm init -y
npm install express @centrali-io/centrali-sdk dotenv

2. Set Up Environment Variables

Create a .env file:

CENTRALI_CLIENT_ID=sa_your_client_id
CENTRALI_CLIENT_SECRET=sk_your_client_secret
CENTRALI_WORKSPACE=your-workspace-slug
PORT=3000

Note

CENTRALI_WORKSPACE holds your workspace slug, not its display name. The create-centrali-app templates use this same variable name.

3. Create the Collection

A new workspace has no collections, so create the products collection this guide uses before querying it. Save as setup.mjs and run it once with node setup.mjs:

import 'dotenv/config';
import { CentraliSDK } from '@centrali-io/centrali-sdk';

const centrali = new CentraliSDK({
  baseUrl: 'https://centrali.io',
  workspaceId: process.env.CENTRALI_WORKSPACE,
  clientId: process.env.CENTRALI_CLIENT_ID,
  clientSecret: process.env.CENTRALI_CLIENT_SECRET
});

const existing = await centrali.collections.list();
if ((existing.data ?? []).some((c) => c.recordSlug === 'products')) {
  console.log('Collection "products" already exists');
} else {
  await centrali.collections.create({
    name: 'Products',
    recordSlug: 'products',
    properties: [
      { name: 'name', type: 'string', required: true },
      { name: 'price', type: 'number' },
      { name: 'inStock', type: 'boolean' }
    ],
    schemaDiscoveryMode: 'strict'
  });
  console.log('Created collection "products"');
}

If this returns 403

The credentials authenticated but are not permitted to create collections. Add the service account to the workspace_administrators or workspace_developers group. Obtaining a token does not by itself grant access to a resource.

4. Create the Server

Create index.js:

import 'dotenv/config';
import express from 'express';
import { CentraliSDK } from '@centrali-io/centrali-sdk';

const app = express();
app.use(express.json());

// Initialize Centrali SDK
const centrali = new CentraliSDK({
  // Use the root domain — the SDK derives api.centrali.io itself.
  baseUrl: 'https://centrali.io',
  workspaceId: process.env.CENTRALI_WORKSPACE, // current SDK option name; pass the workspace slug
  clientId: process.env.CENTRALI_CLIENT_ID,
  clientSecret: process.env.CENTRALI_CLIENT_SECRET
});

// List products
app.get('/products', async (req, res) => {
  const products = await centrali.records.list('products', {
    sort: '-createdAt',
    pageSize: 20
  });
  res.json(products);
});

// Get a single product
app.get('/products/:id', async (req, res) => {
  const product = await centrali.getRecord('products', req.params.id);
  if (!product) return res.status(404).json({ error: 'Not found' });
  res.json(product);
});

// Create a product
app.post('/products', async (req, res) => {
  const product = await centrali.createRecord('products', {
    name: req.body.name,
    price: req.body.price,
    inStock: true
  });
  res.status(201).json(product);
});

// Update a product
app.patch('/products/:id', async (req, res) => {
  const product = await centrali.updateRecord('products', req.params.id, req.body);
  res.json(product);
});

// Delete a product
app.delete('/products/:id', async (req, res) => {
  await centrali.deleteRecord('products', req.params.id);
  res.status(204).end();
});

// Search products
app.get('/search', async (req, res) => {
  const results = await centrali.records.search('products', String(req.query.q ?? ''), {
    page: { limit: 10 }
  });
  res.json(results);
});

app.listen(process.env.PORT, () => {
  console.log(`Server running on http://localhost:${process.env.PORT}`);
});

Add "type": "module" to your package.json for ES module support.

5. Run It

node index.js

6. Test the API

# Create a product
curl -X POST http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"name": "Wireless Headphones", "price": 99.99}'

# List products
curl http://localhost:3000/products

# Search
curl "http://localhost:3000/search?q=headphones"

What's Next?