Package Exports

quickbase-js

Readme

QuickBase JS SDK v2

A TypeScript/JavaScript client for the QuickBase JSON RESTful API.

Features

Typed API Methods - Full TypeScript support with auto-generated types from OpenAPI spec
Multiple Auth Methods - User token, temporary token, SSO, and ticket authentication
Schema Aliases - Use readable names for tables and fields instead of IDs
Fluent Pagination - Chain .all(), .paginate(), or .noPaginate() on paginated endpoints
Date Conversion - Automatic conversion of ISO date strings to JavaScript Date objects
Rate Limit Handling - Automatic retry with exponential backoff on 429 errors
Proactive Throttling - Optional client-side request throttling
Tree-Shakeable - Static method generation for optimal bundle size
XML API Support - Access legacy XML-only endpoints (roles, groups, DBVars, code pages, etc.)
Read-Only Mode - Defense-in-depth protection against accidental writes

API Reference

The SDK provides typed methods for all 59 QuickBase API endpoints including Apps, Tables, Fields, Records, Reports, Users, and more. Each method includes JSDoc documentation with links to the official QuickBase API docs.

Installation

npm / Node.js

npm install quickbase-js

Browser / CDN (QuickBase Code Pages)

For QuickBase Code Pages, use temp-token authentication which automatically leverages the user's browser session:

<script src="https://cdn.jsdelivr.net/npm/quickbase-js@2/dist/quickbase.min.js"></script>
<script>
  // Realm can be auto-detected from the current URL
  const realm = window.location.hostname.split('.')[0];

  const qb = QuickBase.createClient({
    realm: realm,
    auth: { type: 'temp-token' },
  });

  qb.getApp({ appId: 'bpqe82s1' }).then(app => {
    console.log(app.name);
  });
</script>

Or with ES modules:

<script type="module">
  import { createClient } from 'https://cdn.jsdelivr.net/npm/quickbase-js@2/dist/quickbase.esm.js';

  const qb = createClient({
    realm: 'mycompany',
    auth: { type: 'temp-token' },
  });

  const app = await qb.getApp({ appId: 'bpqe82s1' });
  console.log(app.name);
</script>

Quick Start

import { createClient } from 'quickbase-js';

const qb = createClient({
  realm: 'mycompany',
  auth: {
    type: 'user-token',
    userToken: 'your-user-token',
  },
});

// Use typed API methods
const app = await qb.getApp({ appId: 'bpqe82s1' });
console.log(app.name);

// Query records
const records = await qb.runQuery({
  from: 'bpqe82s1',
  select: [3, 6, 7],
  where: "{6.EX.'Active'}",
});
console.log(records.data);

Authentication

User Token (Recommended for Server-Side)

const qb = createClient({
  realm: 'mycompany',
  auth: {
    type: 'user-token',
    userToken: 'your-user-token',
  },
});

Temporary Token (Recommended for Browser/Code Pages)

Temporary tokens are automatically fetched and cached per database. Tokens are refreshed proactively before expiration (default: 4m 50s TTL for 5-minute tokens). The SDK also handles unexpected 401 errors as a fallback.

// In QuickBase Code Pages - uses browser session for authentication
const qb = createClient({
  realm: 'mycompany',
  auth: {
    type: 'temp-token',
  },
});

Auto dbid extraction: The SDK automatically extracts the database ID for temp token authentication from your request parameters:

body.from (runQuery, deleteRecords)
body.to (upsert)
query.tableId (getFields, etc.)
query.appId (getAppTables, etc.)
Path segments /tables/{tableId} and /apps/{appId}

This means you don't need to manually specify the dbid - just make API calls and the SDK handles token management automatically.

SSO Token

const qb = createClient({
  realm: 'mycompany',
  auth: {
    type: 'sso',
    samlToken: 'your-saml-token',
  },
});

Ticket Auth (Username/Password)

Ticket authentication lets users log in with their QuickBase email and password. Unlike user tokens, tickets properly attribute record changes (createdBy/modifiedBy) to the authenticated user. Credentials should come from user input (e.g., a login form), not hardcoded.

