AI Knowledge

AI Knowledge lets you manage knowledge files through the UI or API and then leverage them in the AI Assistant. By ingesting internal company documents and product resources, GoodData transforms them into searchable knowledge that can be used in natural language interactions.

AI Knowledge supports both organization-level and workspace-level documents. Workspace-level documents are inherited down the workspace hierarchy: a document uploaded to a parent workspace can be used in that workspace and in its child workspaces without being duplicated. Each workspace can still keep its own local documents, and sibling workspaces do not share documents with each other.

What AI Knowledge Does

AI Knowledge helps you ingest documents into a knowledge store, run semantic search over the ingested content, and use the retrieved snippets as input for the AI Assistant.

It currently works with plain-text content provided as:

  • Markdown files
  • Text files

If your source content is stored in another format, extract the text first and convert it to one of the supported formats before ingestion.

How It Works

When users ask questions that relate to organizational knowledge, the AI Assistant searches ingested documents and uses matching content to ground its answers.

What users can expect:

  • When searching from a workspace, the Assistant can use documents from the current workspace, its parent workspaces, and the organization level.
  • More-local documents are prioritized over inherited documents when both are relevant. Organization-level documents remain available across the organization, but workspace-level knowledge that is closer to the user is ranked higher when it matches the question. For example, a document uploaded directly to the current workspace is ranked above a matching document inherited from a parent workspace.
  • Answers include citations such as the document title or filename, and page numbers when available.
  • The AI Assistant only cites documents it actually used.

Permissions

Required permissions:

  • Create, upsert, patch, delete: WRITE_KNOWLEDGE_DOCUMENTS
  • Search, list, get: READ_KNOWLEDGE_DOCUMENTS

These permissions follow the standard workspace permission hierarchy. For example, MANAGE implies write, which implies read.

Users can read inherited documents in a workspace where AI Knowledge is available to them. Inherited documents are read-only from the child workspace: users cannot edit, replace, patch, disable, or delete a document inherited from a parent workspace or from the organization level.

Ingestion

When you ingest a document, GoodData splits the content into chunks, creates embeddings for those chunks, and stores them for retrieval.

Default settings:

  • Chunk size: 1000 characters
  • Chunk overlap: 200 characters
  • Split priority: ## headers, ### headers, #### headers, paragraphs, lines, sentences, words, characters

If you provide pageBoundaries in the request, chunks track which page numbers they span.

Document Scope and Visibility

AI Knowledge can include inherited or local workspace documents. Inherited documents (from parent workspaces or organization-level documents) are read-only and indicate their source level. Organization-level documents are managed from AI Hub.

Workspace-level documents are written at one specific workspace level. They are visible in that workspace and in its child workspaces. For example, if you upload a document to a parent workspace, users in child workspaces can use that document in AI Knowledge search and AI Assistant answers without uploading a separate copy.

Inheritance is always downward. A child workspace does not share its local documents with its parent or with sibling workspaces. This makes AI Knowledge suitable for multi-tenant deployments where a parent workspace provides shared knowledge and each child workspace keeps tenant-specific documents private.

When the AI Assistant searches knowledge from a workspace, it searches the current workspace, its parent workspaces, and organization-level documents. If multiple matching documents are found, more-local knowledge is ranked above inherited knowledge.

Working with Documents

Use the AI Knowledge page in AI Hub to upload and manage organization-level knowledge files.

Upload a Document

  1. Open AI Hub.
  2. In the AI Knowledge tile, click Manage.
  3. Click Upload document.
  4. Select a supported file and complete the upload.

After the upload finishes, the file appears in the list.

Search and Filter Documents

Use the search field to find documents by name. Use the State filter to narrow the list by document state.

Manage Existing Documents

To manage a document, open the … (ellipsis) menu next to the document. Available actions include:

  • Disable to exclude the document from AI Knowledge search without deleting it
  • Delete to remove the document from AI Knowledge

A disabled document remains in the list but is not returned in search results.

To edit, replace, disable, or delete an inherited document, manage it at the level where it was uploaded.

Enable AI Knowledge from AI Hub

