Unit

Unit is the core unit of operation in ConfigHub. It contains a blob of configuration Data of a single supported Toolchain Type (configuration format). This blob is typically a text document that contains a collection of Kubernetes or infrastructure resources, or an application configuration file. Applying / deploying or destroying the configuration happens as a single transaction from ConfigHub's perspective. In reality, it is most often a multi-step workflow performed by the underlying configuration / deployment tool. The resources must belong to a single infrastructure provider and the actuation mechanism must be able to resolve references and ordering dependencies among the resources within the document. For example, if one resource needs to be fully provisioned to provide input to another resource, then the actuation code is responsible for handling this. Revisions store historical copies of the configuration data. Configuration data can be restored from prior Revisions. Units can also be cloned to create new variants of a configuration.

Operations

Method	Endpoint	Description
`GET`	`/space/{space_id}/unit`	List Units
`GET`	`/unit`	List of Units across spaces
`GET`	`/unit_data`	Get the config data of many Units across spaces
`GET`	`/unit_mutation_sources`	Get the mutation sources of many Units across spaces
`GET`	`/space/{space_id}/unit/{unit_id}`	Get Unit
`GET`	`/space/{space_id}/unit/{unit_id}/data`	Download config data
`GET`	`/space/{space_id}/unit/{unit_id}/extended`	Get Unit details with expanded relationships
`GET`	`/space/{space_id}/unit/{unit_id}/mutation_sources`	Get mutation sources
`POST`	`/space/{space_id}/unit`	Create Unit
`POST`	`/space/{space_id}/unit/{unit_id}/approve`	Approve a unit configuration
`POST`	`/space/{space_id}/unit/{unit_id}/conflicts`	Apply or dismiss a unit's outstanding merge conflicts
`POST`	`/space/{space_id}/unit/{unit_id}/guard`	Set path guards on a unit
`POST`	`/space/{space_id}/unit/{unit_id}/protection`	Set path protection on a unit
`POST`	`/unit`	Bulk create (clone) multiple units
`POST`	`/unit/approve`	Bulk approve multiple units
`POST`	`/unit/cancel`	Bulk cancel unit operations
`POST`	`/unit/tag`	Bulk tag multiple units
`PATCH`	`/space/{space_id}/unit/{unit_id}`	Patch Unit
`PUT`	`/space/{space_id}/unit/{unit_id}`	Update Unit
`PUT`	`/space/{space_id}/unit/{unit_id}/data`	Upload config data
`PATCH`	`/unit`	Bulk patch multiple units
`DELETE`	`/space/{space_id}/unit/{unit_id}`	Delete Unit
`DELETE`	`/unit`	Bulk delete multiple units

List Units

GET /space/{space_id}/unit

List Units

Operation ID: ListUnits

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`select`	string	Select clause for specifying which fields to include in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. If not specified, all fields are returned. Entity and parent IDs (like OrganizationID, SpaceID, UnitID) and Slug are always returned regardless of the select parameter. Fields used in where and contains filters, and fields named by order_by, are also automatically included. Example: 'DisplayName,CreatedAt,Labels' will return only those fields plus the required ID and Slug fields. The whole string must be query-encoded.
`resource_type`	string	Resource type: Resource type to match for the desired ToolchainType, for example apps/v1/Deployment
`where_data`	string	Where data: The specified string is an expression for the purpose of evaluating whether the configuration data matches the filter. It supports conjunctions using `AND` of relational expressions of the form path operator literal. The path specifications are dot-separated, for both map fields and array indices, as in `spec.template.spec.containers.0.image = 'ghcr.io/headlamp-k8s/headlamp:latest' AND spec.replicas > 1`. Path expressions support `` for wildcard array or map segments and `?key=value` syntax for associative matches of array elements containing objects with a `key` attribute. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `!~`, `~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `!~~` for NOT LIKE. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~*` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. Boolean values support equality and inequality only. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `spec.template.spec.containers.0.image#reference IN (':latest', ':arm64-latest')`. The syntax `.\\|` requires the preceding path to exist; otherwise the relation `!=` will always return true regardless what it is compared with. String literals are quoted with single quotes, such as `'string'`. Integer and boolean literals are also supported for attributes of those types. The whole string must be query-encoded.
`where_trigger`	string	Where expression to match Triggers. Matched triggers are invoked on each unit to filter by validation results. Use with triggers_passed to control whether passing or failing units are returned (default: failing).
`trigger_filter`	string	Filter UUID (with From=Trigger). The filter's matching triggers are invoked on units to filter by validation results. Can be combined with where_trigger.
`triggers_passed`	boolean	When true, return units that pass trigger validation; when false (default), return units that fail. Only applies when where_trigger or trigger_filter is specified.
`view`	string	View slug or UUID. Applies the View's column definitions to extract values for each unit. If the View has a FilterID, its filter is ANDed with other filters. The View must have Of=Unit or a Filter with From=Unit.

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `ExtendedUnit`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

List of Units across spaces

GET /unit

Retrieves a list of Units across spaces in the Organization

Operation ID: ListAllUnits

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`select`	string	Select clause for specifying which fields to include in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. If not specified, all fields are returned. Entity and parent IDs (like OrganizationID, SpaceID, UnitID) and Slug are always returned regardless of the select parameter. Fields used in where and contains filters, and fields named by order_by, are also automatically included. Example: 'DisplayName,CreatedAt,Labels' will return only those fields plus the required ID and Slug fields. The whole string must be query-encoded.
`resource_type`	string	Resource type: Resource type to match for the desired ToolchainType, for example apps/v1/Deployment
`where_data`	string	Where data: The specified string is an expression for the purpose of evaluating whether the configuration data matches the filter. It supports conjunctions using `AND` of relational expressions of the form path operator literal. The path specifications are dot-separated, for both map fields and array indices, as in `spec.template.spec.containers.0.image = 'ghcr.io/headlamp-k8s/headlamp:latest' AND spec.replicas > 1`. Path expressions support `` for wildcard array or map segments and `?key=value` syntax for associative matches of array elements containing objects with a `key` attribute. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `!~`, `~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `!~~` for NOT LIKE. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~*` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. Boolean values support equality and inequality only. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `spec.template.spec.containers.0.image#reference IN (':latest', ':arm64-latest')`. The syntax `.\\|` requires the preceding path to exist; otherwise the relation `!=` will always return true regardless what it is compared with. String literals are quoted with single quotes, such as `'string'`. Integer and boolean literals are also supported for attributes of those types. The whole string must be query-encoded.
`where_trigger`	string	Where expression to match Triggers. Matched triggers are invoked on each unit to filter by validation results. Use with triggers_passed to control whether passing or failing units are returned (default: failing).
`trigger_filter`	string	Filter UUID (with From=Trigger). The filter's matching triggers are invoked on units to filter by validation results. Can be combined with where_trigger.
`triggers_passed`	boolean	When true, return units that pass trigger validation; when false (default), return units that fail. Only applies when where_trigger or trigger_filter is specified.
`view`	string	View slug or UUID. Applies the View's column definitions to extract values for each unit. If the View has a FilterID, its filter is ANDed with other filters. The View must have Of=Unit or a Filter with From=Unit.

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `ExtendedUnit`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Get the config data of many Units across spaces

GET /unit_data

Returns the configuration of every Unit the where clause selects, across every Space in the organization, in one request, with each Unit's DataHash and DataSize. This is the bulk counterpart of the single-Unit data endpoint; it exists as an endpoint of its own rather than as a mode on the Unit list so that no query parameter changes the shape of a response. Scope it to one Space with a where clause.