// Create client after user submits login form
function handleLogin(formData: { username: string; password: string }) {
  const qb = createClient({
    realm: 'mycompany',
    auth: {
      type: 'ticket',
      username: formData.username,
      password: formData.password,
      hours: 24,                      // Optional: validity (default: 12h, max: ~6 months)
      persist: 'sessionStorage',      // Optional: survive page refresh
      onExpired: () => {              // Optional: called when ticket expires
        window.location.href = '/login';
      },
    },
  });
  return qb;
}

Key behaviors:

Authentication happens lazily on the first API call
Password is discarded from memory immediately after authentication
Use persist to survive page refreshes ('sessionStorage' or 'localStorage')
Use onExpired to handle session expiration (e.g., redirect to login)

Pagination

Paginated endpoints (runQuery, runReport, getUsers, etc.) return a PaginatedRequest that supports fluent pagination methods.

Default Behavior (Single Page)

// Returns first page only
const page = await qb.runQuery({ from: 'tableId' });
console.log(page.data.length); // e.g., 100 records
console.log(page.metadata.totalRecords); // e.g., 5000 total

Fetch All Pages

// Automatically fetches all pages and combines results
const all = await qb.runQuery({ from: 'tableId' }).all();
console.log(all.data.length); // 5000 records

Fetch with Record Limit

// Fetch up to 500 records (may span multiple pages)
const limited = await qb.runQuery({ from: 'tableId' }).paginate({ limit: 500 });
console.log(limited.data.length); // 500 records

Explicit Single Page

// Explicitly fetch single page (useful when autoPaginate is enabled globally)
const single = await qb.runQuery({ from: 'tableId' }).noPaginate();

Global Auto-Pagination

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  autoPaginate: true, // Default await now fetches all pages
});

// Now direct await fetches all pages
const all = await qb.runQuery({ from: 'tableId' });

// Use .noPaginate() to get single page
const page = await qb.runQuery({ from: 'tableId' }).noPaginate();

Date Conversion

By default, ISO 8601 date strings in API responses are automatically converted to JavaScript Date objects:

const app = await qb.getApp({ appId: 'bpqe82s1' });

// Date fields are now Date objects
console.log(app.created instanceof Date); // true
console.log(app.created.toISOString());   // "2024-01-15T10:30:00.000Z"

// Works with nested objects and arrays
const records = await qb.runQuery({ from: 'tableId' });
records.data.forEach(record => {
  // Date field values are converted
  console.log(record['7'].value instanceof Date); // true for date/timestamp fields
});

To disable date conversion and keep dates as strings:

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  convertDates: false, // Keep dates as ISO strings
});

Schema Aliases

Use readable names for tables and fields instead of cryptic IDs. The SDK transforms aliases to IDs in requests and IDs back to aliases in responses.

Defining a Schema

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  schema: {
    tables: {
      projects: {
        id: 'bqw3ryzab',
        fields: {
          id: 3,
          name: 6,
          status: 7,
          dueDate: 12,
          assignee: 15,
        },
      },
      tasks: {
        id: 'bqw4xyzcd',
        fields: {
          id: 3,
          title: 6,
          projectId: 8,
          completed: 10,
        },
      },
    },
  },
});

Using Aliases in Queries

// Use table and field aliases instead of IDs
const result = await qb.runQuery({
  from: 'projects',                          // Instead of 'bqw3ryzab'
  select: ['name', 'status', 'dueDate'],     // Instead of [6, 7, 12]
  where: "{'status'.EX.'Active'}",           // Field aliases in where clauses
  sortBy: [{ fieldId: 'dueDate', order: 'ASC' }],
});

// Response uses aliases and values are automatically unwrapped
console.log(result.data[0].name);     // "Project Alpha" (not { value: "Project Alpha" })
console.log(result.data[0].status);   // "Active"
console.log(result.data[0].dueDate);  // Date object (if convertDates is enabled)

Upserting with Aliases

With schema, use field aliases as keys:

await qb.upsert({
  to: 'projects',
  data: [
    { name: 'New Project', status: 'Planning' },
  ],
});

Auto-Wrapping

Values are automatically wrapped in { value: X } format for upserts. This works with or without a schema:

// Clean syntax - values are auto-wrapped
{ '6': 'New Record', '7': 42 }

// Explicit wrapping also works (backwards compatible)
{ '6': { value: 'New Record' }, '7': { value: 42 } }

Response Transformation

Responses are automatically transformed:

Field ID keys ('6') become aliases (name)
Values are unwrapped from { value: X } to just X
Unknown fields (not in schema) keep their numeric key but are still unwrapped

// Raw API response:
{ data: [{ '6': { value: 'Alpha' }, '99': { value: 'Custom' } }] }

// Transformed response (with schema):
{ data: [{ name: 'Alpha', '99': 'Custom' }] }

Helpful Error Messages

Typos in aliases throw errors with suggestions:

// Throws: Unknown field alias 'stauts' in table 'projects'. Did you mean 'status'?
await qb.runQuery({
  from: 'projects',
  select: ['stauts'],  // Typo!
});

Generating Schema from QuickBase

Use the CLI to generate a schema from an existing app:

# Generate TypeScript schema file
npx quickbase-js schema -r "$QB_REALM" -a "$QB_APP_ID" -t "$QB_USER_TOKEN" -o schema.ts

# Generate JSON format
npx quickbase-js schema -r "$QB_REALM" -a "$QB_APP_ID" -t "$QB_USER_TOKEN" -f json -o schema.json

# Output to stdout
npx quickbase-js schema -r "$QB_REALM" -a "$QB_APP_ID" -t "$QB_USER_TOKEN"

The generator creates aliases from field labels using camelCase (e.g., "Due Date" → dueDate).

Updating Schema with --merge

When your QuickBase app changes (new tables, new fields), use --merge to update your schema while preserving any custom aliases you've set:

# Update schema, preserving custom aliases
npx quickbase-js schema -r "$QB_REALM" -a "$QB_APP_ID" -t "$QB_USER_TOKEN" -o schema.ts --merge

What merge does:

Preserves your custom table and field aliases (matched by ID, not name)
Adds new tables and fields with auto-generated aliases
Reports what changed:

Merge complete:
  Tables: 2 preserved, 1 added, 0 removed
  Fields: 15 preserved, 3 added, 0 removed

This lets you rename auto-generated aliases like dateCreated to created and keep them through updates.

Using a Separate Schema File

You can define your schema in a separate file and import it:

schema.ts

import type { Schema } from 'quickbase-js';

export const schema: Schema = {
  tables: {
    projects: {
      id: 'bqw3ryzab',
      fields: {
        id: 3,
        name: 6,
        status: 7,
        dueDate: 12,
      },
    },
  },
};

client.ts

import { createClient } from 'quickbase-js';
import { schema } from './schema.js';

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  schema,
});

Or use a JSON file:

schema.json

{
  "tables": {
    "projects": {
      "id": "bqw3ryzab",
      "fields": { "id": 3, "name": 6, "status": 7 }
    }
  }
}

import { createClient } from 'quickbase-js';
import schema from './schema.json' assert { type: 'json' };

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  schema,
});

Configuration Options

const qb = createClient({
  // Required
  realm: 'mycompany',
  auth: { /* see authentication section */ },

  // Optional
  debug: false,                              // Enable debug logging
  timeout: 30000,                            // Request timeout in ms
  baseUrl: 'https://api.quickbase.com/v1',   // API base URL
  autoPaginate: false,                       // Auto-paginate on direct await
  convertDates: true,                        // Convert ISO date strings to Date objects
  readOnly: false,                           // Block all write operations
  schema: { /* see schema aliases section */ }, // Table and field aliases

  // Rate limiting
  rateLimit: {
    // Optional client-side throttling
    // QuickBase allows 100 requests per 10 seconds per user token
    proactiveThrottle: {
      enabled: false,
      requestsPer10Seconds: 100,
    },

    // Retry configuration for 429 and 5xx errors
    retry: {
      maxAttempts: 3,
      initialDelayMs: 1000,
      maxDelayMs: 30000,
      multiplier: 2,
    },

    // Callback when rate limited
    onRateLimit: (info) => {
      console.log(`Rate limited! Retry after ${info.retryAfter}s`);
      console.log(`Request: ${info.requestUrl}`);
      console.log(`Ray ID: ${info.qbApiRay}`);
    },
  },
});

XML API (Legacy Endpoints)

The XML API provides access to endpoints not available in the JSON API, including role management, group management, app variables, code pages, and more.

Note: The XML API is a legacy API that may be discontinued by QuickBase in the future. Use the JSON API when possible.

