Waiting for engine...
Skip to main content

Knowledge Hub Management APIs - knowledge-bases

Updated 
Toggle Pane

Download OpenAPI Specification: Download

Run In Postman

For more information about Postman collections, forking, and making your first API call, refer to the Working with Boomi APIs on Postman page.

knowledge-bases

Knowledge Base management

List knowledge bases

List knowledge bases with optional filtering.

Returns list of knowledge bases with pagination and optional filtering by repository and status. Archived knowledge bases are excluded unless explicitly requested via the status filter. Results are scoped to the caller's Boomi tenant via the token's account claim.

Required privileges: KNOWLEDGE_HUB_KB_LIST.

Authorizations:
HTTPBearer
query Parameters
limit
integer (Limit) [ 1 .. 1000 ]
Default: 50

Maximum results to return

offset
integer (Offset) >= 0
Default: 0

Pagination offset

Repository Id (string) or Repository Id (null) (Repository Id)

Filter by repository

KnowledgeBaseStatus (string) or Status (null) (Status)

Filter by status

Name (string) or Name (null) (Name)

Filter by knowledge base name

Responses

Response Schema: application/json
total
required
integer (Total)

Total number of items matching filters

limit
required
integer (Limit)

Limit applied

offset
required
integer (Offset)

Offset applied

required
Array of objects (Knowledge Bases)

Response samples

Content type
application/json
{
  • "knowledge_bases": [
    • {
      }
    ],
  • "limit": 20,
  • "offset": 0,
  • "total": 1
}

Create knowledge base

Create a new knowledge base.

Creates a knowledge base with the given configuration. Status is automatically set to 'draft' on creation.

If collection_name is not provided, it is auto-generated from the KB name. A provided collection_name is used as the base; either way a unique suffix derived from the KB id is appended so no two KBs share a vector index. If kb_schema is not provided, an empty metadata schema is created.

Required privileges: KNOWLEDGE_HUB_KB_CREATE.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
description
required
string (Description) [ 1 .. 1000 ] characters
repository_id
required
string <uuid> (Repository Id)
embedding_model
string (Embedding Model)
Default: "cohere.embed-v4:0"

Embedding model ID

retrieval_mode
string (RetrievalMode)
Default: "hybrid"
Enum: "semantic" "lexical" "hybrid"

Valid retrieval modes for KnowledgeBase.

default_top_k
integer (Default Top K)
Default: 10
Collection Name (string) or Collection Name (null) (Collection Name)

Vector store collection name. Auto-generated from name if not provided

KbSchema (object) or null

Metadata field definitions for this knowledge base. Each field describes a metadata key stored in the vector document. If not provided, an empty schema is created (no metadata fields).

Retrieval Config (object) or Retrieval Config (null) (Retrieval Config)

Responses

Request samples

Content type
application/json
{
  • "default_top_k": 10,
  • "description": "HR policies for employee self-service",
  • "embedding_model": "cohere.embed-v4:0",
  • "kb_schema": {
    • "fields": [
      ]
    },
  • "name": "HR Policies KB",
  • "repository_id": "00000000-0000-0000-0000-000000000001",
  • "retrieval_mode": "hybrid"
}

Response samples

Content type
application/json
{
  • "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
  • "status": "ok"
}

Get knowledge base

Get a knowledge base by ID.

Includes the live source count, per-field source counts, and the resolved embedding model details.

Required privileges: KNOWLEDGE_HUB_KB_READ.

Authorizations:
HTTPBearer
path Parameters
knowledge_base_id
required
string <uuid> (Knowledge Base Id)

UUID of the knowledge base

Responses

Response Schema: application/json
name
required
string (Name) [ 1 .. 255 ] characters
description
required
string (Description) [ 1 .. 1000 ] characters
id
required
string <uuid> (Id)
repository_id
required
string <uuid> (Repository Id)
collection_name
required
string (Collection Name)
required
object (KbSchema)

