Skip to manual
gluon

API and integrations

Use the generated REST API

Read objects, views and functions and submit actions under the caller's own permissions.

Application developer

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

Shell
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

Shell
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:

  • _id carries 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.

Shell
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-Authenticate points to the discovery document.
  • 403: withheld (code is the reason class, such as marking or policy) or insufficient-scope.
  • 404: absent for this caller.
  • 429: over the client's rate limit. Wait the Retry-After seconds.

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.

Terminal showing list_procurement_contract with parameters q, limit and capability and responses 200 to 429.
The caller's OpenAPI operation for listing contracts, with its parameters and responses.
Terminal showing withheld 9, contract C-1001, ownerEmail as asterisks and negotiatedRate under _withheld.
A contract list with 9 withheld, one property withheld and the owner email masked.