Quick Start

import { createClient, createXmlClient } from 'quickbase-js';

// Create main client
const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'your-token' },
});

// Create XML client from main client
const xml = createXmlClient(qb);

// Get all roles in an app
const roles = await xml.getRoleInfo(appId);
for (const role of roles.roles) {
  console.log(`${role.name}: ${role.access.description}`);
}

// Get all users and their role assignments
const users = await xml.userRoles(appId);
for (const user of users.users) {
  console.log(`${user.name}: ${user.roles.map(r => r.name).join(', ')}`);
}

// Get comprehensive schema (fields, reports, variables)
const schema = await xml.getSchema(tableId);
for (const field of schema.table.fields ?? []) {
  console.log(`Field ${field.id}: ${field.label} (${field.fieldType})`);
}

Application Tokens

Application tokens are an additional security layer for QuickBase apps. If an app has "Require Application Tokens" enabled, XML API calls must include a valid app token.

Important: User tokens bypass app token checks entirely. You only need app tokens when:

Using ticket auth (type: 'ticket') with the XML API
Using temp tokens (type: 'temp-token') with the XML API
The target app has "Require Application Tokens" enabled

The JSON API does not use app tokens.

// Set app token at client level
const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'ticket', username: 'user@example.com', password: 'pass' },
  appToken: 'your-app-token',  // Used by XML API only
});

const xml = createXmlClient(qb);
const roles = await xml.getRoleInfo(appId);  // Includes app token

// Or set it on the XML client directly
const xmlWithToken = createXmlClient(qb, { appToken: 'your-app-token' });

Available Methods

App Discovery:

Method	XML Action	Description
`grantedDBs(opts?)`	API_GrantedDBs	List all apps/tables user can access
`findDBByName(name, parentsOnly?)`	API_FindDBByName	Find an app by name
`getDBInfo(dbid)`	API_GetDBInfo	Get app/table metadata (record count, manager, timestamps)
`getNumRecords(tableId)`	API_GetNumRecords	Get total record count for a table

Role Management:

Method	XML Action	Description
`getRoleInfo(appId)`	API_GetRoleInfo	Get all roles defined in an application
`userRoles(appId)`	API_UserRoles	Get all users and their role assignments
`getUserRole(appId, userId, includeGroups?)`	API_GetUserRole	Get roles for a specific user
`addUserToRole(appId, userId, roleId)`	API_AddUserToRole	Assign a user to a role
`removeUserFromRole(appId, userId, roleId)`	API_RemoveUserFromRole	Remove a user from a role
`changeUserRole(appId, userId, currentRole, newRole)`	API_ChangeUserRole	Change a user's role

User Management:

Method	XML Action	Description
`getUserInfo(email)`	API_GetUserInfo	Get user info by email address
`provisionUser(appId, email, opts?)`	API_ProvisionUser	Create a new unregistered user
`sendInvitation(appId, userId, userText?)`	API_SendInvitation	Send invitation email to a user
`changeManager(appId, newManagerEmail)`	API_ChangeManager	Change the app manager
`changeRecordOwner(tableId, recordId, newOwner)`	API_ChangeRecordOwner	Change record owner

Group Management:

Method	XML Action	Description
`createGroup(name, opts?)`	API_CreateGroup	Create a new group
`deleteGroup(groupId)`	API_DeleteGroup	Delete a group
`copyGroup(groupId, name, opts?)`	API_CopyGroup	Copy a group
`changeGroupInfo(groupId, opts)`	API_ChangeGroupInfo	Update group name/description
`getUsersInGroup(groupId, includeManagers?)`	API_GetUsersInGroup	Get users and managers in a group
`addUserToGroup(groupId, userId, allowAdmin?)`	API_AddUserToGroup	Add a user to a group
`removeUserFromGroup(groupId, userId)`	API_RemoveUserFromGroup	Remove a user from a group
`getGroupRole(appId, groupId)`	API_GetGroupRole	Get roles assigned to a group
`addGroupToRole(appId, groupId, roleId)`	API_AddGroupToRole	Assign a group to a role
`removeGroupFromRole(appId, groupId, roleId, allRoles?)`	API_RemoveGroupFromRole	Remove a group from a role
`grantedGroups(userId?, adminOnly?)`	API_GrantedGroups	Get groups a user belongs to
`grantedDBsForGroup(groupId)`	API_GrantedDBsForGroup	Get apps a group can access

