Knowledge API

Use the Knowledge API to manage the same knowledge collections you see in the dashboard: add text, files, and web pages, publish them, and choose which voice agents answer from them. It suits help centers, CMS content, and product data that changes outside Chatbyte.

Create a key with knowledge scopesCopy Anchor Link

An organization Admin or Owner creates the key under Settings → API tokens and chooses its knowledge scopes. Existing keys keep working for the Voice API but have no knowledge access until you create a new key with scopes.

Change and publish each include read. Keep the key on your backend.

How knowledge reaches an agentCopy Anchor Link

1. Sources hold content: text, an uploaded file, or one public web page. Every source belongs to at least one collection.
2. Publishing a collection trains its new or changed sources and creates a release, a frozen copy of the collection.
3. Agents answer from the release they use. Publishing moves every agent that uses the collection to the new release, unless you publish with deploy: "none".

A source shows pending until the next publication trains it. Changing a source never changes what an agent says until you publish.

Add and publish contentCopy Anchor Link

curl https://api.chatbyte.ai/v1/knowledge/sources \
  -H "Authorization: Bearer $CHATBYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "title": "Opening hours",
    "content": "We are open Monday to Friday, 9:00 to 17:00.",
    "collection_ids": ["<collection-id>"],
    "external_id": "cms-page-42"
  }'

curl -X POST https://api.chatbyte.ai/v1/knowledge/collections/<collection-id>/publications \
  -H "Authorization: Bearer $CHATBYTE_API_KEY"

Poll GET /v1/knowledge/collections/{collectionId}/publication until run.status is succeeded. The response's state is published once the collection has no unpublished changes. deployment reports the last time publishing moved the agents that use the collection: failed with a failed_agent_count means some agents still use an older release, and the next publication deploys again.

For files, request an upload URL with POST /v1/knowledge/uploads, PUT the file to the returned upload_url with the returned headers, then create a file source with the upload_id. An upload can be used once and expires after 15 minutes. Sources are limited to 20 MB, and new or replaced content must fit your organization's knowledge capacity.

Sources only cover organization knowledge: files uploaded to a Workbench project are never listed and cannot be added to a collection.

Keep sources in syncCopy Anchor Link

• External IDs link a source to your own record. They are unique in your organization, so a second source with the same external_id is refused with 409; filter with GET /v1/knowledge/sources?external_id=… to find the existing one.
• Replace content with PUT /v1/knowledge/sources/{sourceId}/content. The source keeps its ID and collections. Identical content is ignored (changed: false).
• Refresh a web page source with POST /v1/knowledge/sources/{sourceId}/refresh. The page is fetched again and only changed content creates new work.

Publish afterwards so agents use the new content.

Remove contentCopy Anchor Link

• Removing a source from a collection keeps it in other collections. Agents use it until that collection is published again.
• Deleting a source removes it from every collection and agents stop using it immediately. With the publish scope, each affected collection is republished and its agents move to the new release; otherwise the response lists the collections that still need a publication.
• Archiving a collection is refused while any agent uses it. Deleting an agent stops it from using its collections.

Each collection keeps its latest release, the previous one, and any release an agent still uses. Older releases are retired, which frees their storage.

Choose a voice agent's knowledgeCopy Anchor Link

PUT /v1/voice/agents/{agentId}/knowledge-collections sets exactly which published collections a voice agent uses, each on its latest release. The change is all or nothing: if one collection cannot move, nothing changes and the request answers 409 deployment_conflict; fetch the agent's collections and retry. The response's activation_id tracks the update of the agent's tools; poll GET /v1/agent-tool-activations/{activationId} until its status is completed.

A source can belong to several collections the same agent uses. After its content changes, the agent answers from the newest published version as soon as one of those collections is published.

Limits and errorsCopy Anchor Link

Requests are limited per key; respect Retry-After on 429. Errors return { "error": "<code>", "reason": "…" }; insufficient_scope means the key lacks the scope the operation needs. A Chat AI Agent's primary knowledge (managed_by_agent_id) can only be changed from the dashboard.

The API reference lists every endpoint, field, and error code.