Pagination & filtering

List endpoints (such as workspaces) share a set of query parameters, all prefixed with $. Not every endpoint supports every parameter — each endpoint's reference page lists the ones it accepts.

Paging through results

Combine $offset and $limit to walk the collection. The meta.maxResults field in the response tells you the total number of matching items, so you know when to stop. A list response wraps the rows in items:

{
  "items": [ /* … */ ],
  "meta": { "maxResults": 128 }
}

# First page
curl "https://api.knips.com/feeds?\$offset=0&\$limit=20" -H "x-api-key: YOUR_API_KEY"

# Next page
curl "https://api.knips.com/feeds?\$offset=20&\$limit=20" -H "x-api-key: YOUR_API_KEY"

Contact search

Contacts use the optimized POST /feeds/{feedId}/contacts-search endpoint. Pagination, filtering, sorting and selected fields are sent in the JSON request body. limit and offset are required. The maximum limit is 100. A larger value returns 400 and the search is not run.

Omit filter to search all contacts in the workspace:

curl https://api.knips.com/feeds/YOUR_FEED_ID/contacts-search \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 20,
    "offset": 0,
    "orderBy": { "field": "created", "direction": "desc" },
    "fields": ["id", "name", "email", "created"]
  }'

Use a structured filter to narrow the results:

{
  "limit": 20,
  "offset": 0,
  "filter": {
    "type": "filter",
    "field": "name",
    "operator": "like",
    "value": "ola"
  }
}

Product search

Products use POST /feeds/{feedId}/products-search. Pagination, filtering, sorting, selected fields and natural-language search are sent in the JSON request body. limit and offset are required. The maximum limit is 100.

Omit filter and prompt to search all products in the workspace:

curl https://api.knips.com/feeds/YOUR_FEED_ID/products-search \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 20,
    "offset": 0,
    "orderBy": { "field": "created", "direction": "desc" },
    "fields": ["externalId", "title", "price", "imageUrl"]
  }'

Use a structured filter to narrow the results:

{
  "limit": 20,
  "offset": 0,
  "filter": {
    "type": "filter",
    "field": "title",
    "operator": "ilike",
    "value": "bottle"
  }
}

Sorting

For GET list endpoints, pass a field name followed by a direction — asc (default) or desc, separated by a space:

?$orderBy=createdAt desc

Filtering

For GET list endpoints, $filter takes an OData-style expression of the form field operator value, with string values in single quotes. Combine conditions with and / or.

?$filter=name eq 'Summer campaign'
?$filter=created gt '2026-01-01' and archived eq false

The set of filterable fields depends on the endpoint — each endpoint's reference page shows whether it supports $filter.

On GET /feeds, results are automatically scoped to the workspaces your API key can access — your $filter is combined with that scope.