JQL Fundamentals
JQL overview
The POST /jql contract, response envelope, schemas, multi-query requests, and debugging entry points.
JQL is Antly's JSON Query Language. Clients send a JSON document to POST /jql; the server reads the __meta__ envelope, resolves a model, controller, or NoSQL processor, executes the requested intent, and returns a consistent envelope.
The endpoint is registered as ^jql in the API service. Multipart requests use PUT /jql; realtime consumers subscribe through WS /jql-streams. Start with the developer quickstart at /developer/quickstart-api and the authentication guide at /developer/authentication-classes.
Request shape
Every single JQL request needs __meta__.namespace and __meta__.intent. schema should be supplied for clarity and is normally one of model, controller, or nosql.
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "system.User",
5 "intent": "retrieveOne",
6 "authenticationClass": "jwt",
7 "uniqueObject": {
8 "id": 42
9 }
10 },
11 "id": null,
12 "email": null,
13 "firstName": null,
14 "lastName": null
15}Incoming camelCase keys are normalized before processing, so public examples use authenticationClass, uniqueObject, sideEffects, and groupBy; internally these become snake_case.
Response envelope
Single-query responses use these top-level fields:
__payload__: the data returned by the processor.__message__: success or controller message for mutating operations.__extras__: pagination counts, cursors, or controller-specific metadata.__errors__: structured errors when the processor returns recoverable errors.__system__: optional DB query diagnostics.__intent__: the processed intent.
1{
2 "__payload__": [
3 {
4 "id": 42,
5 "email": "admin@example.com"
6 }
7 ],
8 "__message__": null,
9 "__extras__": {
10 "filtered": 1,
11 "display": 1,
12 "queries": 8
13 },
14 "__errors__": null,
15 "__system__": null,
16 "__intent__": "retrieve"
17}Set __meta__.render to only:data when a client needs only the payload body.
Schemas
modelresolvesapp.Modelthrough Django app metadata, applies permissions, model serializers, filters, mutation hooks, and event dispatch.controllerresolvesapp.ControllerNametosrc.<app>.controllers.<ControllerName>JqlControllerand callson_<intent>.nosqlroutes to the NoSQL processor for DynamoDB-backed surfaces such as chat-style data.
Multi-query requests
If the root object has no __meta__, JQL treats it as a map of named subqueries. __root_meta__ can carry root authentication settings without being processed as a query.
1{
2 "__root_meta__": {
3 "authenticationClass": "jwt"
4 },
5 "me": {
6 "__meta__": {
7 "schema": "controller",
8 "namespace": "system.User",
9 "intent": "verifyAuthentication"
10 },
11 "id": null,
12 "email": null
13 },
14 "openTickets": {
15 "__meta__": {
16 "schema": "model",
17 "namespace": "tickets.Ticket",
18 "intent": "retrieve",
19 "filter": {
20 "status": "open"
21 },
22 "limit": 5
23 },
24 "id": null,
25 "title": null,
26 "created": null
27 }
28}The response payload mirrors the query keys and wraps each result with data, extras, message, errors, notices, and intent.
Debugging
Use __meta__.debug: true in non-production contexts to allow underlying exceptions to surface. For query diagnostics, pass query_info_level or db_query_info_level as query parameters; level 1 returns count/time and level 2 includes SQL query details.
Related pages: namespaces, intents, errors, and /developer/realtime-streams.