Knowledge base metadata schema defining user-facing fields.

status
required
string (KnowledgeBaseStatus)
Enum: "enabled" "archived" "draft" "disabled"

Valid statuses for KnowledgeBase.

created_at
required
string <date-time> (Created At)
updated_at
required
string <date-time> (Updated At)
embedding_model
string (Embedding Model)
Default: "cohere.embed-v4:0"

Embedding model ID

retrieval_mode
string (RetrievalMode)
Default: "hybrid"
Enum: "semantic" "lexical" "hybrid"

Valid retrieval modes for KnowledgeBase.

default_top_k
integer (Default Top K)
Default: 10
Embedding Model Name (string) or Embedding Model Name (null) (Embedding Model Name)

Display name of the embedding model.

Embedding Model Provider (string) or Embedding Model Provider (null) (Embedding Model Provider)

Provider/routing key for the embedding model.

Retrieval Config (object) or Retrieval Config (null) (Retrieval Config)
source_count
integer (Source Count)
Default: 0
object (Field Source Counts)
Created By (string) or Created By (null) (Created By)
Updated By (string) or Updated By (null) (Updated By)

Response samples

Content type
application/json
{
  • "collection_name": "hr-policies-kb-1a2b3c4d5e6f",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "admin@boomi.com",
  • "default_top_k": 10,
  • "description": "HR policies for employee self-service",
  • "embedding_model": "cohere.embed-v4:0",
  • "embedding_model_name": "Cohere Embed v4",
  • "embedding_model_provider": "bedrock",
  • "field_source_counts": {
    • "department": 1
    },
  • "id": "10000000-0000-0000-0000-000000000001",
  • "kb_schema": {
    • "fields": [
      ]
    },
  • "name": "HR Policies KB",
  • "repository_id": "00000000-0000-0000-0000-000000000001",
  • "retrieval_mode": "hybrid",
  • "source_count": 1,
  • "status": "enabled",
  • "updated_at": "2026-02-01T09:00:00Z",
  • "updated_by": "admin@boomi.com"
}

Update knowledge base

Update a knowledge base.

When kb_schema is provided, detects field renames and deletions using stable field IDs. Renames cascade to mapping target_fields. Deletions remove affected FieldMapping entries and disable affected sources and their mappings. Blocked (409) if PENDING/RUNNING jobs exist, or if a field type changes on a KB with ingest history (schema_type_immutable).

When dry_run=true, runs the cascade inside a savepoint and rolls back, returning the cascade summary without persisting any changes.

Required privileges: KNOWLEDGE_HUB_KB_WRITE.

Authorizations:
HTTPBearer
path Parameters
knowledge_base_id
required
string <uuid> (Knowledge Base Id)

UUID of the knowledge base

query Parameters
dry_run
boolean (Dry Run)
Default: false

Preview cascade effects without applying changes

Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
RetrievalMode (string) or null
Default Top K (integer) or Default Top K (null) (Default Top K)
Retrieval Config (object) or Retrieval Config (null) (Retrieval Config)
KbSchema (object) or null

Full replacement of the metadata field definitions. Fields not included will be removed.

Responses

Response Schema: application/json
status
string (Status)
Default: "ok"
CascadeSummary (object) or null

Request samples

Content type
application/json
{
  • "default_top_k": 10,
  • "description": "Updated HR policies knowledge base",
  • "name": "HR Policies KB 2026",
  • "retrieval_mode": "hybrid"
}

Response samples

Content type
application/json
{
  • "cascade": {
    • "disabled_source_names": [ ],
    • "fields_deleted": 0,
    • "fields_renamed": 1,
    • "mappings_cleaned": 0,
    • "mappings_updated": 1,
    • "sources_disabled": 0
    },
  • "status": "ok"
}

Delete knowledge base

Archive a knowledge base (soft delete).

Sets status to 'archived'. If purge_data=true, also schedules the KB's vector index for deletion after a grace window — the index itself is never touched here; the background sweep deletes it once the grace period elapses.

