Unit

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

Operations

Method	Endpoint	Description
`GET`	`/space/{space_id}/unit`	List Units
`GET`	`/unit`	List of Units across spaces
`GET`	`/space/{space_id}/unit/{unit_id}`	Get Unit
`GET`	`/space/{space_id}/unit/{unit_id}/data`	Download config data
`GET`	`/space/{space_id}/unit/{unit_id}/extended`	Get Unit details with expanded relationships
`GET`	`/space/{space_id}/unit/{unit_id}/live_data`	Download live data
`GET`	`/space/{space_id}/unit/{unit_id}/live_state`	Download live state
`POST`	`/space/{space_id}/unit`	Create Unit
`POST`	`/space/{space_id}/unit/{unit_id}/apply`	Apply a unit configuration
`POST`	`/space/{space_id}/unit/{unit_id}/approve`	Approve a unit configuration
`POST`	`/space/{space_id}/unit/{unit_id}/destroy`	Destroy a unit configuration
`POST`	`/space/{space_id}/unit/{unit_id}/import`	Import a configuration unit
`POST`	`/space/{space_id}/unit/{unit_id}/refresh`	Refresh a unit configuration
`POST`	`/unit`	Bulk create (clone) multiple units
`POST`	`/unit/apply`	Bulk apply units
`POST`	`/unit/approve`	Bulk approve multiple units
`POST`	`/unit/cancel`	Bulk cancel unit operations
`POST`	`/unit/destroy`	Bulk destroy units
`POST`	`/unit/refresh`	Bulk refresh units
`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
`PATCH`	`/unit`	Bulk patch multiple units
`DELETE`	`/space/{space_id}/unit/{unit_id}`	Delete Unit
`DELETE`	`/unit`	Bulk delete multiple units

List Units

GET /space/{space_id}/unit

List Units

Operation ID: ListUnits

Parameters

Path Parameters

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

Query Parameters

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

Responses

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

List of Units across spaces

GET /unit

Retrieves a list of Units across spaces in the Organization

Operation ID: ListAllUnits

Parameters

Query Parameters

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

Responses

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

Get Unit

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

Get Unit

Operation ID: GetUnit

Parameters

Path Parameters

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

Query Parameters

Parameter	Type	Required	Description
`include`	string		Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastAppliedRevisionNum, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, 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 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

Operation ID: DownloadUnitData

Parameters

Path Parameters

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

Responses

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

Get Unit details with expanded relationships

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

Get Unit details with expanded relationships

Operation ID: GetUnitExtended

Parameters

Path Parameters

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

Responses

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

Download live data

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

Download the live data of a unit

Operation ID: DownloadUnitLiveData

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`

Download live state

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

Download the live state of a unit

Operation ID: DownloadUnitLiveState

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`

Create Unit

POST /space/{space_id}/unit

Create Unit

Operation ID: CreateUnit

Parameters

Path Parameters

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

Query Parameters

Parameter	Type	Description
`upstream_space_id`	string	Unique identifier for a upstream_space_id
`upstream_unit_id`	string	Unique identifier for a upstream_unit_id
`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

Request Body

Content-Type: application/json

Schema: Unit

Responses

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

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

Triggers an apply operation using the config data to a Bridge Worker

Operation ID: ApplyUnit

Parameters

Path Parameters

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

Query Parameters

Parameter	Type	Description
`revision`	string	Revision to apply (defaults to HeadRevisionNum). Can be a revision number, 'LiveRevisionNum', 'LastAppliedRevisionNum', 'Tag:uuid', 'ChangeSet:uuid', etc.
`dry_run`	boolean	Dry run mode - validates which units would be applied without executing
`drift_mode`	string	Drift reconciliation mode. Valid values: OnDemand, ContinuousApply, ContinuousRefresh. If not specified, the current value on the Unit is used.

Responses

Status	Description	Content-Type	Schema
200	UnitAction is a record of an action to be performed by a Bridge Worker. They are queued and sent to the worker in creation order. If the worker is temporarily disconnected the queued actions will be sent when the worker reconnects or responds. If there are links between units applied or destroyed in a single API call, they will be sent to the appropriate worker(s) in the appropriate order (reverse or forword topological order). One or more UnitEvents will correspond to each UnitAction.	`application/json`	`QueuedOperation`
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	Bridge worker unavailable	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Approve a unit configuration

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

