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

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" },
  retry: true,
});

put(settings)

Updates an existing record.

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

deletion(settings)

Deletes a record.

const result = await 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 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

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