Skip to main content

Knowledge access API

The agent configuration's knowledgeAccess field defines which collections and documents a voice or chat agent can use through the public agent API.

Breaking change: collection-based access​

important

The knowledgeAccess shape changed in place on /public/v1/agents, including agent creation and updates through PUT /public/v1/agents/:id. The URL still uses v1, but writes using the old flat includedLabelIds and includedDocumentIds shape are rejected. Update your client before writing agent configurations.

The required shape is now { format: 'collections', collections: [...], excludedDocumentIds: [...] }. Labels and individual documents must be grouped under their collection. Do not send old include fields alongside the new format, and do not assume that an empty selection means access to the entire library.

Read the agent's current saved configuration before updating it. Preserve its converted collection assignments, or choose the intended collections in Studio. Refresh generated client types and cached configuration objects. If you build the new shape yourself, resolve each selected document to its actual collection and explicitly choose the collections in which a label should grant access. Copying a formerly global label selection into every collection can grant more access than intended.

Configuration fields​

Set useKnowledgeDocuments to true to enable retrieval. Set knowledgeAccess inside the agent's config, alongside its other configuration fields.

FieldAccepted valueMeaning
format"collections"Identifies the collection-based format.
collectionsArray of collection grantsThe collections assigned to this agent. Each collection appears at most once.
collections[].collectionIdCollection UUIDThe collection containing the permitted documents.
collections[].scope"all" or "only"All current and future documents, or only selected labels/documents.
collections[].labelIdsArray of label UUIDsWith only, admits documents carrying any of these labels within this collection. Empty for all.
collections[].documentIdsArray of document UUIDsWith only, also admits these individual documents in this collection. Empty for all.
excludedDocumentIdsArray of document UUIDsAgent-wide exclusions that override every grant.

These are configuration excerpts, not complete create or update requests. Replace the example UUIDs with IDs from your tenant and include the other fields required by your agent configuration.

All documents from a collection​

{
  "useKnowledgeDocuments": true,
  "knowledgeAccess": {
    "format": "collections",
    "collections": [
      {
        "collectionId": "11111111-1111-4111-8111-111111111111",
        "scope": "all",
        "labelIds": [],
        "documentIds": []
      }
    ],
    "excludedDocumentIds": []
  }
}

Selected labels and documents, with an exclusion​

{
  "useKnowledgeDocuments": true,
  "knowledgeAccess": {
    "format": "collections",
    "collections": [
      {
        "collectionId": "11111111-1111-4111-8111-111111111111",
        "scope": "only",
        "labelIds": ["22222222-2222-4222-8222-222222222222"],
        "documentIds": ["33333333-3333-4333-8333-333333333333"]
      }
    ],
    "excludedDocumentIds": ["44444444-4444-4444-8444-444444444444"]
  }
}

A document matches either the selected label or the individual document list, but must belong to the assigned collection. The exclusion still wins if that document otherwise matches.

Empty selections and state settings​

An empty collections array grants no access. An only grant with empty label and document lists grants nothing from that collection. To intentionally disable knowledge, set useKnowledgeDocuments to false; do not enable knowledge with an empty scope. New saves require a usable selection when enabling knowledge.

State knowledge remains in each state's knowledge field. prefetchedLabelIds and prefetchedDocumentIds map to Listed up front. An omitted searchableOverride inherits the agent scope. An override with empty collectionIds, labelIds and documentIds maps to No search; nonempty lists map to Only selected.

See the shared state knowledge rules for strict state separation, listing limits and access to previously returned documents.

Next steps​