Unit

Unit is the core unit of operation in ConfigHub. It contains a blob of configuration Data of a single supported Config 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_diff	Get the difference between two Revisions 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}/diff	Get the difference between two Revisions of a Unit
GET	/space/{space_id}/unit/{unit_id}/mutation_sources	Get mutation sources
POST	/diff	Get the difference between two configurations
POST	/space/{space_id}/unit	Create Unit
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/cancel	Bulk cancel unit operations
POST	/unit/move	Move units to another space
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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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 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, fields named by order_by, and fields read by the columns of the View named by view 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.
include_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
view	string		UUID of a View whose columns to compute for each Unit, returned as ViewColumns. The View must be in the same Organization as the user credentials, and be a View of Unit: its Of, or the From of its Filter, must be Unit. If the View has a Filter, the Filter selects the entities as the filter parameter does, so the two may not both be specified. The related entities and fields the View's columns read are included and selected automatically, so neither include nor select has to name them.
limit	integer		Maximum number of Unit entities to return. If not specified, all matching entities are returned. Values greater than 1000 are rejected with 400. When there may be more entities, the response has a ConfigHub-Continue header to pass as the continue parameter of the next request.
order_by	string		Comma-separated list of fields to sort Unit results by, each in the form 'ASC|DESC:FieldName' or just 'FieldName'. Field names are case-sensitive and PascalCase, as in the JSON encoding. Sort direction defaults to ASC when the 'DIRECTION:' prefix is omitted. Supported attributes for ordering Unit: ChangeSetID, CreatedAt, DataHash, DisplayName, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamUnitID. Example: 'DESC:CreatedAt' or 'DisplayName,DESC:CreatedAt'. Results are ordered by the Unit's ID after the fields named, and by the ID alone if none are. The whole string must be query-encoded.
continue	string		The token from the ConfigHub-Continue header of the previous page, to return the Unit entities after it. The request's other parameters, except limit, must be the same as those of the request that returned the token. Keep reading until a response has no such header: a page can hold fewer entities than the limit, or none, and still be followed by more.
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 .\| splits the path: the left side selects, and the right side is a property of what was selected. On the right side of a .\|, and only there, != is true when the property is absent: spec.containers.*.\|image != 'nginx' selects the containers and asks that none of their images be nginx, which a container with no image satisfies. Everywhere else a path that is not present is not a match, != included. 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_data_engine	string		Which engine answers where_data and resource_type: sql (the default) evaluates the expression against the stored resource projection in a single query, falling back to the function engine for the expressions it cannot translate; function invokes the where-filter function on each candidate Unit, reading every one's configuration; shadow runs both, answers with function, and logs any disagreement. Temporary: function is the escape hatch for one release, after which this parameter goes away.
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.

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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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 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, fields named by order_by, and fields read by the columns of the View named by view 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.
include_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
view	string		UUID of a View whose columns to compute for each Unit, returned as ViewColumns. The View must be in the same Organization as the user credentials, and be a View of Unit: its Of, or the From of its Filter, must be Unit. If the View has a Filter, the Filter selects the entities as the filter parameter does, so the two may not both be specified. The related entities and fields the View's columns read are included and selected automatically, so neither include nor select has to name them.
limit	integer		Maximum number of Unit entities to return. If not specified, all matching entities are returned. Values greater than 1000 are rejected with 400. When there may be more entities, the response has a ConfigHub-Continue header to pass as the continue parameter of the next request.
order_by	string		Comma-separated list of fields to sort Unit results by, each in the form 'ASC|DESC:FieldName' or just 'FieldName'. Field names are case-sensitive and PascalCase, as in the JSON encoding. Sort direction defaults to ASC when the 'DIRECTION:' prefix is omitted. Supported attributes for ordering Unit: ChangeSetID, CreatedAt, DataHash, DisplayName, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamUnitID. Example: 'DESC:CreatedAt' or 'DisplayName,DESC:CreatedAt'. Results are ordered by the Unit's ID after the fields named, and by the ID alone if none are. The whole string must be query-encoded.
continue	string		The token from the ConfigHub-Continue header of the previous page, to return the Unit entities after it. The request's other parameters, except limit, must be the same as those of the request that returned the token. Keep reading until a response has no such header: a page can hold fewer entities than the limit, or none, and still be followed by more.
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 .\| splits the path: the left side selects, and the right side is a property of what was selected. On the right side of a .\|, and only there, != is true when the property is absent: spec.containers.*.\|image != 'nginx' selects the containers and asks that none of their images be nginx, which a container with no image satisfies. Everywhere else a path that is not present is not a match, != included. 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_data_engine	string		Which engine answers where_data and resource_type: sql (the default) evaluates the expression against the stored resource projection in a single query, falling back to the function engine for the expressions it cannot translate; function invokes the where-filter function on each candidate Unit, reading every one's configuration; shadow runs both, answers with function, and logs any disagreement. Temporary: function is the escape hatch for one release, after which this parameter goes away.
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.

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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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 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, fields named by order_by, and fields read by the columns of the View named by view 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.
include_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
view	string		UUID of a View of Unit. Its Filter selects the Units as the filter parameter does, so the two may not both be specified.
limit	integer		Maximum number of Unit entities to return. If not specified, all matching entities are returned. Values greater than 1000 are rejected with 400. When there may be more entities, the response has a ConfigHub-Continue header to pass as the continue parameter of the next request.
order_by	string		Comma-separated list of fields to sort Unit results by, each in the form 'ASC|DESC:FieldName' or just 'FieldName'. Field names are case-sensitive and PascalCase, as in the JSON encoding. Sort direction defaults to ASC when the 'DIRECTION:' prefix is omitted. Supported attributes for ordering Unit: ChangeSetID, CreatedAt, DataHash, DisplayName, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamUnitID. Example: 'DESC:CreatedAt' or 'DisplayName,DESC:CreatedAt'. Results are ordered by the Unit's ID after the fields named, and by the ID alone if none are. The whole string must be query-encoded.
continue	string		The token from the ConfigHub-Continue header of the previous page, to return the Unit entities after it. The request's other parameters, except limit, must be the same as those of the request that returned the token. Keep reading until a response has no such header: a page can hold fewer entities than the limit, or none, and still be followed by more.
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 .\| splits the path: the left side selects, and the right side is a property of what was selected. On the right side of a .\|, and only there, != is true when the property is absent: spec.containers.*.\|image != 'nginx' selects the containers and asks that none of their images be nginx, which a container with no image satisfies. Everywhere else a path that is not present is not a match, != included. 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_data_engine	string		Which engine answers where_data and resource_type: sql (the default) evaluates the expression against the stored resource projection in a single query, falling back to the function engine for the expressions it cannot translate; function invokes the where-filter function on each candidate Unit, reading every one's configuration; shadow runs both, answers with function, and logs any disagreement. Temporary: function is the escape hatch for one release, after which this parameter goes away.
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.

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 difference between two Revisions of many Units across spaces

