Knowledge Hub Management APIs - knowledge-bases
UpdatedDownload OpenAPI Specification: Download
For more information about Postman collections, forking, and making your first API call, refer to the Working with Boomi APIs on Postman page.
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:
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
- 200
- 422
{- "knowledge_bases": [
- {
- "collection_name": "hr-policies-kb-1a2b3c4d5e6f",
- "created_at": "2026-01-15T10:30:00Z",
- "default_top_k": 10,
- "description": "HR policies for employee self-service",
- "embedding_model": "cohere.embed-v4:0",
- "field_source_counts": { },
- "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"
}
], - "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:
Request Body schema: application/jsonrequired
| 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
- Payload
{- "default_top_k": 10,
- "description": "HR policies for employee self-service",
- "embedding_model": "cohere.embed-v4:0",
- "kb_schema": {
- "fields": [
- {
- "description": "Owning department",
- "id": "e0010000-0000-4000-8000-000000000001",
- "name": "department",
- "type": "string"
}, - {
- "id": "e0010000-0000-4000-8000-000000000002",
- "name": "effective_date",
- "type": "datetime"
}
]
}, - "name": "HR Policies KB",
- "repository_id": "00000000-0000-0000-0000-000000000001",
- "retrieval_mode": "hybrid"
}Response samples
- 201
- 422
{- "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:
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
- 200
- 422
{- "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": [
- {
- "description": "Owning department",
- "id": "e0010000-0000-4000-8000-000000000001",
- "name": "department",
- "type": "string"
}
]
}, - "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:
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/jsonrequired
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
- Payload
{- "default_top_k": 10,
- "description": "Updated HR policies knowledge base",
- "name": "HR Policies KB 2026",
- "retrieval_mode": "hybrid"
}Response samples
- 200
- 422
{- "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:
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
- 200
- 422
{- "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:
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
- 200
- 422
{- "kb_schema": {
- "fields": [
- {
- "description": "Owning department",
- "id": "e0010000-0000-4000-8000-000000000001",
- "name": "department",
- "type": "string"
}
]
}, - "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:
path Parameters
| knowledge_base_id required | string <uuid> (Knowledge Base Id) UUID of the knowledge base |
Request Body schema: application/jsonrequired
| 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
- Payload
{- "status": "enabled"
}Response samples
- 200
{- "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": [
- {
- "description": "Owning department",
- "id": "e0010000-0000-4000-8000-000000000001",
- "name": "department",
- "type": "string"
}
]
}, - "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:
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
- 200
- 422
{- "limit": 20,
- "offset": 0,
- "sources": [
- {
- "created_at": "2026-01-15T10:30:00Z",
- "file_type": "json",
- "id": "30000000-0000-0000-0000-000000000001",
- "name": "HR Jira Issues",
- "schema_mapping_id": "40000000-0000-0000-0000-000000000001",
- "source_name": "HR Jira",
- "source_schema": {
- "fields": [
- {
- "embeddable": true,
- "metadata_eligible": true,
- "name": "summary",
- "type": "string"
}
]
}, - "source_type": "jira",
- "status": "active",
- "updated_at": "2026-02-01T09:00:00Z"
}
], - "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:
path Parameters
| knowledge_base_id required | string <uuid> (Knowledge Base Id) UUID of the knowledge base |
Request Body schema: application/jsonrequired
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
- Payload
{- "source_name": "HR Jira",
- "source_type": "jira",
- "sources": [
- {
- "file_type": "json",
- "name": "HR Jira Issues",
- "source_schema": {
- "fields": [
- {
- "embeddable": true,
- "metadata_eligible": true,
- "name": "id",
- "type": "string"
}, - {
- "embeddable": true,
- "metadata_eligible": true,
- "name": "summary",
- "type": "string"
}
]
}
}
]
}Response samples
- 201
- 422
{- "schema_mapping_ids": [
- "40000000-0000-0000-0000-000000000001"
], - "source_ids": [
- "30000000-0000-0000-0000-000000000001"
], - "status": "ok"
}