Function
Operations
| Method | Endpoint | Description |
|---|---|---|
GET |
/function |
List retrieves a map of Functions across the Organization |
GET |
/space/{space_id}/function |
List retrieves a map of Functions |
POST |
/function/invoke |
Invoke Functions across Org |
POST |
/space/{space_id}/function/invoke |
Invoke Functions |
List retrieves a map of Functions across the Organization
GET /function
List retrieves a map of Functions across the Organization
Operation ID: ListOrgFunctions
Responses
| Status | Description | Content-Type | Schema |
|---|---|---|---|
| 200 | OK | application/json |
object |
| 400 | Function request is invalid (Bad Request). | application/json |
StandardErrorResponse |
| 401 | Unauthorized access. | application/json |
StandardErrorResponse |
| 403 | Forbidden access. | application/json |
StandardErrorResponse |
| 404 | Function not found. | application/json |
StandardErrorResponse |
| 500 | Something went wrong while processing Function. | application/json |
StandardErrorResponse |
| default | application/json |
object |
List retrieves a map of Functions
GET /space/{space_id}/function
List retrieves a map of Functions
Operation ID: ListFunctions
Parameters
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
space_id |
string | ✓ | Unique identifier for a space_id |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
entity |
string | Type of entity used to identify the worker whose functions should be listed: unit, target, or worker | |
id |
string | ID of the entity used to identify the worker whose functions should be listed |
Responses
| Status | Description | Content-Type | Schema |
|---|---|---|---|
| 200 | OK | application/json |
object |
| 400 | Function request is invalid (Bad Request). | application/json |
StandardErrorResponse |
| 401 | Unauthorized access. | application/json |
StandardErrorResponse |
| 403 | Forbidden access. | application/json |
StandardErrorResponse |
| 404 | Function not found. | application/json |
StandardErrorResponse |
| 500 | Something went wrong while processing Function. | application/json |
StandardErrorResponse |
| default | application/json |
object |
Invoke Functions across Org
POST /function/invoke
Invoke Functions across Units in the Organization
Operation ID: InvokeFunctionsOnOrg
Parameters
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dry_run |
string | Dry run mode: when true, skip updating configuration data even if it changed | |
change_set_id |
string | Must match ChangeSetID of affected Units unless in dry run mode; not valid when invoked on Revisions | |
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, 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. 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'. 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: ApplyGates, ApprovedBy, BridgeWorkerID, ChangeSetID, CreatedAt, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, Labels, LastActionAt, LastAppliedRevisionNum, LastChangeDescription, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, Slug, SpaceID, TargetID, 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. | |
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. |
Request Body
Content-Type: application/json
Schema: FunctionInvocationsRequest
Responses
| Status | Description | Content-Type | Schema |
|---|---|---|---|
| 200 | OK | application/json |
Array of FunctionInvocationsResponse |
| 207 | Multi-Status: Mixed success and failure results | application/json |
Array of FunctionInvocationsResponse |
| 400 | Function request is invalid (Bad Request). | application/json |
StandardErrorResponse |
| 401 | Unauthorized access. | application/json |
StandardErrorResponse |
| 403 | Forbidden access. | application/json |
StandardErrorResponse |
| 404 | Function not found. | application/json |
StandardErrorResponse |
| 422 | Unable to process configuration data | application/json |
StandardErrorResponse |
| 500 | Something went wrong while processing Function. | application/json |
StandardErrorResponse |
| default | application/json |
Array of FunctionInvocationsResponse |
Invoke Functions
POST /space/{space_id}/function/invoke
Invoke Functions
Operation ID: InvokeFunctions
Parameters
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
space_id |
string | ✓ | Unique identifier for a space_id |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
unit_id |
string | Unit ID of the Revision to invoke functions on | |
revision_id |
string | Revision ID to invoke functions on instead of units | |
dry_run |
string | Dry run mode: when true, skip updating configuration data even if it changed | |
change_set_id |
string | Must match ChangeSetID of affected Units unless in dry run mode; not valid when invoked on Revisions | |
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, 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. 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'. 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: ApplyGates, ApprovedBy, BridgeWorkerID, ChangeSetID, CreatedAt, DeleteGates, DestroyGates, DisplayName, FromLinkID, HeadRevisionNum, Labels, LastActionAt, LastAppliedRevisionNum, LastChangeDescription, LiveRevisionNum, OrganizationID, PreviousLiveRevisionNum, Slug, SpaceID, TargetID, 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. | |
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. |
Request Body
Content-Type: application/json
Schema: FunctionInvocationsRequest
Responses
| Status | Description | Content-Type | Schema |
|---|---|---|---|
| 200 | OK | application/json |
Array of FunctionInvocationsResponse |
| 207 | Multi-Status: Mixed success and failure results | application/json |
Array of FunctionInvocationsResponse |
| 400 | Function request is invalid (Bad Request). | application/json |
StandardErrorResponse |
| 401 | Unauthorized access. | application/json |
StandardErrorResponse |
| 403 | Forbidden access. | application/json |
StandardErrorResponse |
| 404 | Function not found. | application/json |
StandardErrorResponse |
| 422 | Unable to process configuration data | application/json |
StandardErrorResponse |
| 500 | Something went wrong while processing Function. | application/json |
StandardErrorResponse |
| default | application/json |
Array of FunctionInvocationsResponse |
Schemas
FunctionInvocationsRequest
FunctionInvocationsRequest represents a request to invoke a list of functions on the configuration data of the matching Units or Revision.
Properties
| Property | Type | Required | Description |
|---|---|---|---|
BridgeWorkerID |
UUID |
||
ChangeDescription |
string | ChangeDescription is a description of the change being made, if any. | |
FunctionInvocations |
FunctionInvocationList |
||
Invocations |
Array of UUID |
Invocations is a list of Invocation IDs to execute. The invocations must be within the same Organization. Invocations will be executed after the FunctionInvocations list. Functions are grouped by executor (built-in vs bridge worker) and executed in phases: general mutating functions first, then final mutating functions (like ensure-context), then validating functions. Functions that don't match the unit's toolchain type are ignored. | |
NumFilters |
integer | NumFilters is the number of validating functions from the FunctionInvocations to treat as filters for the remaining functions in the list. In the case that the validation function does not pass, stop and don't execute the remaining functions, but don't report an error. | |
StopOnError |
boolean | StopOnError indicates whether to stop executing functions from the FunctionInvocations list on the first error, or to execute all of the functions and return all of the errors. Note that this applies to each Unit or Revision individually rather than all of the entities on which the functions are being invoked. | |
ToolchainType |
string | ToolchainType specifies the type of toolchain for these function invocations. This determines which configuration formats the functions can process. | |
Triggers |
Array of UUID |
Triggers is a list of Trigger IDs to execute. The triggers must be within the same Organization. Triggers will be executed after the FunctionInvocations list. Functions are grouped by executor (built-in vs bridge worker) and executed in phases: general mutating functions first, then final mutating functions (like ensure-context), then validating functions. Functions that don't match the unit's toolchain type are ignored. |
FunctionInvocationsResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
ConfigData |
string (base64) | The resulting configuration data, potentially mutated | |
Error |
ResponseError |
||
Mutations |
ResourceMutationList |
||
Mutators |
Array of integer | List of function invocation indices that resulted in mutations | |
OrganizationID |
string (uuid) | ID of the Unit's Organization | |
Outputs |
object | Map of output types to their corresponding output data as embedded JSON | |
RevisionID |
string (uuid) | ID of the Revision the configuration data is associated with | |
SpaceID |
string (uuid) | ID of the Unit's Space | |
Success |
boolean | True if all functions executed successfully | |
UnitID |
string (uuid) | ID of the Unit the configuration data is associated with |
StandardErrorResponse
Error response details.
Properties
| Property | Type | Required | Description |
|---|---|---|---|
Code |
string | HTTP status code of the response. | |
Message |
string | Message returned with the response. |