Operation ID: SearchUnitData

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`select`	string	Select clause for specifying which fields to include in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. If not specified, all fields are returned. Entity and parent IDs (like OrganizationID, SpaceID, UnitID) and Slug are always returned regardless of the select parameter. Fields used in where and contains filters, and fields named by order_by, are also automatically included. Example: 'DisplayName,CreatedAt,Labels' will return only those fields plus the required ID and Slug fields. The whole string must be query-encoded.
`resource_type`	string	Resource type: Resource type to match for the desired ToolchainType, for example apps/v1/Deployment
`where_data`	string	Where data: The specified string is an expression for the purpose of evaluating whether the configuration data matches the filter. It supports conjunctions using `AND` of relational expressions of the form path operator literal. The path specifications are dot-separated, for both map fields and array indices, as in `spec.template.spec.containers.0.image = 'ghcr.io/headlamp-k8s/headlamp:latest' AND spec.replicas > 1`. Path expressions support `` for wildcard array or map segments and `?key=value` syntax for associative matches of array elements containing objects with a `key` attribute. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `!~`, `~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `!~~` for NOT LIKE. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~*` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. Boolean values support equality and inequality only. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `spec.template.spec.containers.0.image#reference IN (':latest', ':arm64-latest')`. The syntax `.\\|` requires the preceding path to exist; otherwise the relation `!=` will always return true regardless what it is compared with. String literals are quoted with single quotes, such as `'string'`. Integer and boolean literals are also supported for attributes of those types. The whole string must be query-encoded.
`where_trigger`	string	Where expression to match Triggers. Matched triggers are invoked on each unit to filter by validation results. Use with triggers_passed to control whether passing or failing units are returned (default: failing).
`trigger_filter`	string	Filter UUID (with From=Trigger). The filter's matching triggers are invoked on units to filter by validation results. Can be combined with where_trigger.
`triggers_passed`	boolean	When true, return units that pass trigger validation; when false (default), return units that fail. Only applies when where_trigger or trigger_filter is specified.
`view`	string	View slug or UUID. Applies the View's column definitions to extract values for each unit. If the View has a FilterID, its filter is ANDed with other filters. The View must have Of=Unit or a Filter with From=Unit.

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `UnitData`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Get the mutation sources of many Units across spaces

GET /unit_mutation_sources

Returns what set each value in the configuration of every Unit the where clause selects, across every Space in the organization, in one request. This is the bulk counterpart of the single-Unit mutation-sources subresource, and the Unit-level counterpart of /revision_mutation_sources, which cannot answer for a Unit's head because "each Unit's head Revision" is not expressible as a where clause over Revisions. Scope it to one Space with a where clause.

Operation ID: SearchUnitMutationSources

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`select`	string	Select clause for specifying which fields to include in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. If not specified, all fields are returned. Entity and parent IDs (like OrganizationID, SpaceID, UnitID) and Slug are always returned regardless of the select parameter. Fields used in where and contains filters, and fields named by order_by, are also automatically included. Example: 'DisplayName,CreatedAt,Labels' will return only those fields plus the required ID and Slug fields. The whole string must be query-encoded.
`resource_type`	string	Resource type: Resource type to match for the desired ToolchainType, for example apps/v1/Deployment
`where_data`	string	Where data: The specified string is an expression for the purpose of evaluating whether the configuration data matches the filter. It supports conjunctions using `AND` of relational expressions of the form path operator literal. The path specifications are dot-separated, for both map fields and array indices, as in `spec.template.spec.containers.0.image = 'ghcr.io/headlamp-k8s/headlamp:latest' AND spec.replicas > 1`. Path expressions support `` for wildcard array or map segments and `?key=value` syntax for associative matches of array elements containing objects with a `key` attribute. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `!~`, `~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `!~~` for NOT LIKE. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~*` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. Boolean values support equality and inequality only. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `spec.template.spec.containers.0.image#reference IN (':latest', ':arm64-latest')`. The syntax `.\\|` requires the preceding path to exist; otherwise the relation `!=` will always return true regardless what it is compared with. String literals are quoted with single quotes, such as `'string'`. Integer and boolean literals are also supported for attributes of those types. The whole string must be query-encoded.
`where_trigger`	string	Where expression to match Triggers. Matched triggers are invoked on each unit to filter by validation results. Use with triggers_passed to control whether passing or failing units are returned (default: failing).
`trigger_filter`	string	Filter UUID (with From=Trigger). The filter's matching triggers are invoked on units to filter by validation results. Can be combined with where_trigger.
`triggers_passed`	boolean	When true, return units that pass trigger validation; when false (default), return units that fail. Only applies when where_trigger or trigger_filter is specified.
`view`	string	View slug or UUID. Applies the View's column definitions to extract values for each unit. If the View has a FilterID, its filter is ANDed with other filters. The View must have Of=Unit or a Filter with From=Unit.

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `UnitMutationSources`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Get Unit

GET /space/{space_id}/unit/{unit_id}

Get Unit

Operation ID: GetUnit

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Query Parameters

Parameter	Type	Required	Description
`include`	string		Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`select`	string		Select clause for specifying which fields to include in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. If not specified, all fields are returned. Entity and parent IDs (like OrganizationID, SpaceID, UnitID) and Slug are always returned regardless of the select parameter. Fields used in where and contains filters, and fields named by order_by, are also automatically included. Example: 'DisplayName,CreatedAt,Labels' will return only those fields plus the required ID and Slug fields. The whole string must be query-encoded.

Responses

Status	Description	Content-Type	Schema
200	Unit with capability to extend additional related entities.	`application/json`	`ExtendedUnit`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Download config data

GET /space/{space_id}/unit/{unit_id}/data

Download the config data of a unit. The response carries the DataHash as an ETag; send it back as If-None-Match to get a 304 when the configuration has not changed.

Operation ID: DownloadUnitData

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Responses

Status	Description	Content-Type	Schema
200	OK	`application/octet-stream`	`string`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Get Unit details with expanded relationships

GET /space/{space_id}/unit/{unit_id}/extended

Get Unit details with expanded relationships

Operation ID: GetUnitExtended

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`UnitExtended`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Get mutation sources

GET /space/{space_id}/unit/{unit_id}/mutation_sources

Read what set each value in a Unit's configuration, by resource and path. MutationSources is the largest column on the table -- larger than the configuration itself -- so it is a subresource rather than a field.