Record that the user invoking this operation approves the configuration data

Operation ID: ApproveUnit

Parameters

Path Parameters

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

Query Parameters

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

Responses

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

Destroy a unit configuration

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

Triggers a destroy operation using the config data to a Bridge Worker

Operation ID: DestroyUnit

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
`dry_run`	boolean		Dry run mode - validates which units would be destroyed without executing

Responses

Status	Description	Content-Type	Schema
200	UnitAction is a record of an action to be performed by a Bridge Worker. They are queued and sent to the worker in creation order. If the worker is temporarily disconnected the queued actions will be sent when the worker reconnects or responds. If there are links between units applied or destroyed in a single API call, they will be sent to the appropriate worker(s) in the appropriate order (reverse or forword topological order). One or more UnitEvents will correspond to each UnitAction.	`application/json`	`QueuedOperation`
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	Bridge worker unavailable	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Import a configuration unit

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

Triggers an import operation using the config data to a Bridge Worker

Operation ID: ImportUnit

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
`dry_run`	boolean		Dry run mode - returns import data in the operation/action

Request Body

Content-Type: application/json

Schema: ImportRequest

Responses

Status	Description	Content-Type	Schema
200	UnitAction is a record of an action to be performed by a Bridge Worker. They are queued and sent to the worker in creation order. If the worker is temporarily disconnected the queued actions will be sent when the worker reconnects or responds. If there are links between units applied or destroyed in a single API call, they will be sent to the appropriate worker(s) in the appropriate order (reverse or forword topological order). One or more UnitEvents will correspond to each UnitAction.	`application/json`	`QueuedOperation`
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	Bridge worker unavailable	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Refresh a unit configuration

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

Triggers a refresh operation using the config data to a Bridge Worker

Operation ID: RefreshUnit

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
`dry_run`	boolean		Dry run mode - returns refresh data in the operation/action and updates LiveData and LiveState in the unit
`drift_mode`	string		Drift reconciliation mode. Valid values: OnDemand, ContinuousApply, ContinuousRefresh. If not specified, the current value on the Unit is used.

Responses

Status	Description	Content-Type	Schema
200	UnitAction is a record of an action to be performed by a Bridge Worker. They are queued and sent to the worker in creation order. If the worker is temporarily disconnected the queued actions will be sent when the worker reconnects or responds. If there are links between units applied or destroyed in a single API call, they will be sent to the appropriate worker(s) in the appropriate order (reverse or forword topological order). One or more UnitEvents will correspond to each UnitAction.	`application/json`	`QueuedOperation`
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	Bridge worker unavailable	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk create (clone) multiple units

POST /unit

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

Operation ID: BulkCreateUnits

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, DriftReconciliationMode, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastAppliedRevisionNum, LastChangeDescription, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamOrganizationID, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LiveRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LiveRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastAppliedRevisionNum, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`name_prefixes`	string	Comma-separated list of prefixes to apply to cloned Unit names
`variant_labels`	string	Comma-separated list of labels with multiple values for cloned Unit labels, in the format of key1=value1\|value2,key2=value1\|value2\|value3
`name_pattern`	string	A string for clone names, use the prefix 'template:' for a Go-template with .SourceEntitySlug to access the original entity's slug and .Labels to access variant labels, example: 'template:{{.SourceEntitySlug}}-{{.Labels.env}}'
`where_space`	string	The specified string is an expression for the purpose of filtering the list of Spaces returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Space: Annotations, AttributeFilterID, AttributeHash, AttributeIDs, CreatedAt, DeleteGates, DisplayName, Labels, OrganizationID, Permissions, Slug, SpaceID, TriggerFilterID, TriggerHash, TriggerIDs, UpdatedAt. Where expression to select destination spaces for cloning units The whole string must be query-encoded.
`filter_space`	string	UUID of a Filter entity to apply to the Space list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Space). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`allow_exists`	string	Allowed values are true and false. Default is false. When true, reports success when an entity already exists and returns the existing entity
`include_outgoing_links_where`	string	The specified string is an expression for the purpose of filtering the list of Links returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Link: Annotations, AutoUpdate, CreatedAt, DeleteGates, DisplayName, DownstreamLastMergedRevisionNum, FromUnitID, Labels, LinkID, OrganizationID, Slug, SpaceID, ToSpaceID, ToUnitID, UpdateType, UpdatedAt, UpstreamLastMergedRevisionNum, UpstreamLinkID, UpstreamOrganizationID, UpstreamSpaceID, UseLiveState. 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.

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 apply units