App Metadata:

Method	XML Action	Description
`getAppDTMInfo(appId)`	API_GetAppDTMInfo	Get modification timestamps
`getAncestorInfo(appId)`	API_GetAncestorInfo	Get app copy/template lineage info

Application Variables:

Method	XML Action	Description
`getDBVar(appId, varName)`	API_GetDBVar	Get an application variable value
`setDBVar(appId, varName, value)`	API_SetDBVar	Set an application variable value

Code Pages:

Method	XML Action	Description
`getDBPage(appId, pageIdOrName)`	API_GetDBPage	Get stored code page content
`addReplaceDBPage(appId, opts)`	API_AddReplaceDBPage	Create or update a code page

Field Management:

Method	XML Action	Description
`fieldAddChoices(tableId, fieldId, choices)`	API_FieldAddChoices	Add choices to a multiple-choice field
`fieldRemoveChoices(tableId, fieldId, choices)`	API_FieldRemoveChoices	Remove choices from a field
`setKeyField(tableId, fieldId)`	API_SetKeyField	Set the key field for a table

Schema Information:

Method	XML Action	Description
`getSchema(dbid)`	API_GetSchema	Get comprehensive app/table metadata

Record Information:

Method	XML Action	Description
`doQueryCount(tableId, query?)`	API_DoQueryCount	Get count of matching records (no data fetch)
`getRecordInfo(tableId, recordId)`	API_GetRecordInfo	Get record with field metadata
`getRecordInfoByKey(tableId, keyValue)`	API_GetRecordInfo	Get record by key field value

Record Operations:

Method	XML Action	Description
`copyMasterDetail(tableId, opts)`	API_CopyMasterDetail	Copy a master record with its detail records
`importFromCSV(tableId, opts)`	API_ImportFromCSV	Bulk import/update records from CSV data
`runImport(tableId, importId)`	API_RunImport	Execute a saved import definition

Webhooks:

Method	XML Action	Description
`webhooksCreate(tableId, opts)`	API_Webhooks_Create	Create a webhook
`webhooksEdit(tableId, webhookId, opts)`	API_Webhooks_Edit	Edit a webhook
`webhooksDelete(tableId, webhookId)`	API_Webhooks_Delete	Delete a webhook
`webhooksActivate(tableId, webhookId)`	API_Webhooks_Activate	Activate a webhook
`webhooksDeactivate(tableId, webhookId)`	API_Webhooks_Deactivate	Deactivate a webhook
`webhooksCopy(tableId, webhookId, name?)`	API_Webhooks_Copy	Copy a webhook

HTML Generation:

Method	XML Action	Description
`genAddRecordForm(tableId, fields?)`	API_GenAddRecordForm	Generate HTML form for adding a record
`genResultsTable(tableId, opts?)`	API_GenResultsTable	Generate HTML/JS/CSV table of query results
`getRecordAsHTML(tableId, opts)`	API_GetRecordAsHTML	Get a record rendered as HTML

Authentication:

Method	XML Action	Description
`signOut()`	API_SignOut	Clear ticket cookie (browser-focused)

Error Handling

XML API errors are returned as XmlError:

import { XmlError, isUnauthorized, isNotFound, isInvalidTicket } from 'quickbase-js';

try {
  const roles = await xml.getRoleInfo(appId);
} catch (error) {
  if (error instanceof XmlError) {
    console.log(`XML API error ${error.code}: ${error.text}`);

    // Use helper functions for common error types
    if (isUnauthorized(error)) {
      console.log('Not authorized');
    } else if (isNotFound(error)) {
      console.log('Resource not found');
    } else if (isInvalidTicket(error)) {
      console.log('Invalid or expired ticket');
    }
  }
}

Read-Only Mode

The XML client inherits read-only mode from the main client (see Read-Only Mode):

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  readOnly: true,
});

const xml = createXmlClient(qb); // Inherits readOnly: true

// Read operations work
const roles = await xml.getRoleInfo(appId);

// Write operations throw ReadOnlyError
await xml.addUserToRole(appId, userId, roleId); // Throws!

You can also override read-only mode for just the XML client:

const xml = createXmlClient(qb, { readOnly: true });

Schema Aliases

The XML client inherits the schema from the main client and supports table and field aliases:

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  schema: {
    tables: {
      projects: {
        id: 'bqprojects123',
        fields: {
          id: 3,
          name: 6,
          status: 7,
        },
      },
    },
  },
});

const xml = createXmlClient(qb);

// Use table aliases
const count = await xml.getNumRecords('projects');  // Resolves to 'bqprojects123'
const roles = await xml.getRoleInfo('projects');

// Use field aliases
await xml.fieldAddChoices('projects', 'status', ['Active', 'Inactive']);
await xml.setKeyField('projects', 'name');

// Field aliases in importFromCSV
await xml.importFromCSV('projects', {
  recordsCsv: 'Project A,Active',
  clist: ['name', 'status'],
  mergeFieldId: 'id',
});

Response Transformation:

The XML client transforms responses to use field and table aliases as keys when a schema is configured, similar to the JSON API:

// getRecordInfo - access fields by alias
const record = await xml.getRecordInfo('projects', 123);
console.log(record.fields.name.value);    // "Project Alpha"
console.log(record.fields.status.value);  // "Active"

// Without schema, fields are keyed by ID
const record2 = await xmlNoSchema.getRecordInfo('bqprojects123', 123);
console.log(record2.fields['6'].value);   // "Project Alpha"

// getSchema - access fields by alias
const schema = await xml.getSchema('projects');
console.log(schema.table.fields?.name.label);    // "Project Name"
console.log(schema.table.fields?.status.label);  // "Status"
console.log(schema.table.childTables?.tasks.dbid);  // "bqtasks123"

// grantedDBs - access databases by alias
const dbs = await xml.grantedDBs();
console.log(dbs.databases.projects.dbname);  // "My Projects App"
console.log(dbs.databases.tasks.dbname);     // "Tasks Table"

// Unknown tables/fields are keyed by their ID
console.log(dbs.databases['bqunknown123'].dbname);  // "Unknown Table"

// getAppDTMInfo - access tables by alias
const dtm = await xml.getAppDTMInfo('projects');
console.log(dtm.appAlias);                           // "projects"
console.log(dtm.tables.projects.lastModifiedTime);   // "1234567890"
console.log(dtm.tables.tasks.lastModifiedTime);      // "1234567891"

Responses transformed to keyed objects:

Method	Keyed Properties
`getRecordInfo` / `getRecordInfoByKey`	`fields.{alias}`
`getSchema`	`table.fields.{alias}`, `table.childTables.{alias}`
`grantedDBs` / `grantedDBsForGroup`	`databases.{alias}`
`getAppDTMInfo`	`tables.{alias}`
`fieldAddChoices` / `fieldRemoveChoices`	`fieldAlias` property
`findDBByName`	`alias` property

API Methods

All QuickBase API endpoints are available as typed methods:

// Apps
const app = await qb.getApp({ appId: 'bpqe82s1' });
const newApp = await qb.createApp({ name: 'My App', description: 'Test' });
await qb.updateApp({ appId: 'bpqe82s1' }, { name: 'Updated Name' });
await qb.deleteApp({ appId: 'bpqe82s1' }, { name: 'My App' });

// Tables
const tables = await qb.getAppTables({ appId: 'bpqe82s1' });
const table = await qb.getTable({ appId: 'bpqe82s1', tableId: 'byyy82s1' });

// Fields
const fields = await qb.getFields({ tableId: 'byyy82s1' });

// Records
const records = await qb.runQuery({
  from: 'byyy82s1',
  select: [3, 6, 7],
  where: "{6.GT.100}",
  sortBy: [{ fieldId: 3, order: 'ASC' }],
  options: { top: 100, skip: 0 },
});

// Insert/Update records (values are auto-wrapped)
const result = await qb.upsert({
  to: 'byyy82s1',
  data: [
    { '6': 'New Record', '7': 42 },
  ],
});

// Delete records
await qb.deleteRecords({
  from: 'byyy82s1',
  where: "{3.EX.123}",
});

// Reports
const report = await qb.runReport(
  { reportId: 'abc123', tableId: 'byyy82s1' },
  { skip: 0, top: 100 }
);

