Knowledge Hub Management APIs - schema-mappings
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.
Get schema mapping
Get schema mapping for a source-to-KB relationship.
Retrieves the field mapping that connects a source to a knowledge base.
Required privileges: KNOWLEDGE_HUB_SSM_READ.
Authorizations:
path Parameters
| source_id required | string <uuid> (Source Id) UUID of the source |
| knowledge_base_id required | string <uuid> (Knowledge Base Id) UUID of the knowledge base |
Responses
Response Schema: application/json
required | Array of objects (Mappings) Field mappings from source to KB schema |
| id required | string <uuid> (Id) |
| source_id required | string <uuid> (Source Id) |
| knowledge_base_id required | string <uuid> (Knowledge Base Id) |
| status required | string (SchemaMappingStatus) Enum: "active" "disabled" Valid statuses for SourceSchemaMapping. |
| created_at required | string <date-time> (Created At) |
| updated_at required | string <date-time> (Updated At) |
ChunkingConfig (object) or null | |
Created By (string) or Created By (null) (Created By) | |
Updated By (string) or Updated By (null) (Updated By) | |
Array of objects (Created Kb Fields) KB schema fields auto-created during a PUT upsert when ensure_target_fields created new fields. Present on all schema-mapping responses (GET, PATCH /status, PUT); always empty except on a PUT upsert that created fields. |
Response samples
- 200
- 422
{- "chunking_config": {
- "chunk_size": 1000,
- "overlap_percent": 10,
- "strategy": "fixed"
}, - "created_at": "2026-01-15T10:30:00Z",
- "created_by": "admin@boomi.com",
- "created_kb_fields": [
- {
- "name": "department",
- "type": "string"
}
], - "id": "40000000-0000-0000-0000-000000000001",
- "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
- "mappings": [
- {
- "query_order": 1,
- "source_field": "summary",
- "target_field": "_content_",
- "target_field_type": "string"
}, - {
- "match_order": 1,
- "source_field": "id",
- "target_field": "id",
- "target_field_type": "string"
}
], - "source_id": "30000000-0000-0000-0000-000000000001",
- "status": "active",
- "updated_at": "2026-02-01T09:00:00Z",
- "updated_by": "admin@boomi.com"
}Upsert schema mapping
Create or update schema mapping for a source-to-KB relationship.
If a mapping exists for this source+KB pair, updates it (200). Otherwise creates a new mapping (201).
Existing mappings must be DISABLED to update.
Required privileges: KNOWLEDGE_HUB_SSM_WRITE.
Authorizations:
path Parameters
| source_id required | string <uuid> (Source Id) UUID of the source |
| knowledge_base_id required | string <uuid> (Knowledge Base Id) UUID of the knowledge base |
Request Body schema: application/jsonrequired
required | Array of objects (Mappings) Field mappings from source to KB schema |
ChunkingConfig (object) or null Configuration for how source text is split into chunks | |
| ensure_target_fields | boolean (Ensure Target Fields) Default: false When true, auto-create any KB schema fields referenced by mappings that do not yet exist on the KB. Creation-only: never mutates existing field types. |
Responses
Response Schema: application/json
required | Array of objects (Mappings) Field mappings from source to KB schema |
| id required | string <uuid> (Id) |
| source_id required | string <uuid> (Source Id) |
| knowledge_base_id required | string <uuid> (Knowledge Base Id) |
| status required | string (SchemaMappingStatus) Enum: "active" "disabled" Valid statuses for SourceSchemaMapping. |
| created_at required | string <date-time> (Created At) |
| updated_at required | string <date-time> (Updated At) |
ChunkingConfig (object) or null | |
Created By (string) or Created By (null) (Created By) | |
Updated By (string) or Updated By (null) (Updated By) | |
Array of objects (Created Kb Fields) KB schema fields auto-created during a PUT upsert when ensure_target_fields created new fields. Present on all schema-mapping responses (GET, PATCH /status, PUT); always empty except on a PUT upsert that created fields. |
Request samples
- Payload
{- "chunking_config": {
- "chunk_size": 1000,
- "overlap_percent": 10,
- "strategy": "fixed"
}, - "ensure_target_fields": true,
- "mappings": [
- {
- "query_order": 1,
- "source_field": "summary",
- "target_field": "_content_",
- "target_field_type": "string"
}, - {
- "match_order": 1,
- "source_field": "id",
- "target_field": "id",
- "target_field_type": "string"
}, - {
- "source_field": "department",
- "target_field": "department",
- "target_field_type": "string"
}
]
}Response samples
- 200
{- "chunking_config": {
- "chunk_size": 1000,
- "overlap_percent": 10,
- "strategy": "fixed"
}, - "created_at": "2026-01-15T10:30:00Z",
- "created_by": "admin@boomi.com",
- "created_kb_fields": [
- {
- "name": "department",
- "type": "string"
}
], - "id": "40000000-0000-0000-0000-000000000001",
- "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
- "mappings": [
- {
- "query_order": 1,
- "source_field": "summary",
- "target_field": "_content_",
- "target_field_type": "string"
}, - {
- "match_order": 1,
- "source_field": "id",
- "target_field": "id",
- "target_field_type": "string"
}
], - "source_id": "30000000-0000-0000-0000-000000000001",
- "status": "active",
- "updated_at": "2026-02-01T09:00:00Z",
- "updated_by": "admin@boomi.com"
}Delete schema mapping
Delete schema mapping for a source-to-KB relationship.
Removes the field mapping that connects a source to a knowledge base. This is a hard delete of the mapping only — the source and knowledge base are untouched.
Required privileges: KNOWLEDGE_HUB_SSM_DELETE.
Authorizations:
path Parameters
| source_id required | string <uuid> (Source Id) UUID of the source |
| knowledge_base_id required | string <uuid> (Knowledge Base Id) UUID of the knowledge base |
Responses
Response samples
- 422
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string"
}
]
}Update schema mapping status
Transition a schema mapping's status.
Valid transitions:
- ACTIVE -> DISABLED
- DISABLED -> ACTIVE
Activation is blocked (422) if the mapping references knowledge base fields that no longer exist.
Required privileges: KNOWLEDGE_HUB_SSM_WRITE.
Authorizations:
path Parameters
| source_id required | string <uuid> (Source Id) UUID of the source |
| knowledge_base_id required | string <uuid> (Knowledge Base Id) UUID of the knowledge base |
Request Body schema: application/jsonrequired
| status required | string (SchemaMappingStatus) Enum: "active" "disabled" Target status for the schema mapping |
Responses
Response Schema: application/json
required | Array of objects (Mappings) Field mappings from source to KB schema |
| id required | string <uuid> (Id) |
| source_id required | string <uuid> (Source Id) |
| knowledge_base_id required | string <uuid> (Knowledge Base Id) |
| status required | string (SchemaMappingStatus) Enum: "active" "disabled" Valid statuses for SourceSchemaMapping. |
| created_at required | string <date-time> (Created At) |
| updated_at required | string <date-time> (Updated At) |
ChunkingConfig (object) or null | |
Created By (string) or Created By (null) (Created By) | |
Updated By (string) or Updated By (null) (Updated By) | |
Array of objects (Created Kb Fields) KB schema fields auto-created during a PUT upsert when ensure_target_fields created new fields. Present on all schema-mapping responses (GET, PATCH /status, PUT); always empty except on a PUT upsert that created fields. |
Request samples
- Payload
{- "status": "active"
}Response samples
- 200
{- "chunking_config": {
- "chunk_size": 1000,
- "overlap_percent": 10,
- "strategy": "fixed"
}, - "created_at": "2026-01-15T10:30:00Z",
- "created_by": "admin@boomi.com",
- "created_kb_fields": [
- {
- "name": "department",
- "type": "string"
}
], - "id": "40000000-0000-0000-0000-000000000001",
- "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
- "mappings": [
- {
- "query_order": 1,
- "source_field": "summary",
- "target_field": "_content_",
- "target_field_type": "string"
}, - {
- "match_order": 1,
- "source_field": "id",
- "target_field": "id",
- "target_field_type": "string"
}
], - "source_id": "30000000-0000-0000-0000-000000000001",
- "status": "active",
- "updated_at": "2026-02-01T09:00:00Z",
- "updated_by": "admin@boomi.com"
}Suggest schema mapping
Suggest a schema mapping for a source-to-KB relationship. Read-only; writes nothing.
If the response's would_create_kb_fields is non-empty, the subsequent PUT must set ensure_target_fields=true for those fields to actually be created.
Fields are skipped (reported unmapped with a reason) if they are:
- id-like (name ends in 'id'/'_id'/'ids', other than the match key 'id'): 'excluded_field'
- malformed schema entries: 'malformed_field'
(Both checked after type resolution and case-fold collision detection, so either of those can report its own reason first.)
If the source has 10 or more fields, only fields matching common patterns are kept: strings like status/stage/type/category/priority/owner/assignee/author/created_by, and datetimes like created/updated/modified. Others are reported as 'no_pattern_match'.
At most 20 fields are mapped or created; extras are reported as 'suggestion_limit_exceeded'. The id, content, description, and title fields are always kept, regardless of pattern or cap.
A mapping that would need a new KB field is reported unmapped as 'kb_not_editable' instead of would_create_kb_fields when the KB isn't draft or disabled.
Required privileges: KNOWLEDGE_HUB_SSM_READ.
Authorizations:
path Parameters
| source_id required | string <uuid> (Source Id) UUID of the source |
| knowledge_base_id required | string <uuid> (Knowledge Base Id) UUID of the knowledge base |
Responses
Response Schema: application/json
Array of objects (Mappings) | |
Array of objects (Would Create Kb Fields) If non-empty, the subsequent PUT must set ensure_target_fields=true for those fields to actually be created. | |
Array of objects (Unmapped) |
Response samples
- 200
- 422
{- "mappings": [
- {
- "query_order": 1,
- "source_field": "summary",
- "target_field": "_content_",
- "target_field_type": "string"
}, - {
- "match_order": 1,
- "source_field": "id",
- "target_field": "id",
- "target_field_type": "string"
}
], - "unmapped": [
- {
- "reason": "excluded_field",
- "source_field": "creator_id"
}
], - "would_create_kb_fields": [
- {
- "name": "department",
- "type": "string"
}
]
}