If organization-level AI Knowledge is not enabled, the AI Knowledge tile in AI Hub is shown in a disabled state. If you have permission to change the setting, click Enable on the tile to turn on organization-level AI Knowledge. The tile becomes active after the setting is enabled.

Organization-level base path: /api/v1/ai/organization/knowledge

Workspace-level base path: /api/v1/ai/workspaces/{workspace_id}/knowledge

Use the organization-level path to manage documents that should be available across the organization. Use the workspace-level path to manage documents for a specific workspace and its child workspaces.

Create a Document

POST /documents creates a new document. Send the request as multipart/form-data.

Use this operation with either the organization-level base path or the workspace-level base path, depending on where the document should be stored.

Example:

curl -X POST \
  'https://{host}/api/v1/ai/workspaces/{workspace_id}/knowledge/documents' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@my-document.md' \
  -F 'title=My Document Title' \
  -F 'scopes=analytics' \
  -F 'scopes=finance'

Response fields include:

  • id
  • filename
  • success
  • message
  • numChunks

If a document with the same filename already exists, the request returns 409 Conflict.

Upsert a Document

PUT /documents creates the document if it does not exist, or replaces it if a document with the same filename already exists. Send the request as multipart/form-data.

The document is created or replaced only at the level addressed by the API path. The write path does not copy the document into child workspaces. Child workspaces inherit it at query time.

Example:

curl -X PUT \
  'https://{host}/api/v1/ai/workspaces/{workspace_id}/knowledge/documents' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@my-document.md' \
  -F 'title=My Document Title' \
  -F 'scopes=analytics' \
  -F 'scopes=finance'

Response fields include:

  • id
  • filename
  • success
  • message
  • numChunks

List Documents

GET /documents lists documents visible at the requested level. For a workspace, the list can include local workspace documents, inherited documents from parent workspaces, and organization-level documents. It supports cursor-based pagination.

Get, Patch, Delete

  • GET /documents/{document_id} returns document metadata.
  • PATCH /documents/{document_id} updates metadata without re-ingesting content.
  • DELETE /documents/{document_id} deletes the document and its chunks.

Patch and delete operations apply only to documents managed at the requested level. Inherited documents are read-only from child workspaces and must be managed at their source level.

GET /search runs semantic similarity search over document chunks. For workspace searches, it can return results from the current workspace, parent workspaces, and the organization level. Disabled documents are excluded. When matching chunks are found at multiple levels, more-local knowledge is ranked above inherited knowledge.

The API supports:

  • query (required)
  • limit (default 10)
  • minScore (default 0.0)
  • scopes (optional OR-based filtering)

Topic tag filtering using scopes is available through the REST API, but it is not currently used by the Assistant tools.

Persistent Document Storage

AI Knowledge uses persistent storage for document metadata and raw document content.

This improves reliability because the retrieval index is not the only place where documents exist. If the index must be rebuilt, the system can restore documents from persistent storage and index them again.

This means the system can:

  • Recover documents from the persistent store
  • Rechunk and re-index documents without requiring users to upload them again
  • Rebuild the retrieval index after index loss or other maintenance events

Common Use Cases

  • Search internal documentation and policies from the AI Assistant.
  • Help users find the right metric, dashboard, or workflow by searching product documentation.
  • Ground answers in organization processes, playbooks, and other internal knowledge.
  • Share common knowledge from a parent workspace with all child workspaces without duplicating files.
  • Let each child workspace keep its own private knowledge while still inheriting shared guidance from parent workspaces and the organization.
  • Support multi-tenant deployments where a vendor manages shared knowledge centrally and each tenant-facing workspace maintains its own documents.

Current Limitations

The following limitations apply in the current version:

  • Content size limit is about 256 KB per ingestion request.
  • Scope filtering is OR-only when multiple scopes are provided.
  • Search is not paginated. It returns the top results up to the requested limit. Document listing is paginated.
  • Only Markdown and text files are currently supported for ingestion. Support for additional file types may be added in a future release.
  • Topic tag filtering is available through the REST API, but it is not currently used by the Assistant tools.
  • Documents are inherited downward automatically. Excluding a specific parent-workspace document from inheritance is not currently supported.
  • Organizations that opt out of data sharing cannot use AI Knowledge (data_share_opt_out=false).
AI Hub
AI Memory