Public Query API
Any query you publish in Kvery becomes a callable HTTP endpoint. Your application, a script, or another service can hit that endpoint and receive the query's result as JSON — no database credentials on the client side, just a URL.
The endpoint
Each shared query is addressed by its hash:
https://app.kvery.io/query/api/{hash}
The {hash} is the share identifier generated when you
share the query. Treat it like a secret: anyone with the
URL (and password, if you set one) can call the endpoint.
The endpoint always runs the published version of the query: an unpublished draft does not change what callers get until you publish it.
Methods map to your SQL
Kvery decides what a request does based on the HTTP method, and a query only answers the methods that match the kind of SQL it contains:
| Method | Serves queries that… | Typical use |
|---|---|---|
GET | read (SELECT, EXEC, WITH … SELECT) | fetch data |
POST | write (INSERT, UPDATE, DELETE, REPLACE, ALTER, CREATE) | create / submit |
PUT | write | replace |
PATCH | write | partial update |
DELETE | write | remove |
So a SELECT query is reachable with GET, while an INSERT/UPDATE/DELETE
query is reachable with POST/PUT/PATCH/DELETE.
Passing parameters
Form variables in your SQL (for example
$status) become request inputs. Supply them as query-string parameters on GET
or in the request body on write methods — the parameter name matches the variable
name without the $ (so $status is passed as status=…):
# GET with a parameter
curl "https://app.kvery.io/query/api/{hash}?status=open"
# POST a write query
curl -X POST "https://app.kvery.io/query/api/{hash}" \
-H "Content-Type: application/json" \
Caching
GET responses that anyone may get — the query is shared without a password and
the group's IP whitelist allows the caller — are served
with a public HTTP Cache-Control header, so repeat reads can be served from cache.
Every other response (Basic Auth, share password, IP whitelist) is marked
private, no-store. Queries can also enable Kvery's own result cache, which
short-circuits identical reads for speed; cached results are only returned to callers
who pass the same checks. Write requests are never cached. See
Export & cache for how caching behaves.
Securing the endpoint
- Set a password on the share so callers must authenticate.
- Set an expiry so the hash stops working after a date.
- Restrict the group with an IP whitelist.
- Apply rate limits so the endpoint can't be hammered.
Calling a query that is not shared
The endpoint of a query that is not shared only answers calls with Basic Auth:
the e-mail address and password of a Kvery user who can access the query. Basic
Auth sends the password with every request and does not ask for the
two-factor code, so for scripts and
integrations prefer MCP tokens and the MCP server's
REST API. Repeated failed Basic Auth attempts are blocked for a while: the
endpoint then answers 429 Too Many Requests with a Retry-After header until
15 minutes have passed since the last failed attempt.
Shaping the response
Use directives to control status codes and error
messages (SET HTTPCODE, ON ERROR RETURN), and
column modifiers to shape the JSON (for example
::hidden to drop internal columns, ::json to embed parsed JSON).
Next steps
- Send many operations in one call with batch requests.
- Generate interactive docs for a whole group with Swagger.