// Users
const users = await qb.getUsers(
  { accountId: '123456' },
  { appIds: ['bpqe82s1'] }
);

Raw Request

For endpoints not covered by typed methods, use the generic request method:

const result = await qb.request<MyResponseType>({
  method: 'POST',
  path: '/some/endpoint',
  body: { key: 'value' },
  query: { param: 'value' },
});

Read-Only Mode

Enable read-only mode to prevent accidental writes during development, testing, or when building read-only dashboards. This feature uses defense-in-depth with two layers of protection.

import { createClient, createXmlClient, ReadOnlyError } from 'quickbase-js';

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  readOnly: true,
});

// Read operations work normally
const app = await qb.getApp({ appId: 'bpqe82s1' });
const records = await qb.runQuery({ from: 'byyy82s1' });

// Write operations throw ReadOnlyError
try {
  await qb.upsert({ to: 'byyy82s1', data: [{ '6': 'test' }] });
} catch (error) {
  if (error instanceof ReadOnlyError) {
    console.log(`Blocked: ${error.method} ${error.path}`);
    // "Blocked: POST /records"
  }
}

What Gets Blocked

Operation Type	Examples	Blocked?
GET requests	getApp, getFields, getTables	✅ Allowed
Query POSTs	runQuery, runReport, getUsers	✅ Allowed
Create/Update	upsert, createApp, createTable	❌ Blocked
Delete	deleteRecords, deleteApp	❌ Blocked
XML writes	addUserToRole, setDBVar	❌ Blocked

Defense-in-Depth

The read-only check uses two layers:

Explicit blocklist - Known write endpoints are blocked by path matching
HTTP method check - Any POST/PUT/DELETE/PATCH not in the allowlist is blocked

This ensures new API endpoints are blocked by default until explicitly allowlisted.

XML API

The XML client automatically inherits read-only mode from the main client:

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  readOnly: true,
});

const xml = createXmlClient(qb); // Inherits readOnly: true

// Read operations work
const roles = await xml.getRoleInfo(appId);

// Write operations throw ReadOnlyError with action info
try {
  await xml.setDBVar(appId, 'myVar', 'value');
} catch (error) {
  if (error instanceof ReadOnlyError) {
    console.log(`Blocked XML action: ${error.action}`);
    // "Blocked XML action: API_SetDBVar"
  }
}

ReadOnlyError

The ReadOnlyError class provides details about the blocked operation:

import { ReadOnlyError } from 'quickbase-js';

try {
  await qb.deleteRecords({ from: 'byyy82s1', where: '{3.GT.0}' });
} catch (error) {
  if (error instanceof ReadOnlyError) {
    error.method;  // "DELETE"
    error.path;    // "/records"
    error.action;  // undefined (only set for XML API)
    error.message; // "Read-only mode: write operation blocked (DELETE /records)"
  }
}

Error Handling

import {
  QuickbaseError,
  RateLimitError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ValidationError,
  ServerError,
  ReadOnlyError,
} from 'quickbase-js';

try {
  await qb.getApp({ appId: 'invalid' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
    console.log(`Ray ID: ${error.rayId}`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid or expired token');
  } else if (error instanceof AuthorizationError) {
    console.log('Permission denied');
  } else if (error instanceof NotFoundError) {
    console.log('Resource not found');
  } else if (error instanceof ValidationError) {
    console.log('Bad request:', error.message);
  } else if (error instanceof ServerError) {
    console.log('Server error:', error.statusCode);
  } else if (error instanceof QuickbaseError) {
    console.log(`API error ${error.statusCode}: ${error.message}`);
  }
}

Rate Limiting

QuickBase enforces a rate limit of 100 requests per 10 seconds per user token. This SDK follows QuickBase's official rate limiting guidance — relying on server-side Retry-After headers by default, with optional client-side throttling.

How 429 Errors Are Handled

When the SDK receives a 429 (Too Many Requests) response, it automatically:

Extracts rate limit info from response headers (Retry-After, cf-ray, qb-api-ray)
Calls the onRateLimit callback if configured, allowing you to log or monitor
Waits before retrying - uses the Retry-After header if present, otherwise exponential backoff with jitter
Retries the request up to maxAttempts times (default: 3)
Throws a RateLimitError if all retries are exhausted

Request fails with 429
        ↓
Extract Retry-After header
        ↓
Call onRateLimit callback (if set)
        ↓
Wait (Retry-After or exponential backoff)
        ↓
Retry request (up to maxAttempts)
        ↓
Throw RateLimitError if exhausted

Retry Configuration

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  rateLimit: {
    retry: {
      maxAttempts: 5,        // Default: 3
      initialDelayMs: 1000,  // Default: 1000ms
      maxDelayMs: 30000,     // Default: 30000ms
      multiplier: 2,         // Default: 2
    },
  },
});