Operation ID: GetUnitMutationSources

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`MutationSourcesResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Create Unit

POST /space/{space_id}/unit

Create Unit

Operation ID: CreateUnit

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id

Query Parameters

Parameter	Type	Description
`upstream_space_id`	string	Unique identifier for a upstream_space_id
`upstream_unit_id`	string	Unique identifier for a upstream_unit_id
`upstream_revision`	string	Revision of the upstream Unit to copy. The default is its head, which is what a clone has always taken. Takes the same forms as merge_end and restore -- a revision number, a named revision, 'Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Before:...' -- resolved against the Unit being cloned from, so a bulk clone lands on a different revision of each source Unit. 'Before:ChangeOrder:uuid' is what a promotion uses: it names the state the change starts from, which for a Unit no target has taken yet is its first revision, so the upgrade that follows replays the change into the clone rather than the clone arriving with the change already folded in. Requires upstream_unit_id (or, in bulk, a source Unit to clone).
`syncback`	boolean	Also create a MergeUnits Link from each upstream Unit back to its clone, alongside the UpgradeUnit Link a clone always gets. The upgrade Link carries changes from the upstream Unit into the clone; this one carries them the other way, which is what makes a clone usable as a draft: change it, review it, then resolve the Link (resolve=Link:...) on the upstream Unit to merge the change home. A Unit may be the source of several of these -- one per outstanding draft -- so each is named for the clone it takes changes from (syncback--) rather than for the Unit they all point at. The Link is created in the upstream Unit's Space, which the caller must be allowed to create Links in. Requires upstream_unit_id (or, in bulk, a source Unit to clone).
`merge_external_source`	string	Identifier of the external source. Sets the source type to MergeExternal and appends the source name to the change description.
`allow_exists`	string	Allowed values are true and false. Default is false. When true, reports success when an entity already exists and returns the existing entity
`include`	string	Comma-separated parts of the result to return in addition to the Unit: ConfigData for the configuration the operation produced, and MutationSources for what set each value in it. Neither is a field of a Unit, and both cost something to return, so they are returned only when named. A dry run stores nothing, so this is the only way to see what it would have produced.

Request Body

Content-Type: application/json

Schema: Unit

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`UnitCreateOrUpdateResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
422	Unable to create unit(s) due to configuration data problem	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Approve a unit configuration

POST /space/{space_id}/unit/{unit_id}/approve

Record that the user invoking this operation approves the configuration data

Operation ID: ApproveUnit

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Query Parameters

Parameter	Type	Required	Description
`revision`	string		Revision to approve (defaults to HeadRevisionNum). Can be a revision number, 'LastReleasedRevisionNum', 'Tag:uuid', 'ChangeSet:uuid', etc.

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`ApproveResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Apply or dismiss a unit's outstanding merge conflicts

POST /space/{space_id}/unit/{unit_id}/conflicts

Act on the parts of the last merge's patch that were not applied. Apply replays the withheld change with every path eligible; Dismiss drops it without changing the configuration data. Either way the selected conflicts leave the Unit's outstanding set. Requires Edit permission.

Operation ID: ResolveUnitConflicts

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Request Body

Content-Type: application/json

Schema: UnitConflictsRequest

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`UnitConflictsResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Set path guards on a unit

POST /space/{space_id}/unit/{unit_id}/guard

Set or remove guards on the unit's PathAnnotations. A guard names a reason a path's value is what it is, so a later operation can be required to know about that reason before overwriting it. Nothing enforces guards yet: setting one records the reason and changes no behavior. A guard may name a path or resource the unit does not have, since it is policy about the configuration rather than a statement about its current contents. Creates a new revision only if the guards actually change. Requires Edit permission.

Operation ID: SetUnitGuard

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Request Body

Content-Type: application/json

Schema: UnitGuardRequest

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`UnitGuardResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Set path protection on a unit

POST /space/{space_id}/unit/{unit_id}/protection

Set Protected values on the unit's MutationSources, marking paths as local overrides a merge must not overwrite when subtraction is disabled. A merge's WhereMutation protects further paths on top of these. Creates a new revision only if the protection actually changes. Requires Edit permission.

Operation ID: SetUnitProtection

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Request Body

Content-Type: application/json

Schema: UnitProtectionRequest

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`UnitProtectionResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk create (clone) multiple units

POST /unit

Clone multiple units selected by query parameters with optional name prefixes and destination spaces

Operation ID: BulkCreateUnits

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`name_prefixes`	string	Comma-separated list of prefixes to apply to cloned Unit names
`variant_labels`	string	Comma-separated list of labels with multiple values for cloned Unit labels, in the format of key1=value1\|value2,key2=value1\|value2\|value3
`name_pattern`	string	A string for clone names, use the prefix 'template:' for a Go-template with .SourceEntitySlug to access the original entity's slug and .Labels to access variant labels, example: 'template:{{.SourceEntitySlug}}-{{.Labels.env}}'
`where_space`	string	The specified string is an expression for the purpose of filtering the list of Spaces returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Space: Annotations, AttributeFilterID, AttributeHash, AttributeIDs, CreatedAt, DeleteGates, DisplayName, Labels, OrganizationID, Permissions, ReleaseBridgeWorkerID, ReleaseTargetID, Slug, SpaceID, TriggerFilterID, TriggerHash, TriggerIDs, UpdatedAt. Where expression to select destination spaces for cloning units The whole string must be query-encoded.
`filter_space`	string	UUID of a Filter entity to apply to the Space list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Space). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`allow_exists`	string	Allowed values are true and false. Default is false. When true, reports success when an entity already exists and returns the existing entity
`include_outgoing_links_where`	string	The specified string is an expression for the purpose of filtering the list of Links returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Link: Annotations, AutoUpdate, CreatedAt, DeleteGates, DisplayName, DownstreamLastMergedRevisionNum, FromUnitID, Hash, Labels, LinkID, MergeEnableSubtraction, OrganizationID, Protect, Slug, SpaceID, Squash, Stale, ToSpaceID, ToUnitID, TransformInvocationID, UpdateType, UpdatedAt, UpstreamLastMergedRevisionNum, UpstreamLinkID, UpstreamSpaceID. Where expression to filter outgoing links (links to units outside the cloned set) for copying. If non-empty, matching outgoing links are also copied with FromUnitID retargeted to the cloned unit. The whole string must be query-encoded.
`upstream_revision`	string	Revision of the upstream Unit to copy. The default is its head, which is what a clone has always taken. Takes the same forms as merge_end and restore -- a revision number, a named revision, 'Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Before:...' -- resolved against the Unit being cloned from, so a bulk clone lands on a different revision of each source Unit. 'Before:ChangeOrder:uuid' is what a promotion uses: it names the state the change starts from, which for a Unit no target has taken yet is its first revision, so the upgrade that follows replays the change into the clone rather than the clone arriving with the change already folded in. Requires upstream_unit_id (or, in bulk, a source Unit to clone).
`syncback`	boolean	Also create a MergeUnits Link from each upstream Unit back to its clone, alongside the UpgradeUnit Link a clone always gets. The upgrade Link carries changes from the upstream Unit into the clone; this one carries them the other way, which is what makes a clone usable as a draft: change it, review it, then resolve the Link (resolve=Link:...) on the upstream Unit to merge the change home. A Unit may be the source of several of these -- one per outstanding draft -- so each is named for the clone it takes changes from (syncback--) rather than for the Unit they all point at. The Link is created in the upstream Unit's Space, which the caller must be allowed to create Links in. Requires upstream_unit_id (or, in bulk, a source Unit to clone).

Request Body

Content-Type: application/merge-patch+json

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `UnitCreateOrUpdateResponse`
207	Multi-Status (partial success)	`application/json`	Array of `UnitCreateOrUpdateResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
422	Unable to create unit(s) due to configuration data problem	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk approve multiple units

POST /unit/approve

Record that the user invoking this operation approves multiple unit configurations using where and contains filters

Operation ID: BulkApproveUnits

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`revision`	string	Revision to approve (defaults to HeadRevisionNum). Can be a revision number, 'LastReleasedRevisionNum', 'Tag:uuid', 'ChangeSet:uuid', etc.

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `ApproveResponse`
207	Multi-Status: Mixed success and failure results	`application/json`	Array of `ApproveResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk cancel unit operations

POST /unit/cancel

