GraphQL
GraphQL lets a caller ask for exactly the fields it needs. For an assistant that is genuinely useful, and it is also the reason scope discipline matters more here.
GraphQL lets a caller ask for exactly the fields it needs. For an assistant that is genuinely useful, and it is also the reason scope discipline matters more here.
What a GraphQL API exposes, and why that matters here
GraphQL exposes a single flexible interface where the caller specifies precisely what it wants. That efficiency is real — an assistant can retrieve exactly the fields needed for an answer rather than pulling a whole object.
The same flexibility means the interface itself imposes fewer boundaries than a REST endpoint does. Where REST exposes named resources, GraphQL exposes a graph, and the discipline about what may be traversed has to come from configuration rather than from the interface shape.
- Schema — the shape of what is available.
- Queries — the specific retrievals defined for the assistant.
- Field-level selection — retrieving only what an answer needs.
- Authentication — credentials you issue and control.
- Permissions — what a given identity may traverse.
Questions Elbi can answer over GraphQL
What is this record?
Specific fields retrieved rather than a whole object.
What is related to it?
Connected records, where the schema exposes the relationship.
What is the current state?
Live status from the system.
Which of these match?
A filtered set described for a business reader.
What changed?
Fields that differ from what was expected.
Record this
Where a mutation is deliberately enabled and scoped.
How Elbi works with a GraphQL API
- One endpoint, many possible questionsA GraphQL API usually serves everything through a single endpoint, and the query text decides what comes back. Scope therefore cannot be set by allowing a URL, as it can with REST; it has to be set by which queries are allowed.
- Named queries, written in advanceEach question Elbi answers maps to a named query written and reviewed during deployment, such as fetching an order's status and delivery date by reference. Where the server supports persisted queries or an operation allow-list, those queries are registered there as well, so nothing else is accepted from the credential.
- Variables, never string-buildingDetails gathered in conversation, such as a reference or a date, are passed as typed variables. The schema's types reject a value of the wrong shape before the query runs.
- Only the fields a sentence needsBecause the caller chooses the fields, a query can ask for status and date and nothing more. Responses stay small, and personal data the answer does not need stays inside your system.
- Errors can arrive with a success statusGraphQL servers commonly return HTTP 200 with an errors array, sometimes next to partial data. A response carrying errors is treated as a failed lookup and said to be one; no answer is built from half a result.
- Mutations are listed one by oneChanges in GraphQL are mutations. Any mutation Elbi may call is named individually with fixed arguments and can wait for a person's confirmation; the schema's other mutations are simply never sent.
GraphQL queries, schema permissions and what stays yours
| Direction of access | Named queries only. Mutations are separate entries, each enabled deliberately. Subscriptions and introspection are not needed to answer questions and are left unused. |
|---|---|
| Who can see what | A GraphQL server usually enforces authorisation per type and per field. The credential's own permissions set the ceiling, and passing the asker's identity lets the server narrow results to their own records. |
| Credentials | Typically a bearer token or an OAuth client issued in your system, scoped as narrowly as the API allows. Revoking it cuts the connection straight away, without involving us. |
| Where data goes | Queries select only the fields an answer needs, and responses serve that answer without being stored. The conversation's message content is destroyed within 24 hours, and no outside AI service is shown any of it. |
| Audit | Each call is logged with its operation name, variables, outcome and conversation, so a reviewer sees which named query ran for which reference rather than an anonymous request to the endpoint. |
| If it is unavailable | Timeouts, server errors and refusals on cost or rate grounds are reported as unavailability, with a person offered. No answer is assembled from partial data. |
What this replaces
The efficiency benefit is genuine: retrieving three fields instead of an entire object makes answers faster and reduces how much data moves at all, which is a small privacy benefit as well as a performance one.
The scope discipline is the important half. Because a graph interface can traverse relationships, a permissive configuration can reach further than anyone intended — from a customer to their orders to their payment records — without that ever being an explicit decision.
The right approach is named, parameterised queries defined during deployment rather than allowing the assistant to compose them. That keeps the connection as narrow and reviewable as a named REST operation while retaining the field-level efficiency.
Where a GraphQL connection fits
Modern application estates
Where GraphQL is the primary interface.
Composite services
Systems aggregating several sources behind one graph.
Mobile-first products
Where the interface was designed for selective retrieval.
Any GraphQL system
Efficient retrieval with explicitly bounded traversal.
Getting value from a GraphQL API
GraphQL earns its keep when an answer spans related records. "When will my order arrive" may need the order, its shipment and the carrier's latest event; in GraphQL that can be one query returning three fields, where REST might need three calls.
Start with questions whose data already sits close together in the graph, and write their queries against a test environment. Keep each query shallow. A query that walks from customer to orders to payments to cards is exactly the traversal nobody meant to approve.
If the API reports query cost or complexity, check each named query against it before launch. A query that is cheap for one customer and expensive for another with a long history is better found in testing than in a refusal on a busy morning.
What connecting a GraphQL API involves
- Start from questions, not the schemaThe schema shows everything that could be asked; real contact shows what is asked. Choose from the second list.
- Write and review the queriesEach named query, with its variables and selected fields, is written down and reviewed by your team. That set of documents is the scope, and it is what an auditor will read.
- Register them where the server allowsIf your GraphQL server supports persisted queries or an operation allow-list, the reviewed queries are registered there, so the credential cannot run anything else.
- Issue a narrow credentialYour team issues the token or OAuth client with the least access the queries need, and keeps the ability to rotate or revoke it.
- Test depth, cost and errorsUnknown references, a customer with a very long history, a field the credential may not read, partial errors, the server refusing a query as too expensive. Each should give a predictable answer.
- Launch with a few queries, then addGo live with the questions asked most, read a month of real traffic, then add further queries or a first mutation.
Personal data and GraphQL traversal
In a graph, personal data is rarely more than a hop or two away: a customer node links to addresses, orders, payments and identity documents. Under the Saudi Personal Data Protection Law the question is what is actually processed, and in GraphQL that is decided by the fields each query selects. Reviewing those selections is the privacy review.
Select only what each answer needs, prefer identifiers to whole objects, and keep sensitive types out of every query unless a flow requires them. What Elbi retrieves is used for the answer, and the conversation holding it is destroyed within 24 hours.
What organisations typically see
GraphQL, REST and when each is the right way in
Where a system offers only GraphQL, as some commerce and SaaS platforms now do for their main API, it is the way in. Where it offers both, REST is usually simpler to scope, because each allowed operation is a path; GraphQL is the better choice when answers need fields from several related records, or when the REST equivalent would return far more than needed.
Some teams let an AI assistant compose GraphQL queries on the fly from the schema. That is flexible, and it is also where traversal and cost problems come from, because nobody reviews a query before it runs. Named, reviewed queries give up little of GraphQL's efficiency and keep the connection explainable.
The other common mistake is treating an HTTP success status as success. In GraphQL, the errors array is where failures are reported.
Common questions
Not by default, and it should not. Named parameterised queries defined at deployment keep the connection reviewable.
It is the thing to configure carefully. A permissive graph connection can reach further than intended without that being an explicit decision.
Where you deliberately enable specific ones, optionally behind confirmation.
Elbi uses a token your team issues, and only to run the named queries agreed at deployment. You can revoke that token at any time without going through us.
Named queries make changes visible. If a field they use is removed or renamed, the query fails loudly instead of quietly returning something different, and GraphQL's deprecation markers usually give warning first. Queries are updated as part of routine review.
Not for answering questions. A subscription keeps a connection open for live updates, which a conversation rarely needs; a fresh query at the moment of the question is simpler. For telling people about changes as they happen, webhooks are the usual route.
Connect Elbi to your GraphQL API
Reviewed, named queries against your own schema, answered in Arabic and English.