Configuration | Umnai | Documentation

An onboarding configuration defines how a datasource becomes a dataset.

It contains the modelling and preprocessing choices used during onboarding, including the prediction type, target, feature groups, categorical handling, missing-value handling, encoding behaviour, and sharding.

Initial and incremental configurations

Onboarding configurations are created as either INITIAL or INCREMENT.

An initial configuration is used when creating a new dataset. It includes the prediction type and the target field for the model.

POST

/data-processing-onboarding-configurations

1 curl -X POST https://api.hi.umnai.com/data-processing-onboarding-configurations \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "configuration_type": "INITIAL",
6   "prediction_type": "CLASSIFICATION",
7   "encoding_strategy": "STREAM",
8   "handle_unseen_categories": true,
9   "impute": false,
10   "one_hot_encoding_max_categories": 64,
11   "strip_categories": true,
12   "targets": [
13     "target_column"
14   ],
15   "name": "Sample Initial Onboarding Configuration"
16 }'

Response

1 {
2   "configuration_type": "INITIAL",
3   "encoding_strategy": "STREAM",
4   "feature_groups": [],
5   "handle_unseen_categories": true,
6   "impute": false,
7   "infrequency_threshold": 1,
8   "mask_category_fraction": 0.37,
9   "mask_fraction": 0.8,
10   "mask_median_fraction": 0.15,
11   "mask_rows_fraction": 0.3,
12   "one_hot_encoding_max_categories": 64,
13   "prediction_type": "CLASSIFICATION",
14   "sharding_strategy": "PROPORTIONATE",
15   "shards": "256m",
16   "strip_categories": true,
17   "targets": [
18     "target_column"
19   ],
20   "id": "2df5b9fdb3389598e304f661315ebec8",
21   "name": "Sample Initial Onboarding Configuration",
22   "account": {
23     "id": "e268443e43d93dab7ebef303bbe9642f",
24     "name": "Sample Account"
25   },
26   "created_at": "2026-03-15T10:15:30.000000Z",
27   "created_by": {
28     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
29     "name": "Sample User"
30   },
31   "updated_at": "2026-03-15T10:15:30.000000Z"
32 }

An incremental configuration is used when updating an existing dataset. It keeps the same dataset context and can adjust onboarding behaviour for the update.

POST

/data-processing-onboarding-configurations

1 curl -X POST https://api.hi.umnai.com/data-processing-onboarding-configurations \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "configuration_type": "INCREMENT",
6   "encoding_strategy": "STREAM",
7   "handle_unseen_categories": true,
8   "impute": false,
9   "strip_categories": true,
10   "name": "Sample Incremental Onboarding Configuration"
11 }'

Response

1 {
2   "configuration_type": "INCREMENT",
3   "encoding_strategy": "STREAM",
4   "handle_unseen_categories": true,
5   "impute": false,
6   "mask_category_fraction": 0.37,
7   "mask_fraction": 0.8,
8   "mask_median_fraction": 0.15,
9   "mask_rows_fraction": 0.3,
10   "strip_categories": true,
11   "id": "5d5d9b3e708a4f0194b647e6df912c32",
12   "name": "Sample Incremental Onboarding Configuration",
13   "account": {
14     "id": "e268443e43d93dab7ebef303bbe9642f",
15     "name": "Sample Account"
16   },
17   "created_at": "2026-03-16T10:15:30.000000Z",
18   "created_by": {
19     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
20     "name": "Sample User"
21   },
22   "updated_at": "2026-03-16T10:15:30.000000Z"
23 }

Configure preprocessing

Most onboarding settings are optional. Keep the defaults unless the dataset needs a specific preprocessing choice.

Prediction type and target

Initial configurations set the prediction type and target.

The platform supports CLASSIFICATION and REGRESSION. Configure a single target field for the model.

Categorical values

Categorical handling is controlled by several settings:

Setting	Purpose
`one_hot_encoding_max_categories`	Sets the threshold beyond which categorical fields switch from one-hot encoding to target encoding.
`handle_unseen_categories`	Enables masking for categories not seen during training.
`infrequency_threshold`	Groups infrequent categories under an infrequent category representation.
`strip_categories`	Removes leading and trailing whitespace from categorical values.

