knack-api

View-based API wrapper for the Knack platform. Provides CRUD operations (GET, POST, PUT, DELETE) with automatic pagination, retry logic, and built-in session management.

For object-based requests, see knack-object-api.

Installation

npm install knack-api

Import

// JavaScript
const { knack_api } = require('knack-api');

// TypeScript
import { knack_api } from 'knack-api/ts';

API

All methods accept a settings object and return a Promise.

host and subdomain are optional on all request types. By default, requests go to https://api.knack.com. Setting host: 'knackly' and subdomain: 'api' would send requests to https://api.knackly.com.

knack_api.get(settings)

Retrieves records from a view. Automatically paginates through all available pages.

const results = await knack_api.get({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  host: 'knackly',
  subdomain: 'api',
});

knack_api.post(settings)

Creates a new record.

const result = await knack_api.post({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  payload: { field_1: 'value' },
  retry: true,
});

knack_api.put(settings)

Updates an existing record.

const result = await knack_api.put({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  recordId: '6123abc456def',
  payload: { field_1: 'updated value' },
  retry: true,
});

knack_api.deletion(settings)

Deletes a record.

const result = await knack_api.deletion({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  recordId: '6123abc456def',
  retry: true,
});

Settings Reference

GET Settings

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | sceneKey | string | Yes | — | Scene identifier (e.g. 'scene_1') | | viewKey | string | Yes | — | View identifier (e.g. 'view_1') | | recordId | string | No | — | Fetch a single record by ID | | filters | object | No | — | Filter rules (see Filters) | | sort | object \| object[] | No | — | Sort configuration (see Sorting) | | page | number | No | 1 | Starting page number | | rowsPerPage | number | No | 1000 | Records per page (max 1000) | | recordLimit | number | No | — | Maximum total records to retrieve | | retry | boolean | No | — | Enable retry on failure (up to 3 attempts) | | cb | function | No | — | Callback invoked after each page request | | isPublic | boolean | No | false | Skip authentication for public views | | context | object | No | — | Context for views that require a parent record ID (see Context) | | host | string | No | 'knack' | Host used in the request URL | | subdomain | string | No | 'api' | Subdomain used in the request URL |

POST Settings

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | sceneKey | string | Yes | Scene identifier | | viewKey | string | Yes | View identifier | | payload | object | Yes | Field values for the new record | | retry | boolean | Yes | Enable retry on failure | | isPublic | boolean | No | Skip authentication for public views | | host | string | No | Host used in the request URL | | subdomain | string | No | Subdomain used in the request URL |

PUT Settings

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | sceneKey | string | Yes | Scene identifier | | viewKey | string | Yes | View identifier | | recordId | string | Yes | ID of the record to update | | payload | object | Yes | Field values to update | | retry | boolean | Yes | Enable retry on failure | | isPublic | boolean | No | Skip authentication for public views | | host | string | No | Host used in the request URL | | subdomain | string | No | Subdomain used in the request URL |

DELETE Settings

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | sceneKey | string | Yes | Scene identifier | | viewKey | string | Yes | View identifier | | recordId | string | Yes | ID of the record to delete | | retry | boolean | Yes | Enable retry on failure | | isPublic | boolean | No | Skip authentication for public views | | host | string | No | Host used in the request URL | | subdomain | string | No | Subdomain used in the request URL |

Filters

Pass a filters object to narrow GET results.

const results = await knack_api.get({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  filters: {
    match: 'and',
    rules: [
      { field: 'field_1', operator: 'contains', value: 'search term' },
      { field: 'field_2', operator: 'is not blank' },
    ],
  },
});

Available Operators

| Operator | Description | |----------|-------------| | is | Exact match | | is not | Not equal | | is blank | Field is empty | | is not blank | Field is not empty | | contains | String contains value | | does not contain | String does not contain value | | starts with | String starts with value | | ends with | String ends with value | | is any | Value is in a list | | higher than | Numeric greater than | | lower than | Numeric less than | | near | Location proximity (use range for distance) | | is today | Date is today | | is today or before | Date is today or earlier | | is today or after | Date is today or later | | is before today | Date is before today | | is after today | Date is after today | | is before | Date is before value | | is after | Date is after value | | is during the current | Date during current period | | is during the previous | Date during previous period | | is during the next | Date during next period | | is before the previous | Date before previous period | | is after the next | Date after next period | | is before current time | Time is before now | | is after current time | Time is after now |

Sorting

Sort accepts a single object or an array for multi-field sorting.

// Single sort
const results = await knack_api.get({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  sort: { field: 'field_1', order: 'asc' },
});

// Multi-field sort
const results = await knack_api.get({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  sort: [
    { field: 'field_1', order: 'asc' },
    { field: 'field_2', order: 'desc' },
  ],
});

Include / Exclude Fields

Filter which fields are returned from a GET request using .include() or .exclude().

// Only return specific fields
const results = await knack_api.get(settings).include(['field_1', 'field_2']);

// Return all fields except those specified
const results = await knack_api.get(settings).exclude(['field_3']);

Pagination

GET requests automatically paginate through all available pages and return the combined results. You can control this behavior with:

• rowsPerPage — Records per request (max 1000, default 1000).
• recordLimit — Stop after retrieving this many total records.
• page — Start from a specific page (default 1).

// Fetch up to 200 records, 50 per request
const results = await knack_api.get({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  rowsPerPage: 50,
  recordLimit: 200,
});

Callback

The cb parameter is called after each individual page request. This is useful for tracking progress when fetching large datasets.

const results = await knack_api.get({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  cb: (data) => {
    console.log(`Received ${data.records.length} records`);
  },
});

All records are still accumulated in memory and returned in the final resolved promise.

Public Views

Set isPublic: true to skip user token verification. Use this for views that are accessible without authentication.

const results = await knack_api.get({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  isPublic: true,
});

Available on get, post, and put methods.

Context

Some views require a parent record ID to fetch related data. Pass a context object where the key follows the pattern {page-slug}_id and the value is the record ID.

const results = await knack_api.get({
  sceneKey: 'scene_1',
  viewKey: 'view_1',
  context: {
    'my-page-slug_id': '6123abc456def',
  },
});

Retry Logic

When retry is enabled, failed requests are automatically retried up to 3 times before rejecting the promise.

Session Management

For authenticated requests, the library verifies the user's session token before making API calls. If the session has expired, a modal is displayed prompting the user to log back in, and the promise is rejected with "User token is invalid.".

License

ISC