Waiting for engine...
Skip to main content

Knowledge Hub Management APIs - jobs

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.

jobs

Create and monitor ingestion jobs

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:
HTTPBearer
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

Content type
application/json
{
  • "jobs": [
    • {
      }
    ],
  • "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:
HTTPBearer
Request Body schema: application/json
required
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

Content type
application/json
{
  • "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

Content type
application/json
{
  • "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:
HTTPBearer
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

Content type
application/json
{
  • "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": {
      }
    },
  • "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:
HTTPBearer
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

Content type
application/json
{
  • "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:
HTTPBearer
path Parameters
job_id
required
string <uuid> (Job Id)

UUID of the job

Responses

Response Schema:
any

Response samples

Content type
null