Consumers
A consumer is the API endpoint that exposes contracts to applications, dashboards, and AI agents.
A consumer is the API endpoint through which the outside world reaches your contracts. Builders author contracts; a consumer is what makes them callable. Every application, dashboard, and AI agent talks to a consumer, never to a table or a contract directly.
What a consumer defines
A consumer ties together four things:
| Slug | The consumer's stable identifier, used in its API paths. |
| Scope | The set of contracts (and their collections) this consumer may expose. |
| Protocols | The ways this consumer can be called: query, chat, MCP. |
| API keys | The credentials that authenticate calls to this consumer. |
Once a consumer is published, its contracts are reachable at paths built from
its slug, such as /v1/api/<consumer_slug>/query.
Scope: least privilege
A consumer should expose only the contracts a given audience needs. Scoping is how you give a partner integration access to three contracts without exposing the other forty in your workspace.
Create a separate consumer per audience or per integration. That keeps each API key's blast radius small, and lets you revoke or change one integration without touching the others.
Protocols
A consumer can expose its contracts through three protocols. Enable the ones an audience needs; a consumer can offer more than one at the same time.
REST query API
A structured JSON request that selects dimensions, measures, and filters from a contract, and returns governed rows. Best for dashboards and application features that need exact, repeatable results. See Querying contracts.
Chat completions API
An OpenAI-compatible chat endpoint. The caller sends messages and Gaur's agent answers using the consumer's contracts. Best for conversational features. See Chat.
MCP server
A Model Context Protocol server that lets AI agents and MCP-aware tools discover and call the consumer's contracts as tools. See Using MCP.
The chat completions API is OpenAI-compatible, but Gaur's agent sends more than plain text. Query results and chart suggestions ride along in extra fields that a strict OpenAI client will drop. Integrators should read Chat before building on it.
Query modes
For the chat and MCP paths, a consumer has a query mode that controls how freely the AI agent can answer:
| Mode | Behavior |
|---|---|
| Contract-only | The agent answers strictly through published contracts. |
| SQL-only | The agent answers by generating SQL over the consumer's allowed objects. |
| Contract with SQL fallback | The agent prefers contracts, and falls back to SQL when no contract fits. |
The difference that matters is bounded vs. unbounded AI generation.
- Contract-only is bounded. The agent can only pick a published contract and fill in a query spec that Gaur validates. Every answer is shaped by a contract you authored and verified, so the space of possible queries is fixed and known. This is the safety guarantee to reach for when the surface is customer-facing or untrusted.
- SQL modes are unbounded. When the agent writes SQL, it composes queries freely, so generation is open-ended again. Gaur still constrains it: the SQL is read-only and restricted to the objects this consumer is scoped to, never your whole database, and it is validated before it runs. That keeps SQL modes safe in terms of access, but the shape of a query is no longer bounded by a contract.
Pick the most restrictive mode that still meets the audience's needs. Use contract-only for customer-facing analytical chatbots and embedded UI chat; use a SQL mode for internal or exploratory tools where flexibility matters more than a fixed query surface. See Chat and Using MCP for the integrator's view.
System prompt
A consumer can carry a system prompt: guidance that shapes how its natural-language answers behave, such as tone, domain framing, and what to do with ambiguous questions. Use it to make a consumer's answers fit the product it serves.
Lifecycle
Create the consumer
Give it a slug and a description of the audience it serves.
Scope it to contracts
Add the contracts (typically from one collection) this consumer should expose.
Enable protocols and set the mode
Turn on the REST query API, chat completions API, and/or MCP server, choose a query mode, and add a system prompt if you need one.
Issue API keys
Create one or more API keys so applications can authenticate.
A consumer also has a status. You can deactivate a consumer to take its endpoints offline without deleting it.