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

Next-Gen Knack support (v3.1.0+)

v3.1.0 works on both Classic and Next-Gen Knack apps. It detects the platform at runtime: Classic reads the synchronous globals (Knack.getUserToken(), Knack.application_id), while Next-Gen uses the promise-based object API (Knack.getUser(), Knack.getApplicationDetails()). Network requests use the native fetch API instead of jQuery (Knack.$.ajax), which Next-Gen removes. No code changes are required in your app — the imports and method signatures are unchanged.

Migrating from v2 to v3

Imports

// v2
const { knack_api } = require("knack-api");
import { knack_api } from "knack-api/ts";

// v3
import { get, post, put, deletion } from "knack-api";

Calling methods

// v2
await knack_api.get({...});
await knack_api.post({...});
await knack_api.put({...});
await knack_api.deletion({...});

// v3
await get({...});
await post({...});
await put({...});
await deletion({...});

Types (TypeScript)

// v2 - lowercase
import {
  getSettings,
  putSettings,
  postSettings,
  deleteSettings,
} from "knack-api/ts";

// v3 - PascalCase, imported from main entry
import {
  GetSettings,
  PutSettings,
  PostSettings,
  DeleteSettings,
} from "knack-api";

Filter rules value type

// v2 - used to accept string only
value?: string;

// v3 - now accepts any type
value?: any;

Package output

v2 shipped raw JS files (knack_api.js, helpers/). v3 ships compiled output only, the package contains dist/ with CJS, ESM, and type declarations.

Import

// JavaScript
import { get, post, put, deletion } from "knack-api";

// TypeScript
import {
  get,
  post,
  put,
  deletion,
  GetSettings,
  PutSettings,
  PostSettings,
  DeleteSettings,
} from "knack-api";

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.

get(settings)

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

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

post(settings)

Creates a new record.

const result = await post({
  sceneKey: "scene_1",
  viewKey: "view_1",
  payload: { field_1: "value" },
});

put(settings)

Updates an existing record.

const result = await put({
  sceneKey: "scene_1",
  viewKey: "view_1",
  recordId: "6123abc456def",
  payload: { field_1: "updated value" },
});

deletion(settings)

Deletes a record.

const result = await deletion({
  sceneKey: "scene_1",
  viewKey: "view_1",
  recordId: "6123abc456def",
});

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 | | 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 | | 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 | | 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 | | 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 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 get({
  sceneKey: "scene_1",
  viewKey: "view_1",
  sort: { field: "field_1", order: "asc" },
});

// Multi-field sort
const results = await 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 get(settings).include(["field_1", "field_2"]);

// Return all fields except those specified
const results = await 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 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 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 get({
  sceneKey: "scene_1",
  viewKey: "view_1",
  isPublic: true,
});

Available on get, post, put and deletion 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 get({
  sceneKey: "scene_1",
  viewKey: "view_1",
  context: {
    "my-page-slug_id": "6123abc456def",
  },
});

Retry Logic

Failed requests are automatically retried up to 3 times before rejecting the promise. This behavior is built in and not configurable.

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