Required privileges: KNOWLEDGE_HUB_KB_DELETE.

Authorizations:
HTTPBearer
path Parameters
knowledge_base_id
required
string <uuid> (Knowledge Base Id)

UUID of the knowledge base

query Parameters
purge_data
boolean (Purge Data)
Default: false

If true, schedules the KB's index for deferred deletion (index_deletion_due_at = now + INDEX_DELETION_GRACE_HOURS) — never deletes it directly

Responses

Response Schema: application/json
knowledge_base_id
required
string <uuid> (Knowledge Base Id)
status
string (Status)
Default: "ok"
archived_sources
integer (Archived Sources)
Default: 0
embeddings_purged
boolean (Embeddings Purged)
Default: false

Mirrors purge_data ('scheduled' semantics): True means the index deletion was scheduled (index_deletion_due_at stamped; the worker sweep performs the actual delete after the grace window), not that it already happened. False when purge_data was false.

Index Deletion Due At (string) or Index Deletion Due At (null) (Index Deletion Due At)

UTC timestamp when the KB's index becomes eligible for deletion by the worker sweep. Set only when purge_data=true; None otherwise.

Response samples

Content type
application/json
{
  • "archived_sources": 0,
  • "embeddings_purged": true,
  • "index_deletion_due_at": "2026-02-08T09:00:00Z",
  • "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
  • "status": "ok"
}

Get knowledge base schema

Get only a knowledge base's metadata schema.

Returns the schema alone, without the config payload the full GET carries — the minimal surface retrieval-side consumers need.

Required privileges: KNOWLEDGE_HUB_KB_SCHEMA_READ.

Authorizations:
HTTPBearer
path Parameters
knowledge_base_id
required
string <uuid> (Knowledge Base Id)

UUID of the knowledge base

Responses

Response Schema: application/json
knowledge_base_id
required
string <uuid> (Knowledge Base Id)
required
object (KbSchema)

Knowledge base metadata schema defining user-facing fields.

Response samples

Content type
application/json
{
  • "kb_schema": {
    • "fields": [
      ]
    },
  • "knowledge_base_id": "10000000-0000-0000-0000-000000000001"
}

Update knowledge base status

Transition a knowledge base's status.

Valid transitions:

  • DRAFT -> ENABLED (requires repo available + at least one active source)
  • ENABLED -> DISABLED (takes the KB out of service; no preconditions)
  • DISABLED -> ENABLED (same preconditions as DRAFT -> ENABLED)

A disabled KB is rejected by retrieval (403 kb_inactive) and by job creation (422 invalid_state), but stays listable and editable. Jobs already enqueued when the KB is disabled are not cancelled.

To archive a KB, use DELETE /knowledge-bases/{id} instead.

Required privileges: KNOWLEDGE_HUB_KB_WRITE.

Authorizations:
HTTPBearer
path Parameters
knowledge_base_id
required
string <uuid> (Knowledge Base Id)

UUID of the knowledge base

Request Body schema: application/json
required
status
required
string (KnowledgeBaseStatus)
Enum: "enabled" "archived" "draft" "disabled"

Target status for the knowledge base

Responses

Response Schema: application/json
name
required
string (Name) [ 1 .. 255 ] characters
description
required
string (Description) [ 1 .. 1000 ] characters
id
required
string <uuid> (Id)
repository_id
required
string <uuid> (Repository Id)
collection_name
required
string (Collection Name)
required
object (KbSchema)

Knowledge base metadata schema defining user-facing fields.

status
required
string (KnowledgeBaseStatus)
Enum: "enabled" "archived" "draft" "disabled"

Valid statuses for KnowledgeBase.

created_at
required
string <date-time> (Created At)
updated_at
required
string <date-time> (Updated At)
embedding_model
string (Embedding Model)
Default: "cohere.embed-v4:0"

Embedding model ID

