Querying

Run SOQL, SOSL, SAQL or plain-English queries over any object through one endpoint.

Everything you store in klerc can be queried, and one endpoint takes all of it: structured SOQL, full-text SOSL, SAQL analytics or a plain-English question. klerc works out which one you sent.

One endpoint#

http

POST /api/v1/query

Field	Required	What it's for
`text`	Yes	The query — SOQL, SOSL, SAQL, a search term, or a question in plain English
`limit`	No	Maximum rows to return
`cursor`	No	Cursor from a previous response, for the next page
`defaultSlug`	No	A default object slug — see the reference

The token needs the query:run scope.

bash

curl -X POST https://api.klerc.co/api/v1/query \  -H "Authorization: Bearer $KLERC_TOKEN" \  -H "Content-Type: application/json" \  -d '{"text": "SELECT insurer, COUNT(Id), SUM(premium) FROM motor_policy GROUP BY insurer", "limit": 50}'

SOQL#

SOQL is a structured query language over your objects. It supports:

SELECT with aliases, parent paths through lookups, and subqueries;
WHERE with the full set of comparison operators;
GROUP BY, HAVING and ORDER BY;
aggregates COUNT, COUNT_DISTINCT, SUM, AVG, MIN and MAX;
LIMIT and cursor pagination.

Your permissions are injected into every query automatically, so a query never returns records or fields you couldn't see in the console. Formula fields are computed at query time.

sql

SELECT insurer, COUNT(Id), SUM(premium)FROM motor_policyWHERE status IN ('Active', 'Renewing')GROUP BY insurerORDER BY SUM(premium) DESCLIMIT 10

Object and field names are your own keys — motor_policy, premium and status come from the demo brokerage.

SOSL and search#

SOSL searches text across every object at once, scoped by name, email, phone or all fields. A bare term also works, which is handy for a "find anything" box in your own tools.

SAQL#

SAQL is a pipeline language compiled to klerc's columnar analytics engine. It's the language behind reports: POST /reports accepts a saql field, and saved reports run through GET /reports/{id}. See /docs/api/reports.

Plain English#

Send a question as text and klerc translates it into the right dialect:

json

{ "text": "renewals due this month by insurer" }

This is the same translation that powers the console's search bar and Molly.

The response#

Results come back in the standard envelope, with the query result in data. The result carries its columns and rows, totals, a cursor when there's more, and any warnings and timing. The reference has the exact shape.