GET /unit_diff

Returns, for every Unit the where clause selects, across every Space in the organization, what changed in its configuration between the Revision from names and the Revision to names, path by path with the values on both sides. This is the bulk counterpart of the single-Unit diff subresource. from and to must each pick out a Revision in every Unit: HeadRevisionNum, LastReleasedRevisionNum, Tag:, ChangeSet: or ChangeOrder:, optionally prefixed with Before:. A Unit with no Revision a side names is absent on that side, and its diff runs against nothing. Scope it to one Space with a where clause.

Operation ID: SearchUnitDiff

Parameters

Query Parameters

Parameter	Type	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
view	string		UUID of a View of Unit. Its Filter selects the Units as the filter parameter does, so the two may not both be specified.
limit	integer		Maximum number of Unit entities to return. If not specified, all matching entities are returned. Values greater than 1000 are rejected with 400. When there may be more entities, the response has a ConfigHub-Continue header to pass as the continue parameter of the next request.
order_by	string		Comma-separated list of fields to sort Unit results by, each in the form 'ASC|DESC:FieldName' or just 'FieldName'. Field names are case-sensitive and PascalCase, as in the JSON encoding. Sort direction defaults to ASC when the 'DIRECTION:' prefix is omitted. Supported attributes for ordering Unit: ChangeSetID, CreatedAt, DataHash, DisplayName, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamUnitID. Example: 'DESC:CreatedAt' or 'DisplayName,DESC:CreatedAt'. Results are ordered by the Unit's ID after the fields named, and by the ID alone if none are. The whole string must be query-encoded.
continue	string		The token from the ConfigHub-Continue header of the previous page, to return the Unit entities after it. The request's other parameters, except limit, must be the same as those of the request that returned the token. Keep reading until a response has no such header: a page can hold fewer entities than the limit, or none, and still be followed by more.
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 .\| splits the path: the left side selects, and the right side is a property of what was selected. On the right side of a .\|, and only there, != is true when the property is absent: spec.containers.*.\|image != 'nginx' selects the containers and asks that none of their images be nginx, which a container with no image satisfies. Everywhere else a path that is not present is not a match, != included. 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_data_engine	string		Which engine answers where_data and resource_type: sql (the default) evaluates the expression against the stored resource projection in a single query, falling back to the function engine for the expressions it cannot translate; function invokes the where-filter function on each candidate Unit, reading every one's configuration; shadow runs both, answers with function, and logs any disagreement. Temporary: function is the escape hatch for one release, after which this parameter goes away.
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.
from	string		The Revision on the From side: a number, a Revision ID, HeadRevisionNum, LastReleasedRevisionNum, Tag:, ChangeSet:, or ChangeOrder:, any of them optionally prefixed with Before:.
to	string		The Revision on the To side, in the same syntax as from.
include	string		Comma-separated: Attribution to attach to each changed path the To side's MutationSources entry, which says what set the new value, Unchanged to also list resources with no changes, and Context to also list, within each changed resource, the unchanged paths around the changes: every unchanged child of each map or array that holds a change, up to the resource, as ChangeType None. Supported values: Attribution, Unchanged, Context.
where_resource	string		Limit the diff to the resources this where expression selects on either side.

