Databox plugin

• The flow is data source, dataset, ingest. dataSources.create makes the container (only a name is required), datasets.create defines columns with schema and an optional primaryKey, and datasets.ingestData pushes records keyed by column ID, at most 500 rows per request. The response returns an ingestionId; poll it with datasets.getIngestion to see how many records were appended, overwritten or rejected. Databox does not document the ingestion status values, so this plugin does not declare a job; poll until the counts settle.
• A primary key changes re-ingestion. With primaryKey set, re-ingesting a matching record overwrites it instead of appending a duplicate. Without one, every ingest appends.
• Deleting a data source cascades. dataSources.delete permanently removes the data source, all of its datasets and all of their records, and cannot be undone.
• Metrics can trigger a sync. metrics.getData may wait for a due or first sync, up to about two minutes, so the plugin raises that call’s timeout; syncInfo.status says whether it synced, and inProgress or neverSynced mean call again shortly. It is rate limited to 30 calls per minute per account.
• Retry behavior. A 429 and a 409 modification_in_progress both carry Retry-After and are retried, because Databox did not process the request; a 409 modification_failed is final and is not. Failed writes are never replayed on a 5xx, since they may have been applied. idempotencyKey inputs (a UUID) send Databox’s Idempotency-Key header, which dedupes creation and ingestion calls for 24 hours.
• Accounts. Organizations with accounts enabled can pass accountId on an operation to act on one account instead of the organization tied to the key.

• 14 typed API operations

​

Setup

npm install corsair @corsair-dev/databox better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/databox better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/databox better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/databox better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { databox } from '@corsair-dev/databox';

export const corsair = createCorsair({
	plugins: [
		databox(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

databox()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'databox',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.databox.api.metrics.list({});

const tenant = corsair.withTenant('acme');
await tenant.databox.api.datasets.ingestData({
	id: 2345678,
	records: [{ transaction_id: 'T-10024', amount: 498, occurred_at: '2026-09-18T09:12:00+00:00' }, { transaction_id: 'T-10025', amount: 59, occurred_at: '2026-09-18T10:03:00+00:00' }],
});

​

What’s next