Import Knowledge

POST /knowledge-bases/{kb_id}/import

Record the job and return it queued. The ingest loop does the work.

202 rather than 201: nothing has been imported yet, and answering 201 with a finished-looking body is how a caller concludes the import failed silently when the counts are still zero a second later. RULE IJ-1 is why the work is not done inline — a crashed inline import would leave a running row nothing may reclaim.

Role floor

Requires admin or above. The floor is a minimum, not a grant: scope filtering still applies on top of it, and a resource in another tenant answers 404 rather than 403.

Parameters

Name	In	Type		Notes
kb_id	path	string (uuid)	required	—

Request body — KnowledgeImportRequest

Field	Type		Notes
mode	verbatim | analyzed	optional	Default "verbatim".
source_format	csv | markdown | items | document | url	optional	Default "items".
object_key	string | null	optional	max length 1024
source_url	string | null	optional	max length 2000
source_filename	string | null	optional	max length 400
items	string[] | null	optional	—
content	string | null	optional	min length 1 max length 1000000

Responses

Status	Description	Body
202	Successful Response	IngestJobView
422	Validation Error	HTTPValidationError

Only the success paths are declared

Any operation may also answer any status in the error catalogue, and every failure body is the platform envelope — including the 422 this document types as HTTPValidationError.

Example

The body shows the fields the schema always carries. Which combination is legal is a service rule the schema cannot express, so read the description above before copying this.

curl -X POST https://your-deployment.example.com/knowledge-bases/{kb_id}/import \
  -H "Authorization: Bearer $COBRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "mode": "verbatim",
       "source_format": "csv"
     }'

Response — IngestJobView

Field	Type		Notes
id	string (uuid)	required	—
kb_id	string (uuid)	required	—
status	queued | running | succeeded | failed | cancelled	required	—
stage	analyzing | embedding | null	optional	—
mode	verbatim | analyzed	required	—
source_format	csv | markdown | items | document | url	required	—
source_filename	string | null	optional	—
source_url	string | null	optional	—
total_items	integer	optional	Default 0.
processed_items	integer	optional	Default 0.
created_items	integer	optional	Default 0.
skipped	IngestSkip[]	optional	—
analyzer_run_id	string (uuid) | null	optional	—
tokens_input	integer	optional	Default 0.
tokens_output	integer	optional	Default 0.
cost	string	optional	Default "0".
error_message	string | null	optional	—
started_at	string (date-time) | null	optional	—
finished_at	string (date-time) | null	optional	—
created_at	string (date-time)	required	—