POST /unit/apply

Executes apply operations for multiple units based on filter criteria across spaces

Operation ID: BulkApplyUnits

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 `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, DriftReconciliationMode, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastAppliedRevisionNum, LastChangeDescription, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamOrganizationID, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LiveRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LiveRevisionNum`. The whole string must be query-encoded.
`filter`	string		UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string		Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string		Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastAppliedRevisionNum, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`dry_run`	boolean		Dry run mode - validates which units would be applied without executing
`revision`	string		Revision to apply (defaults to HeadRevisionNum). Can be a revision number, 'LiveRevisionNum', 'LastAppliedRevisionNum', 'Tag:uuid', 'ChangeSet:uuid', etc.
`drift_mode`	string		Drift reconciliation mode. Valid values: OnDemand, ContinuousApply, ContinuousRefresh. If not specified, the current value on the Unit is used.

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 apply unit(s)	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk approve multiple units

POST /unit/approve

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

Operation ID: BulkApproveUnits

Parameters

Query Parameters

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

Responses

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

Bulk cancel unit operations

POST /unit/cancel

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

Operation ID: BulkCancelUnits

Parameters

Query Parameters

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

Responses

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

Bulk destroy units

POST /unit/destroy

Executes destroy operations for multiple units based on filter criteria across spaces

Operation ID: BulkDestroyUnits

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 `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, DriftReconciliationMode, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastAppliedRevisionNum, LastChangeDescription, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamOrganizationID, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LiveRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LiveRevisionNum`. The whole string must be query-encoded.
`filter`	string		UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string		Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string		Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastAppliedRevisionNum, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`dry_run`	boolean		Dry run mode - validates which units would be destroyed without executing

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 destroy unit(s)	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk refresh units

POST /unit/refresh

Executes refresh operations for multiple units based on filter criteria across spaces

Operation ID: BulkRefreshUnits

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 `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, DriftReconciliationMode, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastAppliedRevisionNum, LastChangeDescription, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamOrganizationID, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LiveRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LiveRevisionNum`. The whole string must be query-encoded.
`filter`	string		UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string		Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string		Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastAppliedRevisionNum, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`dry_run`	boolean		Dry run mode - returns refresh data in the operation/action and updates LiveData and LiveState in the unit
`drift_mode`	string		Drift reconciliation mode. Valid values: OnDemand, ContinuousApply, ContinuousRefresh. If not specified, the current value on the Unit is used.

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 refresh unit(s)	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Bulk tag multiple units

POST /unit/tag

Attach tags to specified unit revisions

Operation ID: BulkTagUnits

Parameters

Query Parameters

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

Request Body

Content-Type: application/json

Schema: UnitTagRequest

Responses

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

Patch Unit

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

Patch Unit

Operation ID: PatchUnit

Parameters

Path Parameters

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

Query Parameters

Parameter	Type	Description
`revision_id`	string	Unique identifier for a revision_id
`dry_run`	boolean	Dry run mode: return changed unit(s) but don't update configuration data
`upgrade`	boolean	Upgrade the unit to the latest version of its upstream unit
`restore`	string	Restore revision source. Supports: Named revisions ('LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', 'HeadRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LiveRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected.
`resolve`	string	Resolve specified non-automatically resolved link from this (downstream) Unit to another (upstream) Unit. Expects Link:uuid or Link:*.
`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 ('LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', 'HeadRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LiveRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected.
`merge_end`	string	Merge end revision of the merge source, which provides the final configuration of the changes to merge. Supports: Named revisions ('LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', 'HeadRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LiveRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected.
`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.
`where_mutation`	string	The specified string is an expression for the purpose of filtering the list of Mutations returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. 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: CreatedAt, FunctionName, InvocationID, LinkID, MergeBaseRevisionNum, MergeEndRevisionNum, MergeSourceID, MutationID, MutationNum, OrganizationID, RestoredRevisionNum, RevisionID, RevisionNum, SpaceID, Subgroup, TriggerID, UnitID, UpdatedAt, UpgradedFromUpstreamRevisionNum. Used to filter which mutations are affected during merge operations. 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
`subgroup`	string	User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.

Request Body

Content-Type: application/merge-patch+json

Responses

Status	Description	Content-Type	Schema
200	Unit is the core unit of operation in ConfigHub. It contains a blob of configuration Data of a single supported Toolchain Type (configuration format). This blob is typically a text document that contains a collection of Kubernetes or infrastructure resources, or an application configuration file. Applying / deploying or destroying the configuration happens as a single transaction from ConfigHub's perspective. In reality, it is most often a multi-step workflow performed by the underlying configuration / deployment tool. The resources must belong to a single infrastructure provider and the actuation mechanism must be able to resolve references and ordering dependencies among the resources within the document. For example, if one resource needs to be fully provisioned to provide input to another resource, then the actuation code is responsible for handling this. Revisions store historical copies of the configuration data. Configuration data can be restored from prior Revisions. Units can also be cloned to create new variants of a configuration.	`application/json`	`Unit`
400	Unit request is invalid (Bad Request).	`application/json`	`StandardErrorResponse`
401	Unauthorized access.	`application/json`	`StandardErrorResponse`
403	Forbidden access.	`application/json`	`StandardErrorResponse`
404	Unit not found.	`application/json`	`StandardErrorResponse`
409	Unit data conflict. Data has changed since last read.	`application/json`	`StandardErrorResponse`
422	Unable to patch unit(s) due to configuration data problem	`application/json`	`StandardErrorResponse`
500	Something went wrong while processing Unit.	`application/json`	`StandardErrorResponse`
default	Unexpected error.	`application/json`	`StandardErrorResponse`

Update Unit

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

Update Unit

Operation ID: UpdateUnit

Parameters

Path Parameters

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

Query Parameters

Parameter	Type	Description
`revision_id`	string	Unique identifier for a revision_id
`dry_run`	boolean	Dry run mode: return changed unit(s) but don't update configuration data
`upgrade`	boolean	Upgrade the unit to the latest version of its upstream unit
`restore`	string	Restore revision source. Supports: Named revisions ('LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', 'HeadRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LiveRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected.
`resolve`	string	Resolve specified non-automatically resolved link from this (downstream) Unit to another (upstream) Unit. Expects Link:uuid or Link:*.
`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 ('LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', 'HeadRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LiveRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected.
`merge_end`	string	Merge end revision of the merge source, which provides the final configuration of the changes to merge. Supports: Named revisions ('LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', 'HeadRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LiveRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected.
`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.
`where_mutation`	string	The specified string is an expression for the purpose of filtering the list of Mutations returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. 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: CreatedAt, FunctionName, InvocationID, LinkID, MergeBaseRevisionNum, MergeEndRevisionNum, MergeSourceID, MutationID, MutationNum, OrganizationID, RestoredRevisionNum, RevisionID, RevisionNum, SpaceID, Subgroup, TriggerID, UnitID, UpdatedAt, UpgradedFromUpstreamRevisionNum. Used to filter which mutations are affected during merge operations. 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
`subgroup`	string	User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.

Request Body

Content-Type: application/json

Schema: Unit

Responses

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

Bulk patch multiple units

PATCH /unit

Apply JSON merge patch to multiple units selected by query parameters

Operation ID: BulkPatchUnits

Parameters

Query Parameters

Parameter	Type	Description
`where`	string	The specified string is an expression for the purpose of filtering the list of Units returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. Map support the dot notation to specify a particular map key, as in `Labels.tier = 'Backend'`. Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence, as in `Labels.tier IS NULL` (key doesn't exist) or `Labels.tier IS NOT NULL` (key exists). Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`. These are useful for nullable columns: `MergeSourceID = '<uuid>' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL. The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses, such as `Slug IN ('slugone', 'slugtwo')` or `Labels.environment IN ('prod', 'staging')`. Conjunctions are supported using the `AND` operator. An example conjunction is: `CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'`. Supported attributes for filtering on Unit: Annotations, ApplyGates, ApplyWarnings, ApprovedBy, BridgeWorkerID, ChangeSetID, CreatedAt, DataHash, DeleteGates, DestroyGates, DisplayName, DriftReconciliationMode, FromLinkID, HeadRevisionNum, HeadUnitActionNum, HeadUnitEventNum, Labels, LastActionAt, LastAppliedRevisionNum, LastChangeDescription, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, ProviderType, Slug, SpaceID, TargetID, TargetOptions, ToolchainType, UnitID, UpdatedAt, UpstreamOrganizationID, UpstreamRevisionNum, UpstreamSpaceID, UpstreamUnitID, Values. Finding all units created by cloning can be done using the expression `UpstreamRevisionNum > 0`. Clones of a specific unit can be found by additionally filtering based on `UpstreamUnitID`. Unapplied units can be found using `LiveRevisionNum = 0`. Units with unapplied changes can be found with `HeadRevisionNum > LiveRevisionNum`. The whole string must be query-encoded.
`filter`	string	UUID of a Filter entity to apply to the Unit list. The Filter must be in the same Organization as the user credentials. The Filter's From field must match the entity type being filtered (Unit). For Space-resident entities, if the Filter has a FromSpaceID, it must match the operation's SpaceID. The Filter's Where clause will be combined with any explicit 'where' parameter using AND logic. If both 'filter' and 'where' parameters are specified, they are combined with AND logic.
`contains`	string	Free text search that approximately matches the specified string against string fields and map keys/values. The search is case-insensitive and uses pattern matching to find entities containing the text. Searchable string fields include attributes like Slug, DisplayName, and string-typed custom fields. For map fields (like Labels and Annotations), the search matches both map keys and values. The search uses OR logic across all searchable fields, so matching any field will return the entity. If both 'where' and 'contains' parameters are specified, they are combined with AND logic. Searchable fields for Unit include string and map-type attributes from the queryable attributes list. The whole string must be query-encoded.
`include`	string	Include clause for expanding related entities in the response for Unit. The attribute names are case-sensitive, PascalCase, and expected in a comma-separated list format as in the JSON encoding. Supported attributes for Unit are ApprovedBy, BridgeWorkerID, ChangeSetID, FromLinkID, HeadMutationNum, HeadRevisionNum, LastAppliedRevisionNum, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, SpaceID, TargetID, UnitEventID, UpstreamSpaceID, UpstreamUnitID. The whole string must be query-encoded.
`dry_run`	boolean	Dry run mode: return changed unit(s) but don't update configuration data
`upgrade`	boolean	Upgrade the unit to the latest version of its upstream unit
`restore`	string	Restore revision source. Supports: Named revisions ('LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', 'HeadRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LiveRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected.
`resolve`	string	Resolve specified non-automatically resolved link from this (downstream) Unit to another (upstream) Unit. Expects Link:uuid or Link:*.
`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 ('LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', 'HeadRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LiveRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected.
`merge_end`	string	Merge end revision of the merge source, which provides the final configuration of the changes to merge. Supports: Named revisions ('LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', 'HeadRevisionNum'), direct revision number (e.g., '42'), or entity references ('Tag:uuid', 'ChangeSet:uuid', 'Revision:uuid'). Can be prefixed with 'Before:' to select the revision immediately before the specified one (e.g., 'Before:LiveRevisionNum', 'Before:42'). When using Tag or ChangeSet references, the latest revision associated with that entity is selected.
`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.
`where_mutation`	string	The specified string is an expression for the purpose of filtering the list of Mutations returned. The expression syntax was inspired by SQL. It supports conjunctions using `AND` of relational expressions of the form attribute operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the JSON encoding. Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~`, `!~`, `!~`, `IN`, `NOT IN`. String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards, `ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching. String regex operators: `~` for regex matching, `~` for case-insensitive regex, `!~` and `!~` for regex not matching (case-sensitive and insensitive). Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`. UUIDs and boolean attributes support equality and inequality only. UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as `'string'`. Time literals use the same form as when serialized as JSON, such as: `CreatedAt > '2025-02-18T23:16:34'`. Integer and boolean literals are also supported for attributes of those types. Arrays support the `?` operator to to match any element of the array, as in `ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'`. Arrays can perform LEN() to check for length, as in `LEN(ApprovedBy) > 0`. 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: CreatedAt, FunctionName, InvocationID, LinkID, MergeBaseRevisionNum, MergeEndRevisionNum, MergeSourceID, MutationID, MutationNum, OrganizationID, RestoredRevisionNum, RevisionID, RevisionNum, SpaceID, Subgroup, TriggerID, UnitID, UpdatedAt, UpgradedFromUpstreamRevisionNum. Used to filter which mutations are affected during merge operations. 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
`subgroup`	string	User-defined category for the Mutation. Must be alphanumeric, at most 64 characters. The prefix 'ConfigHub' is reserved.

Request Body

Content-Type: application/merge-patch+json

Responses

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

Delete Unit

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

Delete Unit

Operation ID: DeleteUnit

Parameters

Path Parameters

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

Responses

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

Bulk delete multiple units

DELETE /unit

Delete multiple units selected by query parameters

Operation ID: BulkDeleteUnits

Parameters

Query Parameters

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

Responses

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

Schemas

ApproveResponse

Properties

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

DeleteResponse

Response for successful delete operation

Properties

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

ExtendedUnit

Unit with capability to extend additional related entities.

Properties

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

ImportRequest

Properties

Property	Type	Description
`Filters`	Array of `ImportFilter`	List of ImportFilter expression clauses. Mutually exclusive with Where.
`Options`	`ImportOptions`
`ResourceInfoList`	`ResourceInfoList`
`Where`	string	Where specifies a unified resource filter expression for import resources and options. It uses SQL-inspired syntax, similar to the where-filter function. Supports conjunctions with AND. String operators: =, !=, <, >, <=, >=, LIKE, ILIKE, ~~, !~~, ~, ~, !~, !~. Pattern matching with LIKE/ILIKE uses % and _ wildcards. Regex operators (~, ~, !~, !~) support POSIX regular expressions. Kubernetes-specific filters include import.include_system for system namespaces like kube-system, import.include_cluster for cluster-scoped resources like ClusterRole, and import.include_custom for custom resource types.

QueuedOperation

UnitAction is a record of an action to be performed by a Bridge Worker. They are queued and sent to the worker in creation order. If the worker is temporarily disconnected the queued actions will be sent when the worker reconnects or responds. If there are links between units applied or destroyed in a single API call, they will be sent to the appropriate worker(s) in the appropriate order (reverse or forword topological order). One or more UnitEvents will correspond to each UnitAction.

Properties

Property	Type	Description
`Action`	`ActionType`
`BridgeState`	string (base64)
`BridgeWorkerID`	string (uuid)	BridgeWorkerID is the unique identifier of the bridge worker that will process this operation.
`CreatedAt`	string (date-time)	The timestamp when the entity was created in "2023-01-01T12:00:00Z" format.
`Data`	string (base64)	The result of a dry-run Data-changing action like refresh and import, where the data is not stored in the Unit.
`Dependencies`	Array of `UUID`	Dependencies contains the list of operation IDs that this operation depends on. Operations will not be delivered until all dependencies are completed.
`DriftReconciliationMode`	string	The drift reconciliation mode for the unit at the time of the operation.
`DryRun`	boolean	DryRun indicates whether the action is a dry run.
`ErrorDetails`	Array of `ErrorItem`	Error details returned by the worker.
`ExtraParams`	string	ExtraParams contains additional parameters for the operation in string format.
`LiveData`	string (base64)
`LiveState`	string (base64)
`OrganizationID`	string (uuid)	OrganizationID is the unique identifier of the organization this operation belongs to.
`QueuedOperationID`	string (uuid)	QueuedOperationID is the unique identifier for the queued unit action.
`RevisionNum`	integer (int64)	RevisionNum is the revision number this operation was performed on.
`SpaceID`	string (uuid)	SpaceID is the unique identifier of the space of the unit this operation is performed on.
`Status`	string	Status indicates the current status of the unit action. v2 statuses: Initializing (being set up), Pending (waiting), Delivered (sent to worker), Progressing (being processed), Completed (success), Failed (error). v1 compatibility: 'pending' = Pending, 'delivered' = Completed (legacy 'delivered' meant work done).
`TargetID`	string (uuid)	TargetID is the unique identifier of the target this operation is directed to.
`UnitActionNum`	integer (int64)	UnitActionNum is the sequence number of this unit action.
`UnitID`	string (uuid)	UnitID is the unique identifier of the unit this operation is performed on.
`UserAgent`	string	User-Agent string of the API call.
`UserID`	string (uuid)	UserID of the user the action was performed by.
`UserIsBot`	boolean	Whether the user who requested the action is a bot user.
`UserRole`	string	Organization-level role of the user who requested the action.
`Version`	integer (int64)	An entity-specific sequence number used for optimistic concurrency control. The value read must be sent in calls to Update.

StandardErrorResponse

Error response details.

Properties

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

Unit

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

Properties

Property	Type	Required	Description
`Annotations`	object		An optional map of Annotation key/value pairs for tools to attach information to entities.
`ApplyGates`	object		A map of "//" to true of Triggers invoking validating functions that did not pass on the latest configuration data. These block Apply operations.
`ApplyWarnings`	object		A map of "//" to true of Triggers with Warn=true invoking validating functions that did not pass on the latest configuration data. These do not block Apply operations.
`ApprovedBy`	Array of `UUID`		The users that have approved the latest revision of the config data for the Unit.
`BridgeState`	string (base64)		Additional state used by the Bridge; content is ProviderType-specific.
`BridgeWorkerID`	string (uuid)		ID of the BridgeWorker from the Target assigned to this Unit.
`ChangeSetID`	string (uuid)		Unique identifier for the ChangeSet to which the current Revision belongs. Optional. Units are not required to belong to ChangeSets.
`ContentHash`	integer		Deprecated: Use DataHash instead. The CRC32 hash of the configuration data.
`CreatedAt`	string (date-time)		The timestamp when the entity was created in "2023-01-01T12:00:00Z" format.
`CursorID`	integer (int64)		An auto-incrementing sequence number used for pagination.
`Data`	string (base64)		The full configuration data for this unit. The maximum size is 67108864 bytes.
`DataHash`	string		The SHA256 hash of the configuration data, encoded as hexadecimal.
`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.
`DriftReconciliationMode`	string		When the drift reconciliation mode is OnDemand, then the live state of the Target is updated only on Apply actions and the unit Data is updated only on Refresh actions. When the mode is ContinuousApply the live state is updated to match the last applied state when it has drifted from that state. When the mode is ContinuousRefresh, the unit Data is updated when it has drifted from the live state. The mode can be changed via the drift_mode parameter on Apply and Refresh operations. If the drift reconciliation mode is set in the opposing direction on the Unit (i.e., ContinuousApply when Refresh is invoked or ContinuousRefresh when Apply is invoked) and is not changed to a compatible value, then the operation will fail.
`EntityType`	string		The type of entity.
`FromLinkID`	Array of `UUID`		IDs of Links originating from this Unit.
`HeadMutationNum`	integer (int64)		Sequence number the head Mutation.
`HeadRevisionNum`	integer (int64)		Sequence number the head Revision.
`HeadUnitActionNum`	integer (int64)		Sequence number of the head unit action (queued operation).
`HeadUnitEventNum`	integer (int64)		Sequence number of the head unit event.
`Labels`	object		An optional map of Label key/value pairs to specify identifying attributes of entities for the purpose of grouping and filtering them.
`LastAppliedRevisionNum`	integer (int64)		Sequence number the last Revision applied. 0 if no live revision.
`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.
`LiveData`	string (base64)		The live resources as of the most recent non-dry-run action in the same representation as Data.
`LiveRevisionNum`	integer (int64)		Sequence number the last Revision applied once apply has completed. 0 if no live revision.
`LiveState`	string (base64)		The live state as of the most recent non-dry-run action; content is ProviderType-specific.
`MutationSources`	`ResourceMutationList`
`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.
`PreviousLiveRevisionNum`	integer (int64)		Sequence number the previous Revision applied. 0 if no live revision.
`ProvidedPaths`	Array of `AttributeInfo`		Attribute paths that this Unit provides to downstream Units via NeedsProvides Links. Computed from get-provided and stored on data updates.
`ProviderType`	string		ProviderType identifies which bridge to use in the case that the Target supports multiple ProviderTypes.
`Slug`	string	✓	Unique URL-safe identifier for the entity.
`SpaceID`	string (uuid)		Unique identifier for a space.
`SpaceSlug`	string		Slug of the Space this entity belongs to. (readonly)
`TargetID`	string (uuid)		TargetID is the identifier of the target this unit is associated with. This defines where the configuration will be applied. It must be set to a valid Target within the same Space before the Unit can be Applied, Destroyed, Imported, or Refreshed.
`TargetOptions`	object		Bridge option values set per-Unit, merged with the Target's Options when sending to the bridge worker (Target's Options take precedence on overlap). The options must be predefined by the ConfigType in the BridgeWorker.
`ToolchainType`	string	✓	ToolchainType specifies the type of toolchain for this unit. Possible values include "Kubernetes/YAML", "AppConfig/Properties", "AppConfig/YAML", "AppConfig/TOML", "AppConfig/INI", "AppConfig/JSON", "AppConfig/Env", "AppConfig/Text", "ConfigHub/YAML".
`UnitID`	string (uuid)		Unique identifier for a Unit.
`UpdatedAt`	string (date-time)		The timestamp when the entity was last updated in "2023-01-01T12:00:00Z" format.
`UpstreamOrganizationID`	string (uuid)		Unique identifier for the Organization of the Unit this unit was cloned from, if any.
`UpstreamRevisionNum`	integer (int64)		Sequence number for the Revision of the Unit this unit was cloned from, or 0. This is updated to the upstream Unit's head revision number when the Unit is upgraded. To change this revision number, change the UpstreamLastMergedRevisionNum of the corresponding Link of UpdateType UpgradeUnit from this Unit to the upstream Unit.
`UpstreamSpaceID`	string (uuid)		Unique identifier for the Space of the Unit this unit was cloned from, if any.
`UpstreamUnitID`	string (uuid)		Unique identifier for Unit this unit was cloned from, if any. To change or remove the upstream unit, change or delete the corresponding Link of UpdateType UpgradeUnit from this Unit to the upstream Unit.
`ValidationResults`	object		A map from gate/warning name to the list of validation results that caused the gate or warning.
`Values`	object		Map from "/" to the first output Value with that attribute name of the function invocation specified by the Trigger.
`Version`	integer (int64)		An entity-specific sequence number used for optimistic concurrency control. The value read must be sent in calls to Update.

UnitActionResponse

Properties

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

UnitCreateOrUpdateResponse

Properties

Property	Type	Required	Description
`Conflicts`	`MutationConflictList`
`Error`	`ResponseError`
`Links`	Array of `LinkCreateOrUpdateResponse`
`Unit`	`Unit`

UnitExtended

Properties

Property	Type	Required	Description
`Action`	`ActionType`
`ActionResult`	`ActionResultType`
`ActionStartedAt`	string (date-time)
`ActionTerminatedAt`	string (date-time)
`ApprovedByUsers`	Array of string
`Drift`	string
`FromLinks`	Array of `Link`
`ResourceStatusSummary`	`ResourceStatusSummary`
`Status`	string
`SyncStatus`	string
`ToLinks`	Array of `Link`
`Unit`	`Unit`

UnitTagRequest

Properties

Property	Type	Required	Description
`Revision`	string		Which Unit revision to tag: 'HeadRevisionNum', 'LiveRevisionNum', 'LastAppliedRevisionNum', 'PreviousLiveRevisionNum', or 'Remove' to remove the tag from the unit
`TagID`	string (uuid)

UnitTagResponse

Properties

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