Responses

Status	Description	Content-Type	Schema
200	OK	application/json	Array of UnitDiff
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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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 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, fields named by order_by, and fields read by the columns of the View named by view 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.
include_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
view	string		UUID of a View of Unit. Its Filter selects the Units as the filter parameter does, so the two may not both be specified.
limit	integer		Maximum number of Unit entities to return. If not specified, all matching entities are returned. Values greater than 1000 are rejected with 400. When there may be more entities, the response has a ConfigHub-Continue header to pass as the continue parameter of the next request.
order_by	string		Comma-separated list of fields to sort Unit results by, each in the form 'ASC|DESC:FieldName' or just 'FieldName'. Field names are case-sensitive and PascalCase, as in the JSON encoding. Sort direction defaults to ASC when the 'DIRECTION:' prefix is omitted. Supported attributes for ordering Unit: ChangeSetID, CreatedAt, DataHash, DisplayName, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, LastChangeDescription, LastReleasedRevisionNum, OrganizationID, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamUnitID. Example: 'DESC:CreatedAt' or 'DisplayName,DESC:CreatedAt'. Results are ordered by the Unit's ID after the fields named, and by the ID alone if none are. The whole string must be query-encoded.
continue	string		The token from the ConfigHub-Continue header of the previous page, to return the Unit entities after it. The request's other parameters, except limit, must be the same as those of the request that returned the token. Keep reading until a response has no such header: a page can hold fewer entities than the limit, or none, and still be followed by more.
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 .\| splits the path: the left side selects, and the right side is a property of what was selected. On the right side of a .\|, and only there, != is true when the property is absent: spec.containers.*.\|image != 'nginx' selects the containers and asks that none of their images be nginx, which a container with no image satisfies. Everywhere else a path that is not present is not a match, != included. 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_data_engine	string		Which engine answers where_data and resource_type: sql (the default) evaluates the expression against the stored resource projection in a single query, falling back to the function engine for the expressions it cannot translate; function invokes the where-filter function on each candidate Unit, reading every one's configuration; shadow runs both, answers with function, and logs any disagreement. Temporary: function is the escape hatch for one release, after which this parameter goes away.
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.

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 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, fields named by order_by, and fields read by the columns of the View named by view 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 the difference between two Revisions of a Unit

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

Returns what changed in a Unit's configuration between two Revisions, path by path, with the values on both sides. Array elements are matched by merge key and resources across renames, as merges match them. from and to take the Revision selectors unit update --restore accepts; to defaults to HeadRevisionNum and from to the Revision before to, so a request with neither answers what the last change did.

Operation ID: GetUnitDiff

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
from	string		The Revision on the From side: a number, a Revision ID, HeadRevisionNum, LastReleasedRevisionNum, Tag:, ChangeSet:, or ChangeOrder:, any of them optionally prefixed with Before:.
to	string		The Revision on the To side, in the same syntax as from.
include	string		Comma-separated: Attribution to attach to each changed path the To side's MutationSources entry, which says what set the new value, Unchanged to also list resources with no changes, and Context to also list, within each changed resource, the unchanged paths around the changes: every unchanged child of each map or array that holds a change, up to the resource, as ChangeType None. Supported values: Attribution, Unchanged, Context.
where_resource	string		Limit the diff to the resources this where expression selects on either side.

