Reviewed knowledge for company agents

Company agents can consult selected entries from the existing organization knowledge store before answering a request. The workspace owner chooses the entries and approves their current revision for private answers or channel answers. This applies to generic agents, including Code Reviewer, as well as the bound Network Doctor profile.

This document describes the implementation and API contract. It does not establish that a particular installation has deployed the change or published any entries.

Publish a reviewed entry #

1. Prepare a concise, nonsecret entry containing the facts or guidance the agent should use. Include the source and observation date in the content where they matter. Review the exact content for its intended audience.

2. Create it through the existing knowledge interface or POST /v1/orgs/:slug/knowledge/entries with the normal authenticated session or organization API key:

   {
     "type": "reference",
     "title": "Reviewed service placement",
     "content": "Service: example service. Placement: approved host and VMID. Source: reviewed inventory. Observed: YYYY-MM-DD. Placement is not live health evidence.",
     "tags": ["company-agent"]
   }

3. Save the returned entry ID. Check the indexing result: 201 indicates completed indexing; 207 with embedding_failed means the entry was saved but indexing failed. The existing POST /v1/orgs/:slug/knowledge/entries/:id/retry endpoint retries failed indexing. Keyword retrieval also needs indexed chunks.

4. As the agent's workspace owner, submit the complete list of approved entries to the grant endpoint below. Read the response back to confirm the entries, audiences, revision hashes and review timestamps.

Creating an organization knowledge entry does not automatically grant a company agent access to it. Conversely, a private-answer grant does not make the underlying entry private: the existing knowledge-store permissions still allow organization members to read organization knowledge. Choose content appropriate for that store.

Owner grant API #

Both routes use the existing company-agent session or organization API-key authentication. The caller must be the current workspace owner with active organization membership. An administrator does not gain grant-management access to another owner's workspace through their role alone.

Example PUT body:

{
  "entries": [
    { "entryId": "reviewed-entry-id", "audience": "channel" },
    { "entryId": "another-reviewed-entry-id", "audience": "private" }
  ]
}

The list accepts at most 20 unique entry IDs from the workspace's organization. Each item contains only entryId and audience. The company-agent publication must already exist. Include every entry that should remain approved; omitted entries are withdrawn. {"entries": []} withdraws all grants.

The response has this shape:

{
  "entries": [
    {
      "entryId": "reviewed-entry-id",
      "audience": "channel",
      "revision": "sha256-of-the-reviewed-revision",
      "reviewedAt": "2026-09-26T10:00:00.000Z",
      "title": "Reviewed service placement"
    }
  ]
}

The server supplies the revision and review timestamp; callers do not choose them. A later GET can return title: null if an approved entry has been deleted.

Private and channel audiences #

A channel grant allows relevant entry content to appear in answers visible to members of the connected channel. Requester identity, company membership, publication and messaging-destination authorization still apply. The model cannot choose another organization, workspace or audience through its prompt.

Revisions, withdrawal and freshness #

Approval pins a SHA-256 hash of the entry's title, content and source URL. Changing any of those values makes the entry ineligible until the owner reviews the new version and submits the list again. Deleting an entry also removes it from retrieval. Search results must match chunks derived from the approved content, so stale indexed chunks cannot replace the text the owner reviewed.

The reader checks selected grants again before model calls and before the answerer returns its result. A withdrawn or changed source detected at either check prevents the answerer from completing that result. Grant checks end when the answerer returns: a later withdrawal does not cancel persistence or channel delivery of that completed result. Previously saved answers and delivered messages are not retracted. Request and messaging authorization checks still apply.

reviewedAt records when the owner granted the current revision. It is not the time a service was observed, nor a guarantee that an inventory fact is still current. Keep observation dates and limitations in the entry itself.

Retrieval and answers #

The server retrieves relevant approved records before the first model response. Search is restricted to the request's organization, workspace grants and audience. It does not depend on the model deciding to call a search tool first. The existing model/input guardrails run before retrieval, including any enforced PII redaction, so the search query follows the same input policy as inference.

Keyword search matches words from the question against approved entries. When a usable embedding is available, vector and keyword results are combined. Missing, null or invalid embeddings, or an embedding/vector-search failure, leave keyword search available. An embedding failure does not grant access to additional entries or trigger an organization-wide search.

Retrieval bounds each query to 1,000 characters and supplies at most five snippets, each with at most 1,200 content characters, within a 6,000-character title/content budget. Returned content is marked as untrusted data; instructions inside an entry do not grant authority or tools.

Answers with retrieved records receive a server-generated Sources consulted: list, with links to the knowledge entries and their review dates. Each entry is listed once. This identifies the material made available to the model; it does not claim every source supports every sentence. No source list is added when no approved records are available. The answer and source list together must fit the existing 8,000-character answer limit and any stricter organization output limit.

Scope #

Each request still starts with empty conversation history. Follow-up Slack mentions do not automatically load earlier thread messages. The service does not learn new persistent facts from replies or synchronize the owner's native sessions, private files, credentials or raw operational archives. Publish reviewed excerpts through the knowledge API.

Knowledge grants do not add live diagnostics. Network Doctor retains its fixed read-only diagnostic operations; other agents do not inherit those operations. An entry can establish recorded placement or review guidance, while current service health requires an actual authorized observation. Infrastructure change proposals continue through the existing owner-decision flow.

See Company agents, Messaging connections, and Network Doctor diagnostic connection.