Cancels pending or in-progress operations for multiple units based on filter criteria

Operation ID: BulkCancelUnits

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `UnitActionResponse`
207	Multi-Status: Mixed success and failure results	`application/json`	Array of `UnitActionResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
422	Unable to cancel unit operation(s)	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk tag multiple units

POST /unit/tag

Attach tags to specified unit revisions

Operation ID: BulkTagUnits

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.

Request Body

Content-Type: application/json

Schema: UnitTagRequest

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `UnitTagResponse`
207	Multi-Status: Mixed success and failure results	`application/json`	Array of `UnitTagResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Patch Unit

PATCH /space/{space_id}/unit/{unit_id}

Patch Unit

Operation ID: PatchUnit

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Query Parameters

Parameter	Type	Description
`revision_id`	string	Unique identifier for a revision_id
`dry_run`	boolean	Dry run mode: return changed unit(s) but don't update configuration data
`protect`	boolean	Record the paths this operation writes as protected local overrides, so a later merge from upstream does not overwrite them. Without it the operation claims nothing: each written path keeps whatever the Unit already has for it, and a path with no history is left unprotected. It only ever adds protection -- re-opening a path is the /protection API (cub unit set-protection --unprotect). Has no effect with restore, which rewinds MutationSources to the restored Revision's stored values wholesale.
`clearance`	string	The classes of guarded reason this operation is cleared for, as a JSON Clearance -- a list of {Key, Operator, Values} requirements, where Operator is Exists, In, NotIn, or DoesNotExist. A path whose guards this does not cover is not written, and the withheld change is reported as a Guarded conflict. An absent or empty clearance clears nothing, which only matters for a Unit that has guards.
`guards`	string	The guards this operation records on the paths it writes, as a JSON object of guard key to value -- the reasons those paths hold what they hold, so a later operation must be cleared for them before overwriting. The guard analogue of protect: protect claims the paths, this says why. It only ever adds and overwrites the keys it names -- retiring a guard is the /guard API (cub unit set-guard --remove-guard).
`squash`	boolean	Merge the range as one rebased diff and record it as one Revision, instead of walking it. By default a merge replays: it takes the source's Revisions in order and, where a Revision records function invocations that can be re-executed, runs them against this Unit rather than rebasing their recorded paths onto it -- so a change lands where this Unit's own structure puts it -- and records each source Revision that has an effect here as a Revision of its own, carrying that Revision's change description, its own conflicts, and one Mutation per source Mutation. Squashing gives up both: the range arrives as a single rebased patch in a single Revision, which is what a merge did before replay existed. Accepted with upgrade, merge_source, and resolve of an UpgradeUnit or MergeUnits Link, and refused elsewhere, since there is no range to walk. A Link can ask for it standingly with its Squash field.
`upgrade`	boolean	Upgrade the unit to the latest version of its upstream unit
`restore`	string	Restore revision source. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`resolve`	string	Resolve Links from this (downstream) Unit to another (upstream) Unit, propagating what each Link's UpdateType says to propagate. Expects Link:, Link:, or Link:. Link: selects every Link from this Unit that can resolve; a where expression selects among those, evaluated against the Links themselves (e.g. UpdateType = 'MergeUnits'), which is how to name one Link in a bulk operation, where a UUID cannot be. A Link with UpdateType None resolves nothing and is never selected. An AutoUpdate Link may be resolved by hand: it does what the queue would have done, and nothing when the Link is already level with its source.
`merge_source`	string	Merge source unit. Currently it must be a unit ID or 'Self'.
`merge_base`	string	Merge base revision, which provides the base configuration data of the changes to merge. With merge_source, this is a revision of the merge source unit. With merge_external_source, this is a revision of the unit being updated and overrides the default selection of the latest MergeExternal revision. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`merge_end`	string	Merge end revision of the merge source, which provides the final configuration of the changes to merge. Also accepted with upgrade and with resolve, where it names how far along the source to take the propagation; the default there is the source's head. Naming a ChangeSet or Tag that ends a change is what leaves a change still being made at the source behind. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`merge_external_source`	string	Identifier of the external source for merge-on-update. When set, computes mutations between the last MergeExternal revision and the provided data, then patches the current unit data with those mutations.
`merge_enable_subtraction`	boolean	Enable the subtraction (override-preservation) step of upgrade and merge_source. By default (false), the source patch is applied without subtraction and the target's local differences are preserved by the stored Mutation Protected values; set true to additionally subtract the target's local differences from the source patch. Has no effect on a self merge (merge_source=Self), where subtraction is always disabled.
`where_mutation`	string	The specified string is an expression for the purpose of filtering the list of Mutations returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Mutation: BridgeWorkerID, CreatedAt, FunctionName, InvocationID, InvocationParams, LinkID, MergeBaseRevisionNum, MergeEndRevisionNum, MergeSourceID, MutationID, MutationNum, OrganizationID, ReplayOutcome, ReplayReason, RestoredRevisionNum, RevisionID, RevisionNum, SpaceID, Subgroup, TriggerID, UnitID, UpdatedAt, UpgradedFromUpstreamRevisionNum. Selects Mutations of this Unit whose paths the merge must not overwrite, unioned with the Protected values stored on the Unit's MutationSources. The whole string must be query-encoded.
`filter_mutation`	string	UUID of a Filter entity to apply to the Mutation list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Mutation). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`tag`	string	Tag ID to add to the head revision
`change_set_id`	string	Must match ChangeSetID of affected Units if config Data is changed unless in dry run mode
`change_order`	string	ChangeOrder to promote, with upgrade or resolve, or to undo, with restore. The change order fixed the range when it was created -- the interval on each source Unit, marked with its Tags -- so it supplies both ends of the merge and merge_end is refused alongside it. A Unit whose source the change order does not cover is passed over rather than failed, which is what lets a bulk upgrade name a whole Space and take only the Units the change is in. A Unit whose last merged revision is not where the change order starts is an error, since merging anyway would replay what it already has or skip what it does not, and with resolve a selected Link whose UpdateType the change order does not follow is an error too. The revisions the promotion creates carry the ChangeOrder, and its start Tag is placed on the revision before them and its end Tag on the one it arrives at, so 'restore Before:ChangeOrder:uuid' undoes it whether it landed as one revision or as one per source revision. With restore the change order is being undone rather than promoted: the restore must be 'Before:ChangeOrder:' the same change order, the change order must have an AbortedReason -- undoing a change nobody has said is not coming is a race with whoever is still promoting it -- and a Unit the change order never marked is an error rather than passed over, since naming it says the Unit is part of the undoing. The first restore mints the change order's restore Tag and records it as RestoreTagID; every restore after that marks with the same Tag, which is what RestoredSpaceIDs is read off. A Unit the change order carried nothing for takes the restore Tag on the revision its start and end Tags are already on, and no revision is made. A Unit already carrying the restore Tag has had the change order taken back out of it and is passed over, since undoing one in a Unit happens once as promoting it into one does -- so the revisions a Unit has taken since it was undone are its own work rather than this undoing's to drop. Restoring also advances the merge pointers of the Links of the change order's UpdateType that follow the restored Unit onto the revision the restore made, so a later upgrade does not replay the change that was just taken out; the downstream Units are not restored with it, since each has to be restored and released on its own account.
`subgroup`	string	User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.
`include`	string	Comma-separated parts of the result to return in addition to the Unit: ConfigData for the configuration the operation produced, and MutationSources for what set each value in it. Neither is a field of a Unit, and both cost something to return, so they are returned only when named. A dry run stores nothing, so this is the only way to see what it would have produced.