Responses

Status	Description	Content-Type	Schema
200	OK	application/json	UnitDiff
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

---

Get the difference between two configurations

POST /diff

Returns what changed from one configuration to another, path by path with the values on both sides. Each side is a Unit, at a Revision or its head, or configuration given inline, such as a local file or an unsaved edit. The two sides may be Units in different Spaces, and must be of one toolchain. It changes nothing; it is a POST because inline configuration does not fit in a query string.

Operation ID: DiffConfigurations

Parameters

Query Parameters

Parameter	Type	Required	Description
include	string		Comma-separated: Attribution to attach to each changed path the To side's MutationSources entry, which says what set the new value, Unchanged to also list resources with no changes, and Context to also list, within each changed resource, the unchanged paths around the changes: every unchanged child of each map or array that holds a change, up to the resource, as ChangeType None. Supported values: Attribution, Unchanged, Context.
where_resource	string		Limit the diff to the resources this where expression selects on either side.

Request Body

Content-Type: application/json

Schema: DiffRequest

Responses

Status	Description	Content-Type	Schema
200	OK	application/json	DiffResult
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

---

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	Required	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, MutationSources for what set each value in it, and Diff for what the operation changed, path by path with the values on both sides. None is a field of a Unit, and each costs 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. Supported values: ConfigData, MutationSources, Diff.
dry_run	boolean		If true, report what the write would do without doing it: the write runs, including every check it makes, and is then rolled back. The response is the one the write would return, with the entities as they would be written. An entity a dry run creates is given an ID that the real create will not reuse.

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

---

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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
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 ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. A write also accepts the parts of its result: ConfigData for the configuration the operation produced, MutationSources for what set each value in it, and Diff for what the operation changed, path by path with the values on both sides. None is a field of a Unit, and each costs 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. Supported values: ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID, ConfigData, MutationSources, Diff. The whole string must be query-encoded.
limit	integer		Maximum number of Unit entities to act on, in ID order. A request that names limit or continue also stops when it runs short of time, and returns a ConfigHub-Continue header to pass as the continue parameter of the next request; keep sending requests until a response has none. If neither is specified, the request acts on every selected entity.
continue	string		The token from the ConfigHub-Continue header of the previous request, to act on the Unit entities after the last one it acted on. The request's other parameters, except limit, must be the same as those of the request that returned the token.
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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, BackingUnitID, ComponentID, CreatedAt, DeleteGates, DisplayName, HiddenReason, Labels, OrganizationID, Permissions, ReleaseTargetID, Slug, SpaceID, TriggerFilterID, TriggerHash, TriggerIDs, UpdatedAt, UpstreamSpaceID. 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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, BackingUnitID, Bindings, Clearance, CreatedAt, DeleteGates, DisplayName, DownstreamLastMergedRevisionNum, DownstreamPaths, DownstreamSetters, FromUnitID, Guards, Hash, HiddenReason, Labels, LinkID, ManualBindings, MergeEnableSubtraction, OrganizationID, Permissions, Protect, Slug, SpaceID, Squash, Stale, ToSpaceID, ToUnitID, TransformInvocationID, UpdateType, UpdatedAt, UpstreamGetters, UpstreamLastMergedRevisionNum, UpstreamLinkID, UpstreamPaths, 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).
dry_run	boolean		If true, report what the write would do without doing it: the write runs, including every check it makes, and is then rolled back. The response is the one the write would return, with the entities as they would be written. An entity a dry run creates is given an ID that the real create will not reuse.

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 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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
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 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

---

Move units to another space

POST /unit/move

Move the selected Units, and the Links from them, to another Space. Requires Manage permission on each Unit and CreateChildren permission on the destination Space. Every check runs over the whole selection before anything is moved.

Operation ID: BulkMoveUnits

Parameters

Query Parameters

Parameter	Type	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
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 ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
dry_run	boolean		Report what the move would do, and what would stop it, without moving anything

Request Body

Content-Type: application/json

Schema: UnitMoveRequest

Responses

Status	Description	Content-Type	Schema
200	OK	application/json	Array of UnitMoveResponse
207	Multi-Status: nothing was moved, or some Units moved and others did not	application/json	Array of UnitMoveResponse
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 tag multiple units

POST /unit/tag

Attach tags to specified unit revisions

Operation ID: BulkTagUnits

Parameters

Query Parameters