For more detail on encoding choices, see Encoding.

Missing values

impute controls whether missing values are imputed during onboarding.

When missing values are important to the modelling task, decide whether to clean them before ingestion or handle them during onboarding.

Feature groups

Feature groups let related features be treated together during modelling and explanations.

A feature group has a name and at least two features.

Sharding

Sharding controls how data is divided during onboarding.

If no sharding strategy is provided, the default depends on the prediction type: PROPORTIONATE for classification and RANDOM_APPROXIMATE for regression.

For imbalanced classification datasets, a disproportionate sharding strategy may be more appropriate than the default.

Retrieve configurations

Retrieve onboarding configurations when you need to reuse an existing configuration.

GET

/data-processing-onboarding-configurations

1 curl https://api.hi.umnai.com/data-processing-onboarding-configurations \
2      -H "Authorization: Bearer <token>"

Response

1 {
2   "data": [
3     {
4       "id": "ea8b745ead39ec442fc3b4fba359bf98",
5       "name": "Sample Organisation",
6       "status": "ACTIVE",
7       "created_at": "2026-03-11T16:04:19.749000Z",
8       "updated_at": null
9     }
10   ],
11   "pagination": {
12     "total_items": 1,
13     "items_per_page": 10,
14     "current_page": 1,
15     "total_pages": 1
16   }
17 }

To inspect a specific configuration, retrieve it by id.

GET

/data-processing-onboarding-configurations/:dataProcessingOnboardingConfigurationId

1 curl https://api.hi.umnai.com/data-processing-onboarding-configurations/{dataProcessingOnboardingConfigurationId} \
2      -H "Authorization: Bearer <token>"

Response

1 {
2   "data": [
3     {
4       "id": "ea8b745ead39ec442fc3b4fba359bf98",
5       "name": "Sample Organisation",
6       "status": "ACTIVE",
7       "created_at": "2026-03-11T16:04:19.749000Z",
8       "updated_at": null
9     }
10   ],
11   "pagination": {
12     "total_items": 1,
13     "items_per_page": 10,
14     "current_page": 1,
15     "total_pages": 1
16   }
17 }

Update a configuration

Update an onboarding configuration when you need to rename it.

PATCH

/data-processing-onboarding-configurations/:dataProcessingOnboardingConfigurationId

1 curl -X PATCH https://api.hi.umnai.com/data-processing-onboarding-configurations/dataProcessingOnboardingConfigurationId \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "name": "New Sample Onboarding Configuration"
6 }'

Response

1 {
2   "configuration_type": "INITIAL",
3   "encoding_strategy": "STREAM",
4   "feature_groups": [],
5   "handle_unseen_categories": true,
6   "impute": true,
7   "infrequency_threshold": 1,
8   "mask_category_fraction": 0.5,
9   "mask_fraction": 0.5,
10   "mask_median_fraction": 0.5,
11   "mask_rows_fraction": 0.5,
12   "one_hot_encoding_max_categories": 1,
13   "prediction_type": "CLASSIFICATION",
14   "sharding_strategy": "PROPORTIONATE",
15   "shards": 1,
16   "strip_categories": true,
17   "targets": [
18     "target_column"
19   ],
20   "id": "2df5b9fdb3389598e304f661315ebec8",
21   "name": "New Sample Onboarding Configuration",
22   "account": {
23     "id": "e268443e43d93dab7ebef303bbe9642f",
24     "name": "Sample Account"
25   },
26   "created_at": "2026-03-15T10:15:30.000000Z",
27   "created_by": {
28     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
29     "name": "Sample User"
30   },
31   "updated_at": "2026-03-15T10:15:30.000000Z"
32 }

Delete a configuration

Delete an onboarding configuration when it should no longer be used by future onboarding jobs.

DELETE

/data-processing-onboarding-configurations/:dataProcessingOnboardingConfigurationId

1 curl -X DELETE https://api.hi.umnai.com/data-processing-onboarding-configurations/dataProcessingOnboardingConfigurationId \
2      -H "Authorization: Bearer <token>"