Request Body

Content-Type: application/merge-patch+json

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`UnitCreateOrUpdateResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
422	Unable to patch unit(s) due to configuration data problem	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Update Unit

PUT /space/{space_id}/unit/{unit_id}

Update Unit

Operation ID: UpdateUnit

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Query Parameters

Parameter	Type	Description
`revision_id`	string	Unique identifier for a revision_id
`dry_run`	boolean	Dry run mode: return changed unit(s) but don't update configuration data
`protect`	boolean	Record the paths this operation writes as protected local overrides, so a later merge from upstream does not overwrite them. Without it the operation claims nothing: each written path keeps whatever the Unit already has for it, and a path with no history is left unprotected. It only ever adds protection -- re-opening a path is the /protection API (cub unit set-protection --unprotect). Has no effect with restore, which rewinds MutationSources to the restored Revision's stored values wholesale.
`clearance`	string	The classes of guarded reason this operation is cleared for, as a JSON Clearance -- a list of {Key, Operator, Values} requirements, where Operator is Exists, In, NotIn, or DoesNotExist. A path whose guards this does not cover is not written, and the withheld change is reported as a Guarded conflict. An absent or empty clearance clears nothing, which only matters for a Unit that has guards.
`guards`	string	The guards this operation records on the paths it writes, as a JSON object of guard key to value -- the reasons those paths hold what they hold, so a later operation must be cleared for them before overwriting. The guard analogue of protect: protect claims the paths, this says why. It only ever adds and overwrites the keys it names -- retiring a guard is the /guard API (cub unit set-guard --remove-guard).
`squash`	boolean	Merge the range as one rebased diff and record it as one Revision, instead of walking it. By default a merge replays: it takes the source's Revisions in order and, where a Revision records function invocations that can be re-executed, runs them against this Unit rather than rebasing their recorded paths onto it -- so a change lands where this Unit's own structure puts it -- and records each source Revision that has an effect here as a Revision of its own, carrying that Revision's change description, its own conflicts, and one Mutation per source Mutation. Squashing gives up both: the range arrives as a single rebased patch in a single Revision, which is what a merge did before replay existed. Accepted with upgrade, merge_source, and resolve of an UpgradeUnit or MergeUnits Link, and refused elsewhere, since there is no range to walk. A Link can ask for it standingly with its Squash field.
`upgrade`	boolean	Upgrade the unit to the latest version of its upstream unit
`restore`	string	Restore revision source. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`resolve`	string	Resolve Links from this (downstream) Unit to another (upstream) Unit, propagating what each Link's UpdateType says to propagate. Expects Link:, Link:, or Link:. Link: selects every Link from this Unit that can resolve; a where expression selects among those, evaluated against the Links themselves (e.g. UpdateType = 'MergeUnits'), which is how to name one Link in a bulk operation, where a UUID cannot be. A Link with UpdateType None resolves nothing and is never selected. An AutoUpdate Link may be resolved by hand: it does what the queue would have done, and nothing when the Link is already level with its source.
`merge_source`	string	Merge source unit. Currently it must be a unit ID or 'Self'.
`merge_base`	string	Merge base revision, which provides the base configuration data of the changes to merge. With merge_source, this is a revision of the merge source unit. With merge_external_source, this is a revision of the unit being updated and overrides the default selection of the latest MergeExternal revision. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`merge_end`	string	Merge end revision of the merge source, which provides the final configuration of the changes to merge. Also accepted with upgrade and with resolve, where it names how far along the source to take the propagation; the default there is the source's head. Naming a ChangeSet or Tag that ends a change is what leaves a change still being made at the source behind. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`merge_external_source`	string	Identifier of the external source for merge-on-update. When set, computes mutations between the last MergeExternal revision and the provided data, then patches the current unit data with those mutations.
`merge_enable_subtraction`	boolean	Enable the subtraction (override-preservation) step of upgrade and merge_source. By default (false), the source patch is applied without subtraction and the target's local differences are preserved by the stored Mutation Protected values; set true to additionally subtract the target's local differences from the source patch. Has no effect on a self merge (merge_source=Self), where subtraction is always disabled.
`where_mutation`	string	The specified string is an expression for the purpose of filtering the list of Mutations returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Mutation: BridgeWorkerID, CreatedAt, FunctionName, InvocationID, InvocationParams, LinkID, MergeBaseRevisionNum, MergeEndRevisionNum, MergeSourceID, MutationID, MutationNum, OrganizationID, ReplayOutcome, ReplayReason, RestoredRevisionNum, RevisionID, RevisionNum, SpaceID, Subgroup, TriggerID, UnitID, UpdatedAt, UpgradedFromUpstreamRevisionNum. Selects Mutations of this Unit whose paths the merge must not overwrite, unioned with the Protected values stored on the Unit's MutationSources. The whole string must be query-encoded.
`filter_mutation`	string	UUID of a Filter entity to apply to the Mutation list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Mutation). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`tag`	string	Tag ID to add to the head revision
`change_set_id`	string	Must match ChangeSetID of affected Units if config Data is changed unless in dry run mode
`change_order`	string	ChangeOrder to promote, with upgrade or resolve, or to undo, with restore. The change order fixed the range when it was created -- the interval on each source Unit, marked with its Tags -- so it supplies both ends of the merge and merge_end is refused alongside it. A Unit whose source the change order does not cover is passed over rather than failed, which is what lets a bulk upgrade name a whole Space and take only the Units the change is in. A Unit whose last merged revision is not where the change order starts is an error, since merging anyway would replay what it already has or skip what it does not, and with resolve a selected Link whose UpdateType the change order does not follow is an error too. The revisions the promotion creates carry the ChangeOrder, and its start Tag is placed on the revision before them and its end Tag on the one it arrives at, so 'restore Before:ChangeOrder:uuid' undoes it whether it landed as one revision or as one per source revision. With restore the change order is being undone rather than promoted: the restore must be 'Before:ChangeOrder:' the same change order, the change order must have an AbortedReason -- undoing a change nobody has said is not coming is a race with whoever is still promoting it -- and a Unit the change order never marked is an error rather than passed over, since naming it says the Unit is part of the undoing. The first restore mints the change order's restore Tag and records it as RestoreTagID; every restore after that marks with the same Tag, which is what RestoredSpaceIDs is read off. A Unit the change order carried nothing for takes the restore Tag on the revision its start and end Tags are already on, and no revision is made. A Unit already carrying the restore Tag has had the change order taken back out of it and is passed over, since undoing one in a Unit happens once as promoting it into one does -- so the revisions a Unit has taken since it was undone are its own work rather than this undoing's to drop. Restoring also advances the merge pointers of the Links of the change order's UpdateType that follow the restored Unit onto the revision the restore made, so a later upgrade does not replay the change that was just taken out; the downstream Units are not restored with it, since each has to be restored and released on its own account.
`subgroup`	string	User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.
`include`	string	Comma-separated parts of the result to return in addition to the Unit: ConfigData for the configuration the operation produced, and MutationSources for what set each value in it. Neither is a field of a Unit, and both cost something to return, so they are returned only when named. A dry run stores nothing, so this is the only way to see what it would have produced.

Request Body

Content-Type: application/json

Schema: Unit

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`UnitCreateOrUpdateResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
422	Unable to update unit(s) due to configuration data problem	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Upload config data

PUT /space/{space_id}/unit/{unit_id}/data

Replace the config data of a unit. The request body is the configuration itself. This is the only way configuration reaches a Unit other than a clone, which copies it server-side: Data is not part of the Unit entity, so no metadata write can carry one or destroy one. Send If-Match with the DataHash a read served to make the write conditional on nobody having written first. Requires Edit permission.

Operation ID: UploadUnitData

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Query Parameters

Parameter	Type	Description
`last_change_description`	string	Human-readable description of this change, copied to the Revision it creates.
`include`	string	Comma-separated parts of the result to return in addition to the Unit: ConfigData for the configuration the operation produced, and MutationSources for what set each value in it. Neither is a field of a Unit, and both cost something to return, so they are returned only when named. A dry run stores nothing, so this is the only way to see what it would have produced.
`dry_run`	boolean	Dry run mode: return changed unit(s) but don't update configuration data
`protect`	boolean	Record the paths this operation writes as protected local overrides, so a later merge from upstream does not overwrite them. Without it the operation claims nothing: each written path keeps whatever the Unit already has for it, and a path with no history is left unprotected. It only ever adds protection -- re-opening a path is the /protection API (cub unit set-protection --unprotect). Has no effect with restore, which rewinds MutationSources to the restored Revision's stored values wholesale.
`clearance`	string	The classes of guarded reason this operation is cleared for, as a JSON Clearance -- a list of {Key, Operator, Values} requirements, where Operator is Exists, In, NotIn, or DoesNotExist. A path whose guards this does not cover is not written, and the withheld change is reported as a Guarded conflict. An absent or empty clearance clears nothing, which only matters for a Unit that has guards.
`guards`	string	The guards this operation records on the paths it writes, as a JSON object of guard key to value -- the reasons those paths hold what they hold, so a later operation must be cleared for them before overwriting. The guard analogue of protect: protect claims the paths, this says why. It only ever adds and overwrites the keys it names -- retiring a guard is the /guard API (cub unit set-guard --remove-guard).
`merge_base`	string	Merge base revision, which provides the base configuration data of the changes to merge. With merge_source, this is a revision of the merge source unit. With merge_external_source, this is a revision of the unit being updated and overrides the default selection of the latest MergeExternal revision. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`merge_external_source`	string	Identifier of the external source for merge-on-update. When set, computes mutations between the last MergeExternal revision and the provided data, then patches the current unit data with those mutations.
`merge_enable_subtraction`	boolean	Enable the subtraction (override-preservation) step of upgrade and merge_source. By default (false), the source patch is applied without subtraction and the target's local differences are preserved by the stored Mutation Protected values; set true to additionally subtract the target's local differences from the source patch. Has no effect on a self merge (merge_source=Self), where subtraction is always disabled.
`tag`	string	Tag ID to add to the head revision
`change_set_id`	string	Must match ChangeSetID of affected Units if config Data is changed unless in dry run mode
`subgroup`	string	User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.

Request Body

Content-Type: application/octet-stream

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	`UnitCreateOrUpdateResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk patch multiple units

PATCH /unit

Apply JSON merge patch to multiple units selected by query parameters

Operation ID: BulkPatchUnits

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`dry_run`	boolean	Dry run mode: return changed unit(s) but don't update configuration data
`protect`	boolean	Record the paths this operation writes as protected local overrides, so a later merge from upstream does not overwrite them. Without it the operation claims nothing: each written path keeps whatever the Unit already has for it, and a path with no history is left unprotected. It only ever adds protection -- re-opening a path is the /protection API (cub unit set-protection --unprotect). Has no effect with restore, which rewinds MutationSources to the restored Revision's stored values wholesale.
`clearance`	string	The classes of guarded reason this operation is cleared for, as a JSON Clearance -- a list of {Key, Operator, Values} requirements, where Operator is Exists, In, NotIn, or DoesNotExist. A path whose guards this does not cover is not written, and the withheld change is reported as a Guarded conflict. An absent or empty clearance clears nothing, which only matters for a Unit that has guards.
`guards`	string	The guards this operation records on the paths it writes, as a JSON object of guard key to value -- the reasons those paths hold what they hold, so a later operation must be cleared for them before overwriting. The guard analogue of protect: protect claims the paths, this says why. It only ever adds and overwrites the keys it names -- retiring a guard is the /guard API (cub unit set-guard --remove-guard).
`squash`	boolean	Merge the range as one rebased diff and record it as one Revision, instead of walking it. By default a merge replays: it takes the source's Revisions in order and, where a Revision records function invocations that can be re-executed, runs them against this Unit rather than rebasing their recorded paths onto it -- so a change lands where this Unit's own structure puts it -- and records each source Revision that has an effect here as a Revision of its own, carrying that Revision's change description, its own conflicts, and one Mutation per source Mutation. Squashing gives up both: the range arrives as a single rebased patch in a single Revision, which is what a merge did before replay existed. Accepted with upgrade, merge_source, and resolve of an UpgradeUnit or MergeUnits Link, and refused elsewhere, since there is no range to walk. A Link can ask for it standingly with its Squash field.
`upgrade`	boolean	Upgrade the unit to the latest version of its upstream unit
`restore`	string	Restore revision source. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`resolve`	string	Resolve Links from this (downstream) Unit to another (upstream) Unit, propagating what each Link's UpdateType says to propagate. Expects Link:, Link:, or Link:. Link: selects every Link from this Unit that can resolve; a where expression selects among those, evaluated against the Links themselves (e.g. UpdateType = 'MergeUnits'), which is how to name one Link in a bulk operation, where a UUID cannot be. A Link with UpdateType None resolves nothing and is never selected. An AutoUpdate Link may be resolved by hand: it does what the queue would have done, and nothing when the Link is already level with its source.
`merge_source`	string	Merge source unit. Currently it must be a unit ID or 'Self'.
`merge_base`	string	Merge base revision, which provides the base configuration data of the changes to merge. With merge_source, this is a revision of the merge source unit. With merge_external_source, this is a revision of the unit being updated and overrides the default selection of the latest MergeExternal revision. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`merge_end`	string	Merge end revision of the merge source, which provides the final configuration of the changes to merge. Also accepted with upgrade and with resolve, where it names how far along the source to take the propagation; the default there is the source's head. Naming a ChangeSet or Tag that ends a change is what leaves a change still being made at the source behind. Supports: Named revisions ('HeadRevisionNum', 'LastReleasedRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'ChangeOrder:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LastReleasedRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected. 'ChangeOrder:uuid' selects the revision the change order ended at on this Unit and 'Before:ChangeOrder:uuid' the one before it began, which is what undoes a promotion however many revisions it made.
`merge_external_source`	string	Identifier of the external source for merge-on-update. When set, computes mutations between the last MergeExternal revision and the provided data, then patches the current unit data with those mutations.
`merge_enable_subtraction`	boolean	Enable the subtraction (override-preservation) step of upgrade and merge_source. By default (false), the source patch is applied without subtraction and the target's local differences are preserved by the stored Mutation Protected values; set true to additionally subtract the target's local differences from the source patch. Has no effect on a self merge (merge_source=Self), where subtraction is always disabled.
`where_mutation`	string	The specified string is an expression for the purpose of filtering the list of Mutations returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Mutation: BridgeWorkerID, CreatedAt, FunctionName, InvocationID, InvocationParams, LinkID, MergeBaseRevisionNum, MergeEndRevisionNum, MergeSourceID, MutationID, MutationNum, OrganizationID, ReplayOutcome, ReplayReason, RestoredRevisionNum, RevisionID, RevisionNum, SpaceID, Subgroup, TriggerID, UnitID, UpdatedAt, UpgradedFromUpstreamRevisionNum. Selects Mutations of this Unit whose paths the merge must not overwrite, unioned with the Protected values stored on the Unit's MutationSources. The whole string must be query-encoded.
`filter_mutation`	string	UUID of a Filter entity to apply to the Mutation list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Mutation). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`tag`	string	Tag ID to add to the head revision
`change_set_id`	string	Must match ChangeSetID of affected Units if config Data is changed unless in dry run mode
`change_order`	string	ChangeOrder to promote, with upgrade or resolve, or to undo, with restore. The change order fixed the range when it was created -- the interval on each source Unit, marked with its Tags -- so it supplies both ends of the merge and merge_end is refused alongside it. A Unit whose source the change order does not cover is passed over rather than failed, which is what lets a bulk upgrade name a whole Space and take only the Units the change is in. A Unit whose last merged revision is not where the change order starts is an error, since merging anyway would replay what it already has or skip what it does not, and with resolve a selected Link whose UpdateType the change order does not follow is an error too. The revisions the promotion creates carry the ChangeOrder, and its start Tag is placed on the revision before them and its end Tag on the one it arrives at, so 'restore Before:ChangeOrder:uuid' undoes it whether it landed as one revision or as one per source revision. With restore the change order is being undone rather than promoted: the restore must be 'Before:ChangeOrder:' the same change order, the change order must have an AbortedReason -- undoing a change nobody has said is not coming is a race with whoever is still promoting it -- and a Unit the change order never marked is an error rather than passed over, since naming it says the Unit is part of the undoing. The first restore mints the change order's restore Tag and records it as RestoreTagID; every restore after that marks with the same Tag, which is what RestoredSpaceIDs is read off. A Unit the change order carried nothing for takes the restore Tag on the revision its start and end Tags are already on, and no revision is made. A Unit already carrying the restore Tag has had the change order taken back out of it and is passed over, since undoing one in a Unit happens once as promoting it into one does -- so the revisions a Unit has taken since it was undone are its own work rather than this undoing's to drop. Restoring also advances the merge pointers of the Links of the change order's UpdateType that follow the restored Unit onto the revision the restore made, so a later upgrade does not replay the change that was just taken out; the downstream Units are not restored with it, since each has to be restored and released on its own account.
`subgroup`	string	User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.

Request Body

Content-Type: application/merge-patch+json

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `UnitCreateOrUpdateResponse`
207	Multi-Status: Mixed success and failure results	`application/json`	Array of `UnitCreateOrUpdateResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
422	Unable to patch unit(s) due to configuration data problem	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Delete Unit

DELETE /space/{space_id}/unit/{unit_id}

Delete Unit

Operation ID: DeleteUnit

Parameters

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	✓	Unique identifier for a space_id
`unit_id`	string	✓	Unique identifier for a unit_id

Responses

Status	Description	Content-Type	Schema
200	Response for successful delete operation	`application/json`	`DeleteResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
422	Unit could not be deleted.	`application/json`	`StandardErrorResponse`
423	Unable to delete the unit(s) due to an inflight operation on the unit(s)	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk delete multiple units

DELETE /unit

Delete multiple units selected by query parameters

Operation ID: BulkDeleteUnits

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. An attribute naming a list of other entities can be filtered on their attributes with a `` segment, as in `FromLink..Slug = 'upgrade-app'`, which holds when any element satisfies it. Without the `*` such a reference is an error, since it names no single value to compare. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LastReleasedRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LastReleasedRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.

Responses

Status	Description	Content-Type	Schema
200	OK	`application/json`	Array of `DeleteResponse`
207	Multi-Status: Mixed success and failure results	`application/json`	Array of `DeleteResponse`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
422	Unable to delete entities	`application/json`	`StandardErrorResponse`
423	Unable to delete entities due to a inflight operation using one or more of the entities	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Schemas

ApproveResponse

Properties

Property	Type	Required	Description
`Error`	`ResponseError`
`Message`	string
`Unit`	`Unit`

DeleteResponse

Response for successful delete operation

Properties

Property	Type	Required	Description
`Error`	`ResponseError`
`Message`	string		Response message.

ExtendedUnit

Unit with capability to extend additional related entities.

Properties

Property	Type	Description
`ApprovedBy`	Array of `User`	the users that have approved the latest revision of the config data.
`BridgeWorker`	`BridgeWorker`
`ChangeSet`	`ChangeSet`
`Error`	`ResponseError`
`FromLink`	Array of `Link`
`HeadMutation`	`Mutation`
`HeadRevision`	`Revision`
`LastReleasedRevision`	`Revision`
`LatestUnitEvent`	`UnitEvent`
`Organization`	`Organization`
`Space`	`Space`
`Target`	`Target`
`Unit`	`Unit`
`UpstreamSpace`	`Space`
`UpstreamUnit`	`Unit`
`View`	`View`
`ViewColumns`	Array of `ViewColumn`

MutationSourcesResponse

Properties

Property	Type	Required	Description
`MutationSources`	`ResourceMutationList`

StandardErrorResponse

Error response details.

Properties

Property	Type	Required	Description
`Code`	string		HTTP status code of the response.
`Message`	string		Message returned with the response.

Unit

Unit is the core unit of operation in ConfigHub. It contains a blob of configuration Data of a single supported Toolchain Type (configuration format). This blob is typically a text document that contains a collection of Kubernetes or infrastructure resources, or an application configuration file. Applying / deploying or destroying the configuration happens as a single transaction from ConfigHub's perspective. In reality, it is most often a multi-step workflow performed by the underlying configuration / deployment tool. The resources must belong to a single infrastructure provider and the actuation mechanism must be able to resolve references and ordering dependencies among the resources within the document. For example, if one resource needs to be fully provisioned to provide input to another resource, then the actuation code is responsible for handling this. Revisions store historical copies of the configuration data. Configuration data can be restored from prior Revisions. Units can also be cloned to create new variants of a configuration.

Properties

Property	Type	Required	Description
`Annotations`	object		An optional map of Annotation key/value pairs for tools to attach information to entities.
`ApplyGates`	object		A map of "//" to true of Triggers invoking validating functions that did not pass on the latest configuration data. These block Apply operations.
`ApplyWarnings`	object		A map of "//" to true of Triggers with Warn=true invoking validating functions that did not pass on the latest configuration data. These do not block Apply operations.
`ApprovedBy`	Array of `UUID`		The users that have approved the latest revision of the config data for the Unit.
`BridgeWorkerID`	string (uuid)		ID of the BridgeWorker from the Target assigned to this Unit.
`ChangeSetID`	string (uuid)		Unique identifier for the ChangeSet to which the current Revision belongs. Optional. Units are not required to belong to ChangeSets.
`Conflicts`	`MutationConflictList`
`CreatedAt`	string (date-time)		The timestamp when the entity was created in "2023-01-01T12:00:00Z" format.
`CursorID`	integer (int64)		An auto-incrementing sequence number used for pagination.
`DataHash`	string		The SHA256 hash of the configuration data, encoded as hexadecimal. It is also the ETag the data endpoint serves, so a caller that listed Units can ask for a body conditionally without fetching it first.
`DataSize`	integer (int64)		The size of the configuration data in bytes. The configuration itself is not part of the Unit; read it from the data endpoint.
`DeleteGates`	object		An optional set of gates that, if any is present, will block deletion.
`DestroyGates`	object		An optional set of gates that, if any is present, will block destroy operations.
`DisplayName`	string		Friendly name for the entity.
`EntityType`	string		The type of entity.
`FromLinkID`	Array of `UUID`		IDs of Links originating from this Unit.
`HeadMutationNum`	integer (int64)		Sequence number the head Mutation.
`HeadRevisionNum`	integer (int64)		Sequence number the head Revision.
`HeadUnitActionNum`	integer (int64)		Sequence number of the head unit action (queued operation).
`HeadUnitEventNum`	integer (int64)		Sequence number of the head unit event.
`Labels`	object		An optional map of Label key/value pairs to specify identifying attributes of entities for the purpose of grouping and filtering them.
`LastChangeDescription`	string		LastChangeDescription is a human-readable description of the last change. This description is copied to the new Revision when the Data is changed.
`LastReleasedRevisionNum`	integer (int64)		Sequence number of the last Revision published in a Release. 0 if no Revision has been released.
`NeededPaths`	Array of `AttributeValue`		Attribute paths that this Unit needs from upstream Units via NeedsProvides Links. Computed from get-needed and stored on data updates.
`OrganizationID`	string (uuid)		Unique identifier for an organization.
`PathAnnotations`	`PathAnnotationList`
`ProvidedPaths`	Array of `AttributeInfo`		Attribute paths that this Unit provides to downstream Units via NeedsProvides Links. Computed from get-provided and stored on data updates.
`ProviderType`	string		ProviderType identifies which bridge to use in the case that the Target supports multiple ProviderTypes.
`Slug`	string	✓	Unique URL-safe identifier for the entity.
`SpaceID`	string (uuid)		Unique identifier for a space.
`SpaceSlug`	string		Slug of the Space this entity belongs to. (readonly)
`TargetID`	string (uuid)		TargetID is the identifier of the target this unit is associated with. This defines where the configuration will be applied. It must be set to a valid Target before the Unit can be Applied, Destroyed, Imported, or Refreshed.
`TargetOptions`	object		Bridge option values set per-Unit, merged with the Target's Options when sending to the bridge worker (Target's Options take precedence on overlap). The options must be predefined by the ConfigType in the BridgeWorker.
`ToolchainType`	string	✓	ToolchainType specifies the type of toolchain for this unit. Possible values include "Kubernetes/YAML", "AppConfig/Properties", "AppConfig/YAML", "AppConfig/TOML", "AppConfig/INI", "AppConfig/JSON", "AppConfig/Env", "AppConfig/Text", "ConfigHub/YAML".
`UnitID`	string (uuid)		Unique identifier for a Unit.
`UpdatedAt`	string (date-time)		The timestamp when the entity was last updated in "2023-01-01T12:00:00Z" format.
`UpstreamRevisionNum`	integer (int64)		Sequence number for the Revision of the Unit this unit was cloned from, or 0. This is updated to the upstream Unit's head revision number when the Unit is upgraded. To change this revision number, change the UpstreamLastMergedRevisionNum of the corresponding Link of UpdateType UpgradeUnit from this Unit to the upstream Unit.
`UpstreamSpaceID`	string (uuid)		Unique identifier for the Space of the Unit this unit was cloned from, if any.
`UpstreamUnitID`	string (uuid)		Unique identifier for Unit this unit was cloned from, if any. To change or remove the upstream unit, change or delete the corresponding Link of UpdateType UpgradeUnit from this Unit to the upstream Unit.
`ValidationResults`	object		A map from gate/warning name to the list of validation results that caused the gate or warning.
`Values`	object		Map from "/" to the first output Value with that attribute name of the function invocation specified by the Trigger.
`Version`	integer (int64)		An entity-specific sequence number used for optimistic concurrency control. The value read must be sent in calls to Update.

UnitActionResponse

Properties

Property	Type	Required	Description
`Action`	`QueuedOperation`
`Error`	`ResponseError`

UnitConflictsRequest

Properties

Property	Type	Description
`Action`	string	Apply re-applies the withheld change; Dismiss drops the conflict without changing the configuration data
`DryRun`	boolean	Report what the request would do without writing anything. The response carries the Unit as it would be.
`Select`	Array of `UnitConflictSelector`	Which outstanding conflicts to act on. Empty acts on all of them.

UnitConflictsResponse

Properties

Property	Type	Description
`Applied`	integer	Number of conflicts whose withheld change was applied
`Conflicts`	`MutationConflictList`
`Dismissed`	integer	Number of conflicts dropped without changing the configuration data
`Error`	`ResponseError`
`Unit`	`Unit`

UnitCreateOrUpdateResponse

Properties

Property	Type	Description
`ConfigData`	string	The configuration the operation produced; returned when include names ConfigData.
`Conflicts`	`MutationConflictList`
`Error`	`ResponseError`
`Links`	Array of `LinkCreateOrUpdateResponse`
`MutationSources`	`ResourceMutationList`
`Unit`	`Unit`

UnitData

Properties

Property	Type	Description
`Data`	string	The configuration data.
`DataHash`	string	SHA256 of the configuration data, which is also the ETag the single-Unit data endpoint serves.
`DataSize`	integer (int64)	Size of the configuration data in bytes.
`Slug`	string	Slug of the Unit.
`SpaceID`	string (uuid)	Unique identifier of the Space the Unit belongs to.
`SpaceSlug`	string	Slug of the Space the Unit belongs to.
`UnitID`	string (uuid)	Unique identifier of the Unit.

UnitExtended

Properties

Property	Type	Required	Description
`ApprovedByUsers`	Array of string
`FromLinks`	Array of `Link`
`ToLinks`	Array of `Link`
`Unit`	`Unit`

UnitGuardRequest

Properties

Property	Type	Required	Description
`Clearance`	`Clearance`
`ResourceGuards`	Array of `ResourceGuards`		Per-resource guard edits to apply to the Unit's PathAnnotations

UnitGuardResponse

Properties

Property	Type	Required	Description
`PathAnnotations`	`PathAnnotationList`

UnitMutationSources

Properties

Property	Type	Description
`DataHash`	string	SHA256 of the configuration data the MutationSources describe.
`MutationSources`	`ResourceMutationList`
`Slug`	string	Slug of the Unit.
`SpaceID`	string (uuid)	Unique identifier of the Space the Unit belongs to.
`SpaceSlug`	string	Slug of the Space the Unit belongs to.
`UnitID`	string (uuid)	Unique identifier of the Unit.

UnitProtectionRequest

Properties

Property	Type	Required	Description
`ResourceProtection`	Array of `ResourceProtection`		Per-resource Protected edits to apply to the Unit's MutationSources

UnitProtectionResponse

Properties

Property	Type	Required	Description
`Error`	`ResponseError`
`MutationSources`	`ResourceMutationList`

UnitTagRequest

Properties

Property	Type	Required	Description
`Revision`	string		Which Unit revision to tag: a named revision ('HeadRevisionNum', 'LastReleasedRevisionNum'), a revision number, an entity reference ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'), any of those prefixed with 'Before:', or 'Remove' to remove the tag from the unit
`TagID`	string (uuid)

UnitTagResponse

Properties

Property	Type	Required	Description
`Error`	`ResponseError`
`Message`	string