Constraints | Umnai | Documentation

Model constraints let you guide the structure of a model during training.

Use them when you already know that a feature or feature interaction should be included, excluded, or prioritised. Constraints can be passed directly to a training job or collected into constraint groups for reuse.

How constraints fit into training

Identify the module

Choose the feature or feature interaction you want to control.

Choose the constraint

Decide whether the module should be included, excluded, or shortlisted.

Create the constraint

Save the constraint so it can be reused across training jobs.

Apply during training

Reference individual constraints or constraint groups when creating a training job.

Constraint behaviour

A constraint applies to one module. The module is described by the features in the constraint.

Constraint	Effect
`INCLUDE`	The module is always included.
`EXCLUDE`	The module is always excluded.
`SHORTLIST`	The module is prioritised, but may only be included if it fits within the model structure limits.

The API also accepts boolean values for include: true behaves like INCLUDE, and false behaves like EXCLUDE.

Use reason to record why the constraint exists, and weight to indicate how important the constraint is when several constraints apply.

To train only the modules defined by constraints, set exclude_implicit in the training configuration and do not set max_interactions.

Create and manage constraints

Create individual constraints for the modules you want to control. You can pass these constraints directly to a training job, even if you do not create a group.

Create a constraint

Create a constraint for the feature or interaction you want to include, exclude, or prioritise.

POST

/model-constraints

1 curl -X POST https://api.hi.umnai.com/model-constraints \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "name": "Sample Model Constraint",
6   "features": [
7     "sample_features"
8   ],
9   "include": true,
10   "reason": "sample_reason",
11   "weight": 1
12 }'

Response

1 {
2   "id": "5ae2fc124d3551f9b354bf5f0f5cafe7",
3   "account": {
4     "id": "e268443e43d93dab7ebef303bbe9642f",
5     "name": "Sample Account"
6   },
7   "name": "Sample Model Constraint",
8   "features": [
9     "sample_features"
10   ],
11   "include": true,
12   "reason": "sample_reason",
13   "weight": 1,
14   "created_at": "2026-03-15T10:15:30.000000Z",
15   "created_by": {
16     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
17     "name": "Sample User"
18   },
19   "updated_at": "2026-03-15T10:15:30.000000Z"
20 }

Save the returned constraint id. You will use it when assigning the constraint to a group or when creating a training job.

Retrieve constraints

Retrieve constraints when you need to reuse existing definitions or inspect how a module is constrained.

GET

/model-constraints

1 curl https://api.hi.umnai.com/model-constraints \
2      -H "Authorization: Bearer <token>"

Response