Parameter	Type	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
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 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
422	Moving a change order's release tag to a Revision a release of the change could not deliver: before its end tag or the last released Revision, with validation errors, or in a Space where a release has been published at it	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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, FunctionInvocation.Arguments, FunctionInvocation.Clearance, FunctionInvocation.FunctionName, FunctionInvocation.Guards, FunctionInvocation.WhereResource, FunctionName, HiddenReason, InvocationID, InvocationParams, LinkID, MergeBaseRevisionNum, MergeEndRevisionNum, MergeSourceID, MutationID, MutationNum, OrganizationID, ReplayOutcome, ReplayReason, RestoredRevisionNum, RevisionID, RevisionNum, SpaceID, Subgroup, TriggerID, UnitID, UpdatedAt. 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 past where the change order starts is an error, since merging anyway would replay what it already has; one that is short of it is handled as prior_revisions says. 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.
prior_revisions	string		With change_order, when promoting it by upgrade or resolve: what to do for a Unit whose last merged revision of its source is before the revision the change order starts at there -- typically because a Link in the source's Space, such as a TransformPaths Link, wrote revisions after the Unit last merged, and those revisions are not the change order's. Include (the default) merges them first, walking them one source revision at a time even with squash, as revisions that do not carry the change order, and places the change order's start Tag on the revision they leave, so 'restore Before:ChangeOrder:uuid' keeps them. Skip merges only the change order's range, as though the Unit's merge pointer had already been advanced to the change order's start, so what those revisions changed does not reach the Unit. Error refuses, naming the Unit, the Link, and each of those revisions with the operation and Link that made it. All merges them as Include does. A Unit that has already merged past the change order's start is an error whatever this says. Defaults to the change order's PriorRevisions.
subgroup	string		User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.
force_close	boolean		Close a ChangeSet a ChangeWorkflow governs although the gates of the workflow's Final do not hold. Applies to a write that clears a Unit's ChangeSetID, which closes its ChangeSet. Requires force_reason, and Edit permission on the ChangeSet, whose CloseOverride records the override.
force_reason	string		Why a ChangeSet's gates are overridden; required with force_close.
include	string		Comma-separated parts of the result to return in addition to the Unit: ConfigData for the configuration the operation produced, MutationSources for what set each value in it, and Diff for what the operation changed, path by path with the values on both sides. None is a field of a Unit, and each costs 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. Supported values: ConfigData, MutationSources, Diff.

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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, FunctionInvocation.Arguments, FunctionInvocation.Clearance, FunctionInvocation.FunctionName, FunctionInvocation.Guards, FunctionInvocation.WhereResource, FunctionName, HiddenReason, InvocationID, InvocationParams, LinkID, MergeBaseRevisionNum, MergeEndRevisionNum, MergeSourceID, MutationID, MutationNum, OrganizationID, ReplayOutcome, ReplayReason, RestoredRevisionNum, RevisionID, RevisionNum, SpaceID, Subgroup, TriggerID, UnitID, UpdatedAt. 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 past where the change order starts is an error, since merging anyway would replay what it already has; one that is short of it is handled as prior_revisions says. 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.
prior_revisions	string		With change_order, when promoting it by upgrade or resolve: what to do for a Unit whose last merged revision of its source is before the revision the change order starts at there -- typically because a Link in the source's Space, such as a TransformPaths Link, wrote revisions after the Unit last merged, and those revisions are not the change order's. Include (the default) merges them first, walking them one source revision at a time even with squash, as revisions that do not carry the change order, and places the change order's start Tag on the revision they leave, so 'restore Before:ChangeOrder:uuid' keeps them. Skip merges only the change order's range, as though the Unit's merge pointer had already been advanced to the change order's start, so what those revisions changed does not reach the Unit. Error refuses, naming the Unit, the Link, and each of those revisions with the operation and Link that made it. All merges them as Include does. A Unit that has already merged past the change order's start is an error whatever this says. Defaults to the change order's PriorRevisions.
subgroup	string		User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.
force_close	boolean		Close a ChangeSet a ChangeWorkflow governs although the gates of the workflow's Final do not hold. Applies to a write that clears a Unit's ChangeSetID, which closes its ChangeSet. Requires force_reason, and Edit permission on the ChangeSet, whose CloseOverride records the override.
force_reason	string		Why a ChangeSet's gates are overridden; required with force_close.
include	string		Comma-separated parts of the result to return in addition to the Unit: ConfigData for the configuration the operation produced, MutationSources for what set each value in it, and Diff for what the operation changed, path by path with the values on both sides. None is a field of a Unit, and each costs 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. Supported values: ConfigData, MutationSources, Diff.

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 the configuration still being that one. 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	Required	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, MutationSources for what set each value in it, and Diff for what the operation changed, path by path with the values on both sides. None is a field of a Unit, and each costs 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. Supported values: ConfigData, MutationSources, Diff.
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.

