v2 API Overview

The Knowify Developers API is currently in transition between two surfaces:

Version	Status	When to use
v2	Active, recommended	All new integrations
v1	Legacy, frozen	Existing integrations only — no new endpoints land here

If you're starting fresh, build against v2.

What v2 looks like

Every resource follows a small, predictable contract.

Reads

GET    /api/v2/{resource}              # list, with filtering/sorting/pagination
POST   /api/v2/{resource}/query        # same shape as GET, but the query is a JSON body
GET    /api/v2/{resource}/{id}         # one record by Id

Writes

POST   /api/v2/{resource}              # create
PATCH  /api/v2/{resource}/{id}         # partial update
DELETE /api/v2/{resource}/{id}         # soft-delete

The query shape (used by both GET and POST /query) is one consistent dialect:

Param	Purpose
where	Filter — keys are field names, values are literals or operator objects ($eq, $in, $gte, $iLike, …)
order	Sort — array of `[field, "ASC"
fields	Choose which fields to return — CSV, array, or { exclude: [...] }
scopes	Apply named filters defined on the resource (active, forResource({ Id }), …)
include	Load related records inline
limit / offset	Pagination
since	Return records modified at or after an ISO-8601 timestamp

Same dialect on every resource. Learn it once, use it everywhere.

Responses

• List endpoints return { data: [...], meta: { total, limit, offset, has_more } }.
• Single-record endpoints return the entity directly.
• Errors are RFC 7807 problem+json.

Authentication

Two paths, pick whichever fits your situation:

1. OAuth 2.0 — the standard flow. Best for third-party apps that need user consent, managed token refresh, and scoped permissions.
2. Direct kAuth — Authorization: kauth <token>. Best when you already hold a Knowify session token and want the simplest possible auth header.

Both reach the same endpoints. Direct kAuth is granted the admin meta-scope (full read+write across every resource); OAuth tokens carry whatever scopes the consent grant approved.

Differences from v1

Concern	v1	v2
Response envelope	{ didSucceed, data, status, message }	{ data, meta } for lists, entity directly for single records
Errors	{ didSucceed: false, message, status }	application/problem+json (RFC 7807)
Pagination	page / page_size / sort / sort_asc	limit / offset / order: [[field, dir]]
Filtering	A handful of resource-specific query params	Unified where clause across every resource
Field projection	fields=...	Same — CSV, array, or { exclude: ... }
Sub-resources	Nested paths (/projects/:id/list-items)	Flat resources with FK filters (/list-items?where[ProjectId]=:id)

The biggest user-visible change is the unified query shape — instead of every resource having its own ad-hoc filter params, every resource uses the same where / order / fields dialect.

Endpoint reference

The full per-resource reference lives in the API Reference → — auto-generated from the live OpenAPI spec, so it never drifts from the running service.