1 {
2   "data": [
3     {
4       "id": "ea8b745ead39ec442fc3b4fba359bf98",
5       "name": "Sample Organisation",
6       "created_at": "2026-03-11T16:04:19.749000Z",
7       "updated_at": null,
8       "status": "ACTIVE"
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 constraint, retrieve it by id.

GET

/model-constraints/:modelConstraintId

1 curl https://api.hi.umnai.com/model-constraints/{modelConstraintId} \
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 or delete a constraint

Update a constraint when you need to rename it.

PATCH

/model-constraints/:modelConstraintId

1 curl -X PATCH https://api.hi.umnai.com/model-constraints/modelConstraintId \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "name": "Sample Model Constraint"
6 }'

Response

1 {
2   "id": "5ae2fc124d3551f9b354bf5f0f5cafe7",
3   "account": {
4     "id": "e268443e43d93dab7ebef303bbe9642f",
5     "name": "Sample Account"
6   },
7   "name": "Sample Model Constraint",
8   "features": [
9     "sample_features"
10   ],
11   "include": true,
12   "reason": "sample_reason",
13   "weight": 1,
14   "created_at": "2026-03-15T10:15:30.000000Z",
15   "created_by": {
16     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
17     "name": "Sample User"
18   },
19   "updated_at": "2026-03-15T10:15:30.000000Z"
20 }

Delete a constraint when it should no longer be used.

DELETE

/model-constraints/:modelConstraintId

1 curl -X DELETE https://api.hi.umnai.com/model-constraints/modelConstraintId \
2      -H "Authorization: Bearer <token>"

Work with constraint groups

Constraint groups collect related constraints so they can be applied together.

Use a group when the same set of constraints should be reused across multiple training jobs, or when you want to keep domain, policy, or modelling constraints together.

Create a group

Create a group before assigning constraints to it.

POST

/model-constraint-groups

1 curl -X POST https://api.hi.umnai.com/model-constraint-groups \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "name": "Sample Model Constraint Group"
6 }'

Response

1 {
2   "id": "7816ab623b9cf875dd46d6fdd7667d46",
3   "account": {
4     "id": "e268443e43d93dab7ebef303bbe9642f",
5     "name": "Sample Account"
6   },
7   "name": "Sample Model Constraint Group",
8   "constraints": [
9     {
10       "id": "4c40acf7e0555c947c2fa09d7db82b3a",
11       "name": "Sample Constraint"
12     }
13   ],
14   "created_at": "2026-03-15T10:15:30.000000Z",
15   "created_by": {
16     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
17     "name": "Sample User"
18   },
19   "updated_at": "2026-03-15T10:15:30.000000Z"
20 }

Save the returned group id. You will use it when assigning constraints and when creating a training job.

Retrieve groups

Retrieve groups when you need to reuse a group in a training job or inspect the constraints assigned to it.

GET

/model-constraint-groups

1 curl https://api.hi.umnai.com/model-constraint-groups \
2      -H "Authorization: Bearer <token>"

Response

1 {
2   "data": [
3     {
4       "id": "ea8b745ead39ec442fc3b4fba359bf98",
5       "name": "Sample Organisation",
6       "created_at": "2026-03-11T16:04:19.749000Z",
7       "updated_at": null,
8       "status": "ACTIVE"
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 group, retrieve it by id.

GET

/model-constraint-groups/:modelConstraintsGroupId

1 curl https://api.hi.umnai.com/model-constraint-groups/{modelConstraintsGroupId} \
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 }

Assign constraints to a group

Assign constraints after both the constraint and the group have been created.

POST

/model-constraint-groups/:modelConstraintsGroupId/constraints

1 curl -X POST https://api.hi.umnai.com/model-constraint-groups/modelConstraintsGroupId/constraints \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "constraint_id": "3677ab7adaf00725e9fdbaed503a94e3"
6 }'

Response

1 {
2   "id": "7816ab623b9cf875dd46d6fdd7667d46",
3   "account": {
4     "id": "e268443e43d93dab7ebef303bbe9642f",
5     "name": "Sample Account"
6   },
7   "name": "Sample Model Constraint Group",
8   "constraints": [
9     {
10       "id": "4c40acf7e0555c947c2fa09d7db82b3a",
11       "name": "Sample Constraint"
12     }
13   ],
14   "created_at": "2026-03-15T10:15:30.000000Z",
15   "created_by": {
16     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
17     "name": "Sample User"
18   },
19   "updated_at": "2026-03-15T10:15:30.000000Z"
20 }

Unassign constraints from a group

Unassign a constraint when it should no longer belong to the group.

DELETE

/model-constraint-groups/:modelConstraintsGroupId/constraints/:modelConstraintId

1 curl -X DELETE https://api.hi.umnai.com/model-constraint-groups/modelConstraintsGroupId/constraints/modelConstraintId \
2      -H "Authorization: Bearer <token>"

Update or delete a group

Update a group when you need to rename it.

PATCH

/model-constraint-groups/:modelConstraintsGroupId

1 curl -X PATCH https://api.hi.umnai.com/model-constraint-groups/modelConstraintsGroupId \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "name": "Sample Model Constraint Group"
6 }'

Response

1 {
2   "id": "7816ab623b9cf875dd46d6fdd7667d46",
3   "account": {
4     "id": "e268443e43d93dab7ebef303bbe9642f",
5     "name": "Sample Account"
6   },
7   "name": "Sample Model Constraint Group",
8   "constraints": [
9     {
10       "id": "4c40acf7e0555c947c2fa09d7db82b3a",
11       "name": "Sample Constraint"
12     }
13   ],
14   "created_at": "2026-03-15T10:15:30.000000Z",
15   "created_by": {
16     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
17     "name": "Sample User"
18   },
19   "updated_at": "2026-03-15T10:15:30.000000Z"
20 }

Delete a group when it should no longer be used.

DELETE

/model-constraint-groups/:modelConstraintsGroupId

1 curl -X DELETE https://api.hi.umnai.com/model-constraint-groups/modelConstraintsGroupId \
2      -H "Authorization: Bearer <token>"

How constraints fit into training

Identify the module

Choose the constraint

Create the constraint

Group related constraints

Apply during training

Constraint behaviour

Create and manage constraints

Create a constraint

Retrieve constraints

Update or delete a constraint

Work with constraint groups

Create a group

Retrieve groups

Assign constraints to a group

Unassign constraints from a group

Update or delete a group