Header Parameters

Parameter	Type	Required	Description
If-Match	string		The DataHash of the configuration this write replaces, as the ETag a read of the Unit's data served it (quoted) or bare. The write is refused with 409 Conflict when the Unit's configuration is not that one, so an edit made from one Unit's configuration, or before somebody else's write, cannot land over another. Omitted, the write is unconditional.

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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
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 ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. A write also accepts the parts of its result: ConfigData for the configuration the operation produced, MutationSources for what set each value in it, and Diff for what the operation changed, path by path with the values on both sides. None is a field of a Unit, and each costs 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. Supported values: ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID, ConfigData, MutationSources, Diff. The whole string must be query-encoded.
limit	integer		Maximum number of Unit entities to act on, in ID order. A request that names limit or continue also stops when it runs short of time, and returns a ConfigHub-Continue header to pass as the continue parameter of the next request; keep sending requests until a response has none. If neither is specified, the request acts on every selected entity.
continue	string		The token from the ConfigHub-Continue header of the previous request, to act on the Unit entities after the last one it acted on. The request's other parameters, except limit, must be the same as those of the request that returned the token.
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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, FunctionInvocation.Arguments, FunctionInvocation.Clearance, FunctionInvocation.FunctionName, FunctionInvocation.Guards, FunctionInvocation.WhereResource, FunctionName, HiddenReason, InvocationID, InvocationParams, LinkID, MergeBaseRevisionNum, MergeEndRevisionNum, MergeSourceID, MutationID, MutationNum, OrganizationID, ReplayOutcome, ReplayReason, RestoredRevisionNum, RevisionID, RevisionNum, SpaceID, Subgroup, TriggerID, UnitID, UpdatedAt. 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 past where the change order starts is an error, since merging anyway would replay what it already has; one that is short of it is handled as prior_revisions says. 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.
prior_revisions	string		With change_order, when promoting it by upgrade or resolve: what to do for a Unit whose last merged revision of its source is before the revision the change order starts at there -- typically because a Link in the source's Space, such as a TransformPaths Link, wrote revisions after the Unit last merged, and those revisions are not the change order's. Include (the default) merges them first, walking them one source revision at a time even with squash, as revisions that do not carry the change order, and places the change order's start Tag on the revision they leave, so 'restore Before:ChangeOrder:uuid' keeps them. Skip merges only the change order's range, as though the Unit's merge pointer had already been advanced to the change order's start, so what those revisions changed does not reach the Unit. Error refuses, naming the Unit, the Link, and each of those revisions with the operation and Link that made it. All merges them as Include does. A Unit that has already merged past the change order's start is an error whatever this says. Defaults to the change order's PriorRevisions.
subgroup	string		User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.
force_close	boolean		Close a ChangeSet a ChangeWorkflow governs although the gates of the workflow's Final do not hold. Applies to a write that clears a Unit's ChangeSetID, which closes its ChangeSet. Requires force_reason, and Edit permission on the ChangeSet, whose CloseOverride records the override.
force_reason	string		Why a ChangeSet's gates are overridden; required with force_close.

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

Query Parameters

