Query API

The Query API provides advanced read operations with filtering, pagination, and batch queries. It is available alongside the standard Resource API endpoints.

All query endpoints require a Bearer access token and the appropriate :read scope.

Batch Query

Fetch multiple resource types in a single request:

POST /api/v1/query
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

Request Body

An object mapping model names to query options:

{
  "Projects": {
    "limit": 10,
    "offset": 0,
    "where": { "Status": "Active" }
  },
  "Invoices": {
    "limit": 5,
    "sort": "DateCreated DESC"
  }
}

You can alias results using as:

{
  "Projects as activeProjects": {
    "where": { "Status": "Active" }
  },
  "Projects as archivedProjects": {
    "where": { "Status": "Archived" }
  }
}

Response

{
  "didSucceed": true,
  "data": {
    "activeProjects": {
      "data": [...],
      "total": 42,
      "limit": 100,
      "offset": 0
    },
    "archivedProjects": {
      "data": [...],
      "total": 8,
      "limit": 100,
      "offset": 0
    }
  },
  "timing": 234
}

Single Model Query

Query a specific model with full filtering:

POST /api/v1/query/:modelName
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

Requires the {scope}:read permission for the model (e.g., projects:read for Projects).

Request Body

{
  "limit": 20,
  "offset": 0,
  "where": {
    "Status": "Active",
    "ClientId": "c123"
  }
}

Response

{
  "didSucceed": true,
  "data": [...],
  "total": 156,
  "limit": 20,
  "offset": 0,
  "timing": 123
}

Find by ID

Fetch a single record by primary key:

POST /api/v1/query/:modelName/:id
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

Response

{
  "didSucceed": true,
  "data": { ... single record ... },
  "timing": 45
}

Available Models

Use these PascalCase names in query requests:

Model Name	Resource Slug	Scope Prefix
Projects	projects	projects
Payables	bills	bills
Clients	clients	clients
Departments	departments	departments
Invoices	invoices	invoices
AiaInvoices	aiainvoices	invoices
Items	items	items
Milestones	milestones	milestones
Payments	payments	payments
Requests	purchases	purchases
Resources	resources	resources
ServiceTickets	tickets	tickets
TimeEntries	time	time
Vendors	vendors	vendors
Allocations	allocations	allocations
Billables	billables	billables
Contracts	contracts	contracts
Documents	documents	documents
Users	users	users
Submittals	submittals	submittals
Assets	assets	assets
ListItems	list-items	list-items

Example: Dashboard Data in One Request

curl -X POST https://developers.knowify.com/api/v1/query \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Projects as recentProjects": {
      "limit": 5,
      "sort": "DateCreated DESC"
    },
    "Invoices as unpaidInvoices": {
      "limit": 10,
      "where": { "Status": "Sent" }
    },
    "TimeEntries as todayTime": {
      "limit": 50,
      "where": { "Date": "2024-03-15" }
    }
  }'

Error Responses

Status	Meaning
400	Invalid query body or unknown model
401	Missing or invalid access token
403	Token lacks required scope for the queried model
503	Query engine unavailable