retrieval_mode
string (RetrievalMode)
Default: "hybrid"
Enum: "semantic" "lexical" "hybrid"

Valid retrieval modes for KnowledgeBase.

default_top_k
integer (Default Top K)
Default: 10
Embedding Model Name (string) or Embedding Model Name (null) (Embedding Model Name)

Display name of the embedding model.

Embedding Model Provider (string) or Embedding Model Provider (null) (Embedding Model Provider)

Provider/routing key for the embedding model.

Retrieval Config (object) or Retrieval Config (null) (Retrieval Config)
source_count
integer (Source Count)
Default: 0
object (Field Source Counts)
Created By (string) or Created By (null) (Created By)
Updated By (string) or Updated By (null) (Updated By)

Request samples

Content type
application/json
{
  • "status": "enabled"
}

Response samples

Content type
application/json
{
  • "collection_name": "hr-policies-kb-1a2b3c4d5e6f",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "admin@boomi.com",
  • "default_top_k": 10,
  • "description": "HR policies for employee self-service",
  • "embedding_model": "cohere.embed-v4:0",
  • "embedding_model_name": "Cohere Embed v4",
  • "embedding_model_provider": "bedrock",
  • "field_source_counts": {
    • "department": 1
    },
  • "id": "10000000-0000-0000-0000-000000000001",
  • "kb_schema": {
    • "fields": [
      ]
    },
  • "name": "HR Policies KB",
  • "repository_id": "00000000-0000-0000-0000-000000000001",
  • "retrieval_mode": "hybrid",
  • "source_count": 1,
  • "status": "enabled",
  • "updated_at": "2026-02-01T09:00:00Z",
  • "updated_by": "admin@boomi.com"
}

List sources for knowledge base

List sources connected to a knowledge base via schema mappings.

Returns sources that have a schema mapping to this KB, excluding archived sources. Each source includes its schema_mapping_id for use in job creation.

Required privileges: KNOWLEDGE_HUB_SOURCE_READ.

Authorizations:
HTTPBearer
path Parameters
knowledge_base_id
required
string <uuid> (Knowledge Base Id)

UUID of the knowledge base

query Parameters
limit
integer (Limit) [ 1 .. 1000 ]
Default: 50

Maximum results to return

offset
integer (Offset) >= 0
Default: 0

Pagination offset

Responses

Response Schema: application/json
total
required
integer (Total)

Total number of items matching filters

limit
required
integer (Limit)

Limit applied

offset
required
integer (Offset)

Offset applied

required
Array of objects (Sources)

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "sources": [
    • {
      }
    ],
  • "total": 1
}

Create source for knowledge base

Create sources directly inside a knowledge base.

Each source is created already linked to this KB through a DISABLED schema mapping — atomic: a failure leaves no unassociated source behind.

An unstructured source (is_unstructured true, or a known unstructured file type) may be created with an empty source_schema; kh-api stores the fixed worker field list plus _content_ — same contract as POST /sources.

Required privileges: KNOWLEDGE_HUB_SOURCE_WRITE.

Authorizations:
HTTPBearer
path Parameters
knowledge_base_id
required
string <uuid> (Knowledge Base Id)

UUID of the knowledge base

Request Body schema: application/json
required
required
Array of objects (Sources) non-empty

Array of sources to create

Source Type (string) or Source Type (null) (Source Type)

Type of source (e.g., jira, salesforce)

Source Name (string) or Source Name (null) (Source Name)

Display name for the source

Source Metadata (object) or Source Metadata (null) (Source Metadata)

Opaque JSON blob for source-specific metadata

Responses

Request samples

Content type
application/json
{
  • "source_name": "HR Jira",
  • "source_type": "jira",
  • "sources": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "schema_mapping_ids": [
    • "40000000-0000-0000-0000-000000000001"
    ],
  • "source_ids": [
    • "30000000-0000-0000-0000-000000000001"
    ],
  • "status": "ok"
}