Documentation
Knowledge
knowledge.grounding
REST
ShippingPOST /api/v1/knowledge/groundingMCP tool
Liveknowledge.groundingExposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Knowledge domain.
Operating contract
WHAT THE SHOP'S OWN AI IS WORKING FROM, assembled exactly as it is at the moment an agent answers a customer: the shop's brief, then as many of its remembered facts as the recall budget fits.
THE SPLIT IS THE SAFETY PROPERTY. trusted is material compiled from the shop's OWN rows — its catalog, its prices, its locations, its hours. reference is everything else, and it is handed to the model as data rather than as instruction. Do not merge the two when reporting them: the distinction is what stops a fact somebody typed from reading as a rule the shop set.
THIS IS THE READ THAT EXPLAINS A WRONG ANSWER. When a shop says 'the AI told a customer the wrong thing', the question is what it was grounded on — and a fact that did not fit the recall budget is invisible everywhere else in the product.
THE BUDGET IS A CEILING AND IT BITES SILENTLY. knowledge.list shows every fact the shop has saved; this shows the ones that made it into the prompt. When the two disagree, the shop has more memory than its plan lets any single answer carry, and the fix is fewer, better facts rather than more of them.
A retired fact never appears here, and neither does one scoped to a different agent.
This returns the whole assembled set for the budget, so nothing is truncated beyond that ceiling — which is itself the finding.
Who may call it
- Permission
shop.manageThe caller must hold shop.manage at the ACT level. A read-only dashboard grant on the same section is refused.- Plan
- Every planNo plan gate. Available on every Service VIN plan.
- Retries
naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.- Rate class
readCounted against the read budget — the widest of the four.
Input
This capability takes no arguments.
Output
| Field | Type | Description |
|---|---|---|
| trusted | string[] | — |
| reference | string[] | — |
| trusted_chars | number | — |
| reference_chars | number | — |
Examples
Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.
export SERVICEVIN_API_KEY=svk_live_…
curl -X POST https://www.servicevin.com/api/v1/knowledge/grounding \
-H "Authorization: Bearer $SERVICEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch("https://www.servicevin.com/api/v1/knowledge/grounding", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;import os, requests
res = requests.post(
"https://www.servicevin.com/api/v1/knowledge/grounding",
headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
json={},
timeout=30,
)
payload = res.json()
if not res.ok:
raise RuntimeError(payload["error"]["code"])
data = payload["data"]{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "knowledge.grounding",
"arguments": {}
}
}Refusals
The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.
| Status | Code | When |
|---|---|---|
| 404 | not_found | The id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both. |
| 403 | forbidden | This login does not hold shop.manage. |
| 422 | validation_error | An argument was wrong. The message names the field. |
| 429 | rate_limited | Too many read calls. Back off and retry. |
| 500 | internal_error | Something failed on our side. Nothing was changed. |