knack-api

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