Skip to main content

Ingesting a File With API

This guide provides detail of the request to upload a file using the Koverse API

After reading this guide the reader should understand the fields of the request body for uploads the options for configuration and how to use the response body to check the Ingest Job status.

Requirements needed for completion of this guide​

  • An existing koverse workspace
  • An existing koverse dataset (in workspace)

The POST to the uploads endpoint is a multi-part form-data request.

Postman Instructions:
From Body selection under the POST - select form-data.
Hover over the right side of the files Key box and select 'files' instead of 'text'.
It will then give a button in value to click to select your file for upload.

Form Data Uploads

See the uploads API documentation Create Upload

DatasetId is a required field in the form-data

Optional Fields​

AccessControlLabel​

The purpose of the Access Control Label is to define which attribute parser will be used by the ingest job to create the records security_label for ABAC access control.

Security Label Info

simple-parser​

The simple parser uses a field from your record to use as the security_label for the record.

For example when ingesting a csv file with the following 

id,label  
1,high  
2,low

The label field can be configured for ABAC use
by setting accessControlLabel in the form-data with value

{
  securityLabeled: true,
  securityLabelInfo: {
    fields: ["label"],
    parserClassName: "simple-parser"
  }
}
identity-parser​

The identity parser uses a field from your record to use as the expression for security_label for the record.

For example when ingesting a csv file with the following

id,label  
1,high&medium  
2,low&open

The label field can be configured for ABAC use
by setting accessControlLabel in the form-data with value

{
  securityLabeled: true,
  securityLabelInfo: {
    fields: ["label"],
    parserClassName: "identity-parser"
  }
}

Label expressions can use the operators 

& | ( )

Examples of valid expressions

high&medium
high&(medium|low)
high|(medium&low)
高的|(medium&low)

Any UTF-8 character can be used in the attribute term example - term high could also be 高的 (high in chinese)
Usage of any of the expression separators in a term

& | ( )

must be escaped with a backslash

hi\&gh

would become the attribute "hi\&gh"

Both parsers offer labelHandlingPolicy as a configuration
The label handling policy tells the parser what to do if the value in the row is missing.

Example for csv:

id,label  
1,high  
2,low  
3,
labelHandlingPolicy Setting Options​

'ignore' setting would insert the row without a security_label (open access)

'replace' setting would take the value in 'replacementString' to be the value

'drop' setting would not ingest the row with the missing value, and the row would not be added to the dataset.

Custom Metadata​

User provided metadata that will be added to the ingested record (for document uploads)

The value should be provided in json string format

Example the json object

{ 
  "key": "value",
  "createdDt": "05/10/2025"
}

should be provided in the format

{
  ... 
  "customMetadata": "{\"key\":\"value\",\"createdDt\":\"05/10/2025\"}"
}

On a successful post (201 created response code), the response body will include the jobId field.
The jobId can be used to return the job, Retrieve Job with the given ID The Job includes a status field. img.png

Preliminary status updates include queued when the Job is pending processing and running when the Job is in progress.

A successful ingest Job will result in the status being updated to complete.

If an ingest job fails the status will be updated to failed, more information about a failure may be available on the Job error field.