Data API

Overview

The Data API is direct REST access to Carbon's tables and views — the escape hatch beneath the Carbon API. Every table and view is an endpoint.

Reach for the Carbon API first. This surface is for the case it doesn't cover — when you know exactly what you're touching. Start by creating an API key.

You are outside the service layer

Nothing here validates, recalculates, or posts. A write goes straight to the table, so the values that depend on it — order totals, statuses, ledger entries — are not maintained for you. Use the Carbon API unless you know exactly what the table touches.

Tables & views

The API exposes both tables (read/write) and views (read-only, computed). Some resources appear twice — for example salesInvoice (a table) and salesInvoices (a view). These are not interchangeable.

Always read from the view

Tables like salesInvoice and purchaseInvoice have stored total and status columns that are set at creation and not updated when line items change. The corresponding views (salesInvoices, purchaseInvoices) compute totals, tax, balance, and status live from line items and settlements. If you read from the table, you will get stale data.

The rule is simple:

Operation

Use

List / retrieve

The view (plural, e.g. salesInvoices)

Create / update / delete

The table (singular, e.g. salesInvoice)

In the sidebar, views are marked with an eye icon and tables with a grid icon. Affected resource pages also show a banner linking to the correct counterpart.

Quickstart

The Data API is standard REST — call it from any language, or use supabase-js as shown here. Save your key and the API URL as environment variables:

.env

# .env
CARBON_DATA_API_URL=<your-host>
CARBON_DATA_API_KEY=<your-api-key>

Then initialize the client:

lib/carbon.ts

import { createClient } from '@supabase/supabase-js'

const apiUrl = process.env.CARBON_DATA_API_URL
const apiKey = process.env.CARBON_DATA_API_KEY

export const carbon = createClient(apiUrl, apiKey)

You can now query any resource with carbon.from('…'). Pick a resource from the sidebar for its endpoints and ready-to-copy samples — pointed at your configured instance.