Parameter	Type	Required	Description
detach	boolean		If true, remove the references to the deleted entities from entities the request does not delete, instead of refusing the delete while any remain. References that cannot be removed still refuse it. For a Space, applies to everything the recursive delete removes.

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 is still in use: it has DeleteGates, or other entities still reference it. Or 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	Required	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 FromLinkID ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(FromLinkID) > 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, ChangeSetID, Conflicts, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, HiddenReason, Labels, LastChangeDescription, LastReleasedRevisionNum, LinkFindings, NeededPaths, OrganizationID, Permissions, ProvidedPaths, ProviderType, Slug, SpaceID, TargetID, ToolchainType, UnitID, UpdatedAt, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, ValidationErrors, ValidationTriggerIDs, ValidationWarnings, ValueTriggerIDs, 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. Units never released can be found using LastReleasedRevisionNum = 0. Units with unreleased changes can be found with HeadRevisionNum > LastReleasedRevisionNum AND TargetID IS NOT NULL. 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_hidden	string		Hidden Unit entities, those with a HiddenReason, are left out of the results, or of what a bulk operation acts on, unless this names their HiddenReason. It is a comma-separated list of HiddenReasons, or * for all of them. A where clause naming the entities, by their Slug or ID with = or IN, or naming HiddenReason at all, also returns hidden entities it selects. ConfigHub/YAML Units, which hold the configuration of entities, are hidden with the HiddenReason BackingUnit.
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 ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastReleasedRevisionNum, OrganizationID, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
limit	integer		Maximum number of Unit entities to act on, in ID order. A request that names limit or continue also stops when it runs short of time, and returns a ConfigHub-Continue header to pass as the continue parameter of the next request; keep sending requests until a response has none. If neither is specified, the request acts on every selected entity.
continue	string		The token from the ConfigHub-Continue header of the previous request, to act on the Unit entities after the last one it acted on. The request's other parameters, except limit, must be the same as those of the request that returned the token.
detach	boolean		If true, remove the references to the deleted entities from entities the request does not delete, instead of refusing the delete while any remain. References that cannot be removed still refuse it. For a Space, applies to everything the recursive delete removes.

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 is still in use: it has DeleteGates, or other entities still reference it. Or data has changed since last read.	application/json	StandardErrorResponse
422	Unable to delete entity	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

DeleteResponse

Response for successful delete operation

Properties

Property	Type	Required	Description
Error			Error information if the delete operation failed.
Message	string		Response message.

DiffRequest

Properties

Property	Type	Required	Description
From			The configuration the diff runs from
To			The configuration the diff runs to

DiffResult

Properties

Property	Type	Required	Description
Diff			What changed from the From configuration to the To configuration
From			What the From side resolved to
To			What the To side resolved to

ExtendedUnit

Unit with capability to extend additional related entities.

Properties

Property	Type	Required	Description
ChangeSet	ChangeSet
Error	ResponseError
FromLink	Array of Link
HeadMutation			The Unit's current HeadMutation
HeadRevision			The Unit's current HeadRevision
LastReleasedRevision			The Unit's current LastReleasedRevision
LatestUnitEvent			The latest event that took place on the Unit.
Organization			The Organization the Unit belongs to.
Space			The Space the Unit belongs to.
Target			The Target the Unit has been configured to operate with.
Unit			The requested Unit of the operation.
UpstreamSpace			If this Unit is a clone, the Upstream Space the UpstreamUnit belongs to. Optional.
UpstreamUnit			If this Unit is a clone, the Upstream Unit it was cloned from. Optional.
ViewColumns	Array of ViewColumn		The values of the columns of the View named by the view parameter, in the View's column order. A column that selects several values, such as one with a wildcard, has an entry for each, all with the column's Name.

MutationSourcesResponse

Properties

Property	Type	Required	Description
MutationSources			Sources of mutations affecting the configuration data, by resource and path.

StandardErrorResponse

The body of an error response: the error as data (Error), and as one string (message) for clients written before Error.

Properties

Property	Type	Required	Description
Error			The error: its message, category (Type), HTTP status, details, and structured items.
message	string		The error as one string: its message, with any details, items, and individual errors appended. Kept for clients written before Error; new clients read Error.

Unit

Unit is the core unit of operation in ConfigHub. It contains a blob of configuration Data of a single supported Config 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		Deprecated: use ValidationErrors, which this is a copy of. Returned for compatibility with clients written before the field was renamed; it cannot be set.
ApplyWarnings	object		Deprecated: use ValidationWarnings, which this is a copy of. Returned for compatibility with clients written before the field was renamed; it cannot be set.
ChangeSetID	string (uuid)		Unique identifier for the ChangeSet to which the current Revision belongs. Optional. Units are not required to belong to ChangeSets.
Conflicts
CreatedAt	string (date-time)		The timestamp when the entity was created in "2023-01-01T12:00:00Z" format.
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.
HeadRevisionID	string (uuid)		Unique identifier of the head Revision -- the same Revision HeadRevisionNum numbers. Use include=HeadRevisionNum to expand it.
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.
HiddenReason	string		The reason the entity is hidden, if it is. A hidden entity is left out of List and Search results, and of what bulk operations act on, unless the include_hidden parameter names its reason or is *, or the where parameter names the entity by Slug or ID. ConfigHub/YAML Units are created hidden with the reason BackingUnit unless given another.
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, or for a backing Unit the last Revision its entity took. 0 if there is none.
LinkFindings
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			Annotations on locations within the Unit's configuration data, by resource and path.
Permissions			Permissions to access this unit.
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 says whether and how the Unit is delivered. None keeps it off every Target and out of Releases, ConfigHub marks configuration ConfigHub applies to itself, and OCI or empty means it is published in its Space's Releases.
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.
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.
ValidationErrors	object		A map of "//" to true of Triggers invoking validating functions that did not pass on the latest configuration data. These block Release operations.
ValidationResults	object		A map from gate/warning name to the list of validation results that caused the gate or warning.
ValidationTriggerIDs	object		Map from each gate name in ValidationErrors and ValidationWarnings, and in the head Revision's ValidationPassed, to the ID of the Trigger that produced it. A gate no Trigger produced has no entry. The Trigger may since have been renamed, moved, or deleted, so find it by this ID rather than by the slugs in the gate name.
ValidationWarnings	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 Release operations.
ValueTriggerIDs	object		Map from each key in Values to the ID of the Trigger that produced it.
Values	object		Map from "//" to the first output Value with that attribute name of the function invocation specified by the Trigger. Units not resolved since the Space slug was added have "/" keys.
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	Required	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	Required	Description
Applied	integer		Number of conflicts whose withheld change was applied
Conflicts			The Unit's outstanding conflicts after the request
Diff			What applying the withheld changes changed in the configuration, or would change for a dry run, path by path with the values on both sides
Dismissed	integer		Number of conflicts dropped without changing the configuration data
Error	ResponseError
Unit			The Unit as the request left it, or would have left it for a dry run

UnitCreateOrUpdateResponse

Properties

Property	Type	Required	Description
ChangeSetClose			The gates closing the Unit's ChangeSet was judged against, when the write closed, or on a dry run would close, a ChangeSet a ChangeWorkflow governs. Returned for every Unit of the ChangeSet the write detaches. A close the gates refuse fails every such Unit alike, so a write detaching nothing else answers with the refusal alone, whose items name each gate that does not hold, by Space.
ConfigData	string		The configuration the operation produced; returned when include names ConfigData.
Conflicts	MutationConflictList
Diff			What the operation changed, or on a dry run would change, path by path with the values on both sides; returned when include names Diff.
Error	ResponseError
Links	Array of LinkCreateOrUpdateResponse
MutationSources			What set each value in the configuration the operation produced; returned when include names MutationSources.
Unit	Unit

UnitData

Properties

Property	Type	Required	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.

UnitDiff

Properties

Property	Type	Required	Description
Diff			What changed from the From Revision to the To Revision
Error	ResponseError
FromRevisionNum	integer (int64)		The Revision on the From side; 0 when the Unit has none there and the diff is against nothing
SpaceID	string (uuid)		The Space of the Unit
ToRevisionNum	integer (int64)		The Revision on the To side; 0 when the Unit has none there and the diff is against nothing
UnitID	string (uuid)		The Unit

UnitGuardRequest

Properties

Property	Type	Required	Description
Clearance			The classes of reason this edit is cleared for; required to edit a path that already carries guards
ResourceGuards	Array of ResourceGuards		Per-resource guard edits to apply to the Unit's PathAnnotations

UnitGuardResponse

Properties

Property	Type	Required	Description
PathAnnotations			The Unit's PathAnnotations after applying the guard edits

UnitMoveRequest

Properties

Property	Type	Required	Description
ToSpaceID	string (uuid)

UnitMoveResponse

Properties

Property	Type	Required	Description
Error	ResponseError
Moved	boolean
MovedLinkSlugs	Array of string
Resolving	boolean
Slug	string
TargetID	string (uuid)
UnitID	string (uuid)

UnitMutationSources

Properties

Property	Type	Required	Description
DataHash	string		SHA256 of the configuration data the MutationSources describe.
MutationSources			Sources of mutations affecting the configuration data, by resource and path.
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			The Unit's MutationSources after applying the protection edits

UnitTagRequest

Properties

Property	Type	Required	Description
Move	boolean		Move the Tag from the Revision it marks on each Unit to the one Revision names, refusing a Unit it marks no Revision of. Tags owned by a ChangeSet, ChangeOrder or Release cannot be added or removed; a ChangeOrder's release Tag can be moved, to a Revision at or after the one its end Tag marks and the Unit's LastReleasedRevisionNum, with no ValidationErrors, while no Release in the Space has been published at it.
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