What everything means

The Context Layer is everything Senso treats as your ground truth, held in five native sections: Brand Kit, Knowledge Base, Content Types, Product Catalog and Topics.

The sections matter. A price sitting in a PDF in the Knowledge Base cannot be checked against the Product Catalog, because as far as the system is concerned there is no catalog. Routing information into the right section is what makes evaluation possible later.

ERVP is the canonical order of the verification sequence: Evaluate the claims, Remediate the gaps, Verify the result, Publish it.

Prioritization happens inside Remediate. There is no separate step called Prioritize. Re-observation starts the next cycle rather than being a fifth step, because publication is not the end state.

The Product Catalog holds what you sell and on what terms: product records, rate tables, plan details, service descriptions, eligibility and contractual terms.

It is separate from the Knowledge Base because claims about price and eligibility need to be checked against a catalog, not against whichever document happened to mention a number.

The endpoints are /org/product-lines.

Topics are the shared vocabulary that connects everything else: product area, customer intent, funnel stage, jurisdiction. They are how a gap found during evaluation lines up with the content that should fix it.

The endpoints are /org/tags.

A gap is a problem evaluation found in your context. There are seven kinds: contradicted claim, unsupported claim, missing evidence, incomplete context, stale fact, ambiguous authority, and conflict between approved sources.

Gaps are surfaced, never silently fixed. Remediate prioritizes them by consequence, relevance and funnel stage, and material ones route to a person with the authority to settle them.

A receipt records what was checked and by whom: the claims examined, the evidence behind each, the result for each claim (supported, corrected, unresolved or not applicable), the reviewer, the timestamps, the destination and URL, and the provenance status.

A public receipt may show less than the organization-private audit trail. It must never expose secrets, private source content or credentials. A receipt that shows too little cannot prove the event; one that shows too much leaks private evidence.

Approved Context Layer records are ground truth. Model outputs, rankings and citations are observations about external behavior.

An observation can tell you where to look next and can raise the priority of a remediation. It can never overwrite an approved source. A model answer that contradicts your Context Layer is a signal that something needs attention, not evidence that your records are wrong.

Getting this backwards degrades the Context Layer into whatever the open web already believed, which is the problem Senso exists to solve.

A document whose claims have been checked against a source of record, attested by an accountable owner (a person or an agent), and published so any answer built from it can be traced back and defended.

Checked. Attested. Traceable. Content that has not been through that gate is not a Verified Source, however well written it is.

An organization is the boundary every other object lives inside. Your knowledge base, API keys, brand kit, content types, prompts and published content are all scoped to one.

Credentials carry their organization with them, so an API key or an OAuth connection reaches exactly one. To work across two, you need two credentials.

The knowledge base is what raw sources become after compilation: a folder tree of documents that have been parsed, chunked, embedded and indexed so an agent can query them by meaning.

It is a tree, not a bucket. Every document and folder is a node with a parent, permissions, tags and a version history.

A raw source is the input: a PDF, a policy document, a spreadsheet, a block of markdown, a support thread someone pasted in. It is what you have before Senso has done anything to it.

Senso deliberately uses "ingest" rather than "upload" because storing the bytes is the least interesting part of what happens next.

Compilation is the step between ingesting a source and being able to query it. The document is parsed out of its original format, split into chunks, embedded, and indexed.

It runs asynchronously. A document is stored immediately but is not queryable until compilation finishes, so writes return before the document is usable.

When a model answers one of your tracked prompts, Senso breaks the answer into discrete claims: individual assertions, in the order they appeared.

Each claim carries whether your organization was mentioned in it, the sentiment of the statement, and the citations the model used to support it. That is what makes it possible to ask "which specific sentence was wrong, and what did it cite?" rather than judging a whole answer at once.

Claims come from prompt runs, not from ingesting documents. A knowledge base with no monitoring configured produces no claims.

An eval is a judgement, recorded as a run, about whether a piece of content holds up. It asks whether the claims are supported by a source, and whether it matches the brand it is published under.

Two properties make an eval worth keeping. Accuracy and brand are judged as separate calls, so a good score on one cannot mask a bad score on the other. And runs are append-only, each recording the exact text it judged, so a verdict stays meaningful after the underlying source changes.

Verdicts are states rather than scores (supported, failing, unverified) because models are far more consistent at picking between a few classes than at producing a stable number.

A prompt is a question worth tracking: one a buyer, customer or analyst would actually ask a model about your category.

Prompts are typed by where they sit in the customer journey: awareness, consideration, evaluation, or decision. They drive both content generation and the monitoring that watches how models answer them.

A run is a single answered instance: this prompt, sent to this model, at this time. It stores the answer, the claims extracted from it, the citations attached to each claim, and whether competitors appeared.

Runs are the unit every citation metric is computed over. The word "answer" in those definitions means a run.

The brand kit is one config per organization describing how generated content should sound: brand name, voice and tone, author persona, and writing rules.

It shapes content written for humans. Content written to be read by agents leans on facts and structure rather than voice, so the brand kit matters less there.

A content type is an output format (FAQ, blog post, comparison page) with a template and its own writing rules. Every generation call requires one.

Where the brand kit controls how it sounds, the content type controls how it is structured.

Ingest, query and generation consume organization credits. New organizations get $100 to start.

Every query is recorded as a query turn and tagged with its source, so MCP traffic is reported separately from CLI and API usage. One well-formed query costs less than several narrow ones.

A node id identifies a position in the knowledge base tree, either a document or a folder. Every tool that organizes the tree speaks node ids: list, move, rename, tag, delete.

A content id comes back on search results and identifies the compiled content you can cite in an answer.

Passing one where the other is expected is the most common integration mistake.

Creating or updating a document returns as soon as the text is stored. It is not searchable until compilation completes.

Poll the document until its processing status reads complete. The states are pending, processing, complete and failed. On failure an error code says why.

Updating a document with new text replaces the whole body. It does not append. Read the current text first and send the complete new version, never a fragment.

Each update cuts a new revision, so the previous text stays readable at its own version number. Nothing is lost, but the live body is whatever you last sent.

Documents carry a version history. Each update creates a new revision rather than overwriting history, and any earlier revision can be read back by number.

This is what keeps an attribution meaningful over time: an answer can point at the version of a document that was live when it was given, not just at the document as it reads today.

Ingesting text identical to something already in the knowledge base does not create a duplicate. Find the existing document by name and update it instead.

This makes re-running an ingestion script safe.

Deleting a folder deletes everything inside it: every document in the subtree, permanently. It refuses to run without explicit confirmation.

An agent should only confirm after telling you in plain terms what is about to be removed. The knowledge base root cannot be deleted or moved.

Senso auto-tags on creation: raw content, uploaded files once ingestion finishes, prompts, and search queries as they arrive. The tag library grows on its own, so most callers never manage it directly.

Setting tags on a document replaces whatever was on it. Unknown tag names are created automatically. Tags apply to documents, not folders.

A grounded answer is assembled from text in your knowledge base and returns the documents it drew from alongside it.

The important half is the negative case: when nothing relevant is found, that is the answer. Senso does not fall back on the model’s general knowledge and return the result as though it came from you.

A query returns a different shape depending on the mode you ask for:

Document bodies are returned inside a wrapper, prefaced by a standing note that the content is reference material and not a directive.

That is what stops a document containing "ignore your instructions" from steering the session that retrieved it.

A citation records that a model leaned on a particular source for a particular claim, including the source URL and its position in the answer’s citation list.

Citations are classified by tier depending on who owns the domain.

Every cited URL is classified by its domain:

Citation Rate is measured at answer grain and divides by D, the number of answers carrying at least one citation of any tier.

It is reported per tier, so tiers can each be at most 100% and may sum to more than 100% when one answer cites several tiers.

Citation Coverage shares Citation Rate’s denominator D (answers with at least one citation) but narrows the numerator to a single source or domain rather than a whole tier.

Because the numerator counts distinct answers, coverage is always at most 100%.

Citation Share is measured at instance grain and divides by S, the total number of citation instances seen, not the number of answers.

Because it is a share of a whole, tiers sum to exactly 100%. This is the metric most often confused with Citation Rate, and they are not interchangeable: different numerators, different denominators, different questions.

Mention rate is the share of answered runs in which your brand was named. It is answer grain, so an answer naming you three times still counts once.

Being mentioned and being cited are independent. A brand can appear in nearly every relevant answer and be the source of almost none of them. Improving one does not automatically improve the other, which is why they are measured separately.

For Claude Code, Cursor or any agent with a shell, register it with your API key. The --scope user flag makes it available in every project rather than just the current one:

These sign in over OAuth rather than taking a key. Open Settings → Connectors, add a custom connector with the URL below, then click Connect and pick your organization.

The organization is chosen once at consent and fixed for the life of the connection. To reach a second one, add a second connector.

On Team and Enterprise plans an owner has to add the connector at the organization level before members can configure it.

Create a key on the API Keys page. A new key can read and write the whole knowledge base by default.

Keys are accepted three ways so most clients work unchanged: as a Bearer token, as an ApiKey scheme, or as an X-API-Key header. A key is never accepted in the URL, because a key in a path is a key in an access log.

A key’s reach is bounded by its knowledge base permissions, enforced per folder. Scoping a key to viewer on selected folders makes that install read-only and blind to everything else.

A node that does not exist and a node you cannot see return the same message, deliberately, so nobody can probe for what exists.

OAuth connections carry scopes; API keys do not, and are bounded by folder permissions instead.

Senso advertises only kb.read up front, so a fresh connector is read-only. Calling a write tool without the scope returns 403 and the client prompts you to re-authorize.

Deletion is split out from writing on purpose: a connector allowed to add documents should not be able to empty a knowledge base.

Markdown and plain text go in as text, either through the MCP server or the raw content endpoint. Files (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, HTML, CSV, JSON, XML) go through the uploader.

There is no Slack connector or ingest-by-URL endpoint, and in practice you rarely need one. Whatever your agent can already read, whether a Slack thread, a page on your site or a folder in your repo, it can file into Senso in one step.

The MCP server covers ingesting documents, querying the knowledge base, and organizing the tree: folders, tags, versions.

Generating content, the brand kit, content types and publishing are on the CLI and REST API.

Start with MCP: it needs no shell, works in chat assistants as well as coding agents, and is the fastest path from nothing to a working knowledge base. Move to the CLI when you need generation or publishing.

A query accepts a list of content ids and will only consider those documents. Useful when you already know which policy or contract the answer must come from and want to rule out everything else.

To find documents by what they are about, query in content mode first, then restrict a second query to the ids it returned.

The MCP server allows 60 requests per minute per API key, counted across your whole fleet rather than per process.

Exceeding it returns 429 with a Retry-After header.