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.
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.
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.
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.