Knowledge Hub Management APIs - jobs
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 jobs
List jobs with optional filtering.
Each filter accepts one or more values (OR'd within the filter); multiple filters are AND'd together, e.g. ?status=running&status=pending&source_id=X returns jobs for source X that are running OR pending.
Results are scoped to the caller's Boomi tenant via the token's account claim.
Required privileges: KNOWLEDGE_HUB_JOB_READ.
Authorizations:
query Parameters
Array of Source Id (strings) or Source Id (null) (Source Id) Filter by Source ID(s) | |
Array of Knowledge Base Id (strings) or Knowledge Base Id (null) (Knowledge Base Id) Filter by Knowledge Base ID(s) | |
Array of Repository Id (strings) or Repository Id (null) (Repository Id) Filter by repository ID(s) | |
Array of Status (strings) or Status (null) (Status) Filter by status(es) | |
Created After (string) or Created After (null) (Created After) Filter by created at/after (ISO-8601, UTC offset required) | |
Created Before (string) or Created Before (null) (Created Before) Filter by created at/before (ISO-8601, UTC offset required) | |
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 Maximum results to return |
| offset | integer (Offset) >= 0 Default: 0 Pagination offset |
Responses
Response Schema: application/json
required | Array of objects (Jobs) |
| total required | integer (Total) Total number of jobs matching filters |
| limit required | integer (Limit) Limit applied |
| offset required | integer (Offset) Offset applied |
Response samples
- 200
- 422
{- "jobs": [
- {
- "chunks_created": 340,
- "completed_at": "2026-02-01T08:45:00Z",
- "completed_at_ms": 1769935500000,
- "created_at": "2026-02-01T08:30:00Z",
- "created_at_ms": 1769934600000,
- "data_volume": {
- "bytes": 1572864,
- "display": {
- "unit": "MiB",
- "value": 1.5
}
}, - "data_volume_bytes": 1572864,
- "embeddings_generated": 340,
- "job_id": "01920f4a-0000-7000-8000-000000000001",
- "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
- "knowledge_base_name": "HR Policies KB",
- "load_mode": "append",
- "options": { },
- "priority": 5,
- "records_failed": 0,
- "records_processed": 120,
- "records_received": 120,
- "repository_id": "00000000-0000-0000-0000-000000000001",
- "repository_name": "HR Policies",
- "schema_mapping_id": "40000000-0000-0000-0000-000000000001",
- "source_id": "30000000-0000-0000-0000-000000000001",
- "source_name": "HR Jira Issues",
- "started_at": "2026-02-01T08:31:00Z",
- "started_at_ms": 1769934660000,
- "status": "success"
}
], - "limit": 20,
- "offset": 0,
- "total": 1
}Create job
Create an ingestion job.
Called by Data Integration (or any external provider) to create an ingestion job. Creates a job record and queues it for processing. The source must be active, the knowledge base enabled, and the schema mapping active (422 otherwise).
Required privileges: KNOWLEDGE_HUB_JOB_EXECUTE.
Authorizations:
Request Body schema: application/jsonrequired
| schema_mapping_id required | string <uuid> (Schema Mapping Id) Schema Mapping ID that defines the Source→KB relationship |
| storage_type required | string (StorageTypeEnum) Enum: "s3" "gcs" "azure" Storage type: s3, gcs, azure |
required | object (StagedDataRefRequest) Staged data location |
| load_mode required | string (LoadModeEnum) Enum: "append" "overwrite" "merge" Load mode: append, overwrite, or merge |
| priority | integer (Priority) [ 1 .. 10 ] Default: 5 Job priority (1=lowest, 10=highest) |
DocumentFilter (object) or null Filter criteria for selective document processing | |
External Run Id (string) or External Run Id (null) (External Run Id) External run ID for tracking | |
External Provider (string) or External Provider (null) (External Provider) External provider name | |
object (Options) Additional options |
Responses
Request samples
- Payload
{- "external_provider": "rivery",
- "external_run_id": "rivery-12345",
- "load_mode": "append",
- "priority": 5,
- "schema_mapping_id": "40000000-0000-0000-0000-000000000001",
- "staged_data_ref": {
- "bucket": "kh-staging-bucket",
- "prefix": "hr-policies/2026-02/"
}, - "storage_type": "s3"
}Response samples
- 201
{- "job_id": "01920f4a-0000-7000-8000-000000000001",
- "source_id": "30000000-0000-0000-0000-000000000001",
- "status": "pending"
}Get job
Get a job by ID.
Required privileges: KNOWLEDGE_HUB_JOB_READ.
Authorizations:
path Parameters
| job_id required | string <uuid> (Job Id) UUID of the job |
Responses
Response Schema: application/json
| job_id required | string <uuid> (Job Id) Job ID |
| status required | string (JobStatusEnum) Enum: "pending" "running" "success" "failed" "cancelled" "partial" Job status |
| priority required | integer (Priority) Job priority (1=lowest, 10=highest) |
| created_at required | string <date-time> (Created At) Job creation timestamp |
| created_at_ms required | integer (Created At Ms) created_at expressed as UTC epoch milliseconds |
required | Started At Ms (integer) or Started At Ms (null) (Started At Ms) started_at expressed as UTC epoch milliseconds |
required | Completed At Ms (integer) or Completed At Ms (null) (Completed At Ms) completed_at expressed as UTC epoch milliseconds |
Schema Mapping Id (string) or Schema Mapping Id (null) (Schema Mapping Id) Schema Mapping ID used for this job; null if that mapping has since been deleted | |
Source Id (string) or Source Id (null) (Source Id) Source ID derived from schema mapping | |
Source Name (string) or Source Name (null) (Source Name) Source name for display | |
Knowledge Base Id (string) or Knowledge Base Id (null) (Knowledge Base Id) Knowledge Base ID | |
Knowledge Base Name (string) or Knowledge Base Name (null) (Knowledge Base Name) Knowledge Base name for display | |
Repository Id (string) or Repository Id (null) (Repository Id) Repository ID | |
Repository Name (string) or Repository Name (null) (Repository Name) Repository name for display | |
LoadModeEnum (string) or null Load mode the job was created with: append, overwrite, or merge | |
Started At (string) or Started At (null) (Started At) Job start timestamp | |
Completed At (string) or Completed At (null) (Completed At) Job completion timestamp | |
JobProgress (object) or null Detailed progress tracking | |
Records Received (integer) or Records Received (null) (Records Received) Total records received | |
Records Processed (integer) or Records Processed (null) (Records Processed) Records successfully processed | |
Records Failed (integer) or Records Failed (null) (Records Failed) Records that failed processing | |
Chunks Created (integer) or Chunks Created (null) (Chunks Created) Number of chunks created | |
Embeddings Generated (integer) or Embeddings Generated (null) (Embeddings Generated) Number of embeddings generated | |
Data Volume Bytes (integer) or Data Volume Bytes (null) (Data Volume Bytes) Total bytes of source files loaded, exact and never rounded — the canonical value for sorting/export. knowledge-hub-frontend's Activity Log reads this field directly; see data_volume.bytes for the same value paired with its human-readable display. | |
ByteSizeInfo (object) or null data_volume_bytes paired with its human-readable display | |
Array of Errors (objects) or Errors (null) (Errors) Detailed error information | |
External Run Id (string) or External Run Id (null) (External Run Id) External run ID | |
External Provider (string) or External Provider (null) (External Provider) External provider name | |
Options (object) or Options (null) (Options) Additional options | |
Error Message (string) or Error Message (null) (Error Message) Overall job error message |
Response samples
- 200
- 422
{- "chunks_created": 340,
- "completed_at": "2026-02-01T08:45:00Z",
- "completed_at_ms": 1769935500000,
- "created_at": "2026-02-01T08:30:00Z",
- "created_at_ms": 1769934600000,
- "data_volume": {
- "bytes": 1572864,
- "display": {
- "unit": "MiB",
- "value": 1.5
}
}, - "data_volume_bytes": 1572864,
- "embeddings_generated": 340,
- "external_provider": "rivery",
- "external_run_id": "rivery-12345",
- "job_id": "01920f4a-0000-7000-8000-000000000001",
- "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
- "knowledge_base_name": "HR Policies KB",
- "load_mode": "append",
- "options": { },
- "priority": 5,
- "progress": {
- "chunks_generated": 340,
- "embeddings_created": 340,
- "failed_documents": 0,
- "percent_complete": 100,
- "processed_documents": 120,
- "total_documents": 120
}, - "records_failed": 0,
- "records_processed": 120,
- "records_received": 120,
- "repository_id": "00000000-0000-0000-0000-000000000001",
- "repository_name": "HR Policies",
- "schema_mapping_id": "40000000-0000-0000-0000-000000000001",
- "source_id": "30000000-0000-0000-0000-000000000001",
- "source_name": "HR Jira Issues",
- "started_at": "2026-02-01T08:31:00Z",
- "started_at_ms": 1769934660000,
- "status": "success"
}Cancel job
Cancel a pending or running job.
Jobs in terminal states (success, failed, partial, cancelled) cannot be cancelled. Cancellation is cooperative: a RUNNING job stops at the worker's next per-file boundary; a job whose finalize already committed keeps its final status.
Required privileges: KNOWLEDGE_HUB_JOB_DELETE.
Authorizations:
path Parameters
| job_id required | string <uuid> (Job Id) UUID of the job |
Responses
Response Schema: application/json
| job_id required | string <uuid> (Job Id) Job ID |
| status required | string (Status) New job status |
| message required | string (Message) Cancellation message |
Response samples
- 200
- 422
{- "job_id": "01920f4a-0000-7000-8000-000000000001",
- "message": "Cancellation requested",
- "status": "cancelled"
}Get job log
Download a job's ingestion log as CSV (columns: timestamp,level,msg).
Time window is derived from the job's own started_at/completed_at — a still-running job's window extends to "now". A job that hasn't started yet returns an empty log.
Returned as raw text/csv, not a JSON envelope: this is a file download, and
wrapping the CSV text in JSON would double its memory footprint (once raw, once
JSON-escaped) for no benefit. The truncation flag travels as an X-Truncated
header instead of a JSON field.
Required privileges: KNOWLEDGE_HUB_JOB_READ.
Authorizations:
path Parameters
| job_id required | string <uuid> (Job Id) UUID of the job |
Responses
Response Schema:
Response samples
- 200
- 422
null