Gluon builds /api/v1 on every request from the deployments that serve the person behind the token. Two people using the same client can see different paths, different schemas and different counts. Build against the caller's own OpenAPI document and treat anything missing from it as absent for that person.
Before your first call
You need an approved OAuth client and an access token for the resource https://gluon.example/api/v1 (see Approve OAuth clients and handle rate limits). Send it on every request as Authorization: Bearer $TOKEN.
Every request binds exactly one Capability: the capability query parameter when the client is approved for it, otherwise the client's only Capability offered to the person on the api channel. When the client holds several, name one, or the request binds nothing and is refused.
Read the contract for this caller
curl -s https://gluon.example/api/v1/openapi.json -H "Authorization: Bearer $TOKEN"
The OpenAPI 3.1 document lists the object types the bound Capability reads, and the views, actions and functions whose expose includes api. Properties outside the caller's segments are left out of the schemas.
GET /api/v1/package returns the served package on the api channel: the version the person is served, the deployments that reach them with their segments and Capabilities, and every element with its properties and markings.
Read objects
curl -s 'https://gluon.example/api/v1/objects/procurement.Contract?q=ACME&limit=10' \
-H "Authorization: Bearer $TOKEN"
A list returns {items, withheld}. q searches, and limit runs from 1 to 200 with a default of 50. GET /api/v1/objects/{qname}/{id} returns one object. In every object:
_idcarries the object's id,- a withheld property is absent and named in
_withheld, - a masked value reads
****.
withheld counts the records inside the caller's segments that policy keeps from them. A type that exists for the caller but is withheld answers 403. A type outside their segments answers 404, the same as a type that does not exist.
Views and functions
GET /api/v1/views/{qname} returns the view's object set, filtered and ordered before the limit (1 to 200, default 50). Counts are relative to the reader, so two callers get different numbers for the same view. A view evaluates over one fetch of up to 10,000 rows of its base type.
POST /api/v1/functions/{qname} runs a kind: cel function. Send its inputs as a JSON body; the answer is {"value": ...}. Only values the caller may read unmasked are bound, and a withheld input refuses with evaluation-error.
Submit an action
Actions need a token with the execute scope.
curl -s https://gluon.example/api/v1/actions/procurement.RenewContract \
-H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-d '{"contract": "c-1002", "newExpiry": "2027-10-15"}'
Gluon answers 202 with {run, state, autonomy, riskTier}. state is pending-approval, with an approvalUrl, when an approver must sign off; proposed when the Capability caps autonomy at L2, so nothing runs; otherwise the state the run reached after Gluon queued it. Sending the same parameters again returns the same run.
Ask a question
POST /api/v1/ask with {"question": "..."} runs the chat pipeline on the api channel and returns the cited answer, with the same withheld counts a chat answer would carry.
Add "mode": "accurate" to search several times and read further before answering (about a minute); "fast", or no mode, runs one search. The answer says which mode answered (mode), whether a Fast answer searched further by itself (escalated) and how long it took (answerMs). A Capability set to one mode refuses the other with 422 mode_pinned. The MCP ask tool takes the same mode argument.
Handle refusals
A refusal is {"code": ..., "detail": ...} with one of these statuses:
- 401: the token is missing, expired or meant for another resource.
WWW-Authenticatepoints to the discovery document. - 403: withheld (
codeis the reason class, such asmarkingorpolicy) orinsufficient-scope. - 404: absent for this caller.
- 429: over the client's rate limit. Wait the
Retry-Afterseconds.
A context object you send in a body is dropped and audited as api.client-context-ignored; the channel, device and network come from the token and the gateway. Every read that returns data writes one api.read audit record with the objects returned, the withheld count and the deciding policy per object.
Renamed properties
After a property is renamed, the old name stays in the schema marked deprecated with the version it will be removed in, and responses carry the value under both names until then. Move your code to the new name before that version reaches your deployment.