The backoff formula with jitter: delay = initialDelayMs * (multiplier ^ attempt) ± 10%

Proactive Throttling

Prevent 429 errors entirely by throttling requests client-side using a sliding window algorithm:

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  rateLimit: {
    proactiveThrottle: {
      enabled: true,
      requestsPer10Seconds: 100,
    },
  },
});

This tracks request timestamps and blocks new requests when the limit would be exceeded, waiting until the oldest request exits the 10-second window.

Rate Limit Callback

Get notified when rate limited (called before retry):

const qb = createClient({
  realm: 'mycompany',
  auth: { type: 'user-token', userToken: 'token' },
  rateLimit: {
    onRateLimit: (info) => {
      console.log(`Rate limited on ${info.requestUrl}`);
      console.log(`Retry after: ${info.retryAfter} seconds`);
      console.log(`Ray ID: ${info.qbApiRay}`);
      console.log(`Attempt: ${info.attempt}`);
    },
  },
});

Handling RateLimitError

If retries are exhausted, a RateLimitError is thrown:

import { RateLimitError } from 'quickbase-js';

try {
  await qb.getApp({ appId: 'bpqe82s1' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited after ${error.rateLimitInfo.attempt} attempts`);
    console.log(`Retry after: ${error.retryAfter} seconds`);
  }
}

Migration from v1

Authentication

// v1 - user token
const qb = quickbase({ realm: 'company', userToken: 'token' });

// v2 - user token (explicit type)
const qb = createClient({
  realm: 'company',
  auth: { type: 'user-token', userToken: 'token' },
});

// v1 - temp tokens in Code Pages
const qb = quickbase({ realm: 'company', useTempTokens: true });

// v2 - temp tokens in Code Pages
const qb = createClient({
  realm: 'company',
  auth: { type: 'temp-token' },
});

Pagination

// v1 - callback-based
await qb.withPaginationDisabled(async () => qb.runQuery({ body: { from: tableId } }));
await qb.withPaginationLimit(100, async () => qb.runQuery({ body: { from: tableId } }));

// v2 - fluent API
await qb.runQuery({ from: tableId }).noPaginate();
await qb.runQuery({ from: tableId }).paginate({ limit: 100 });

Request Body

// v1 - body wrapper
await qb.runQuery({ body: { from: tableId, select: [3, 6] } });

// v2 - direct parameters
await qb.runQuery({ from: tableId, select: [3, 6] });

Development

# Clone with submodules (includes OpenAPI spec)
git clone --recurse-submodules https://github.com/DrewBradfordXYZ/quickbase-js.git

# Or if already cloned, initialize submodules
git submodule update --init

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Type check
npm run typecheck

# Generate types from OpenAPI spec
npm run spec:generate

Updating the OpenAPI Spec

The spec/ directory is a Git submodule pointing to quickbase-spec. Each SDK pins to a specific commit, so spec updates are controlled:

# Update to latest spec
cd spec
git pull origin main
cd ..
git add spec
git commit -m "Update quickbase-spec submodule"

# Regenerate types
npm run spec:generate

Spec Tools

# Full spec processing pipeline
npm run spec:build

# Individual steps
npm run spec:convert   # Swagger 2.0 → OpenAPI 3.0
npm run spec:patch     # Apply fixes from overrides
npm run spec:validate  # Validate spec
npm run spec:split     # Split by tag (for editing)
npm run spec:generate  # Generate TypeScript types

Documentation

API documentation is auto-generated from source code and hosted at: https://drewbradfordxyz.github.io/quickbase-js/

To generate docs locally:

npm run docs        # Generate docs to ./docs
npm run docs:watch  # Watch mode for development

Documentation is built with TypeDoc and auto-deployed to GitHub Pages on every push to main.

License

MIT