Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Confighub Unit Action API
version: 0.1.0
contact:
name: ConfigHub Support
url: https://confighub.com/
email: hello@confighub.com
license:
name: N/A
url: https://confighub.com/TBD
termsOfService: TBD
description: 'Operations tagged UnitAction across 2 of this provider''s published API definitions: openapi.json, confighub-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://hub.confighub.com/api
description: production
security:
- bearerAuth: []
tags:
- name: UnitAction
paths:
/space/{space_id}/unit/{unit_id}/unit_action:
get:
tags:
- UnitAction
summary: List UnitActions
operationId: ListUnitActions
parameters:
- name: space_id
in: path
description: Unique identifier for a space_id
required: true
schema:
type: string
format: uuid
- name: unit_id
in: path
description: Unique identifier for a unit_id
required: true
schema:
type: string
format: uuid
- name: where
in: query
description: 'The specified string is an expression for the purpose of filtering
the list of QueuedOperations returned. The expression syntax was inspired by SQL.
It supports conjunctions using `AND` of relational expressions of the form *attribute*
*operator* *attribute_or_literal*. The attribute names are case-sensitive and PascalCase,
as in the JSON encoding.
Strings support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `LIKE`, `NOT LIKE`, `ILIKE`, `~~`, `!~~`, `~`, `~*`, `!~`, `!~*`, `IN`, `NOT IN`.
String pattern operators: `LIKE` and `~~` for pattern matching with `%` and `_` wildcards,
`ILIKE` for case-insensitive pattern matching, `NOT LIKE` and `!~~` for negated pattern matching.
String regex operators: `~` for regex matching, `~*` for case-insensitive regex,
`!~` and `!~*` for regex not matching (case-sensitive and insensitive).
Integers support the following operators: `<`, `>`, `<=`, `>=`, `=`, `!=`, `IN`, `NOT IN`.
UUIDs and boolean attributes support equality and inequality only.
UUID and time literals must be quoted as string literals.
String literals are quoted with single quotes, such as `''string''`.
Time literals use the same form as when serialized as JSON,
such as: `CreatedAt > ''2025-02-18T23:16:34''`.
Integer and boolean literals are also supported for attributes of those types.
Arrays support the `?` operator to to match any element of the array,
as in `FromLinkID ? ''7c61626f-ddbe-41af-93f6-b69f4ab6d308''`.
Arrays can perform LEN() to check for length, as in `LEN(FromLinkID) > 0`.
An attribute naming a list of other entities can be filtered on their attributes with a `*` segment,
as in `FromLink.*.Slug = ''upgrade-app''`, which holds when any element satisfies it.
Without the `*` such a reference is an error, since it names no single value to compare.
Map support the dot notation to specify a particular map key, as in `Labels.tier = ''Backend''`.
Maps support `IS NULL` and `IS NOT NULL` with dot notation to check for key absence or presence,
as in `Labels.tier IS NULL` (key doesn''t exist) or `Labels.tier IS NOT NULL` (key exists).
Comparison results can be tested with `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, and `IS NOT FALSE`.
These are useful for nullable columns: `MergeSourceID = ''<uuid>'' IS NOT FALSE` matches rows where MergeSourceID equals the value OR is NULL.
The `IN` and `NOT IN` operators accept a comma-separated list of values in parentheses,
such as `Slug IN (''slugone'', ''slugtwo'')` or `Labels.environment IN (''prod'', ''staging'')`.
Conjunctions are supported using the `AND` operator.
An example conjunction is:
`CreatedAt >= ''2025-01-07'' AND Slug = ''test'' AND Labels.mykey = ''myvalue''`.
Supported attributes for filtering on QueuedOperation: Action, BridgeWorkerID, CreatedAt, DryRun, OrganizationID, QueuedOperationID, RevisionNum, SpaceID, Status, TargetID, UnitActionNum, UnitID.
The whole string must be query-encoded.'
required: false
schema:
type: string
- name: filter
in: query
description: 'UUID of a Filter entity to apply to the QueuedOperation 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 (QueuedOperation).
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.'
required: false
schema:
type: string
- name: contains
in: query
description: '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 QueuedOperation include string and map-type attributes from the queryable attributes list.
The whole string must be query-encoded.'
required: false
schema:
type: string
- name: where_permission
in: query
description: 'Only return QueuedOperation entities on which the caller has this permission, as well as View, which every entity listed needs.
A list made to choose an entity to act on can name the permission the action needs, such as Edit to change it or Use to refer to it from another entity, so that it leaves out the entities the action would be refused on.
Supported values: Manage, Edit, Use, View.'
required: false
schema:
enum:
- Manage
- Edit
- Use
- View
type: string
- name: limit
in: query
description: Maximum number of QueuedOperation entities to return. If not specified, all matching entities are returned. Values greater than 1000 are rejected with 400. When there may be more entities, the response has a ConfigHub-Continue header to pass as the continue parameter of the next request.
required: false
schema:
maximum: 1000
minimum: 0
type: integer
- name: order_by
in: query
description: 'Comma-separated list of fields to sort QueuedOperation results by, each in the form ''ASC|DESC:FieldName'' or just ''FieldName''.
Field names are case-sensitive and PascalCase, as in the JSON encoding. Sort direction defaults to ASC when the ''DIRECTION:'' prefix is omitted.
Supported attributes for ordering QueuedOperation: Action, BridgeWorkerID, CreatedAt, DryRun, OrganizationID, QueuedOperationID, RevisionNum, Status, TargetID, UnitActionNum, UnitID.
Example: ''DESC:CreatedAt'' or ''DisplayName,DESC:CreatedAt''.
Results are ordered by the QueuedOperation''s ID after the fields named, and by the ID alone if none are.
The whole string must be query-encoded.'
required: false
schema:
pattern: ^\s*(?:(?:[Aa][Ss][Cc]|[Dd][Ee][Ss][Cc])\s*:\s*)?(Action|BridgeWorkerID|CreatedAt|DryRun|OrganizationID|QueuedOperationID|RevisionNum|Status|TargetID|UnitActionNum|UnitID)\s*(?:,\s*(?:(?:[Aa][Ss][Cc]|[Dd][Ee][Ss][Cc])\s*:\s*)?(?:Action|BridgeWorkerID|CreatedAt|DryRun|OrganizationID|QueuedOperationID|RevisionNum|Status|TargetID|UnitActionNum|UnitID)\s*)*$
type: string
- name: continue
in: query
description: 'The token from the ConfigHub-Continue header of the previous page, to return the QueuedOperation entities after it.
The request''s other parameters, except limit, must be the same as those of the request that returned the token.
Keep reading until a response has no such header: a page can hold fewer entities than the limit, or none, and still be followed by more.'
required: false
schema:
type: string
responses:
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'200':
description: OK
headers:
ConfigHub-Continue:
style: simple
description: The token to pass as the continue parameter of the next request, when there may be more entities after this page. It is absent on the last page. A page can hold fewer entities than the limit, or none, and still have one.
schema:
type: string
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UnitAction'
'400':
description: UnitAction request is invalid (Bad Request).
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'404':
description: UnitAction not found.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'500':
description: Something went wrong while processing UnitAction.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
servers:
- url: https://hub.confighub.com/api
description: production
/space/{space_id}/unit/{unit_id}/unit_action/{unit_action_id}:
get:
tags:
- UnitAction
summary: Get UnitAction
operationId: GetUnitAction
parameters:
- name: space_id
in: path
description: Unique identifier for a space_id
required: true
schema:
type: string
format: uuid
- name: unit_id
in: path
description: Unique identifier for a unit_id
required: true
schema:
type: string
format: uuid
- name: unit_action_id
in: path
description: Unique identifier for a unit_action_id
required: true
schema:
type: string
format: uuid
responses:
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'200':
description: UnitAction is a record of an operation queued for a Worker, such as a function invocation on a unit. Operations are delivered to the worker in creation order; if the worker is disconnected, pending operations are delivered when it reconnects. One or more UnitEvents will correspond to each UnitAction.
content:
application/json:
schema:
$ref: '#/components/schemas/UnitAction'
'400':
description: UnitAction request is invalid (Bad Request).
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'404':
description: UnitAction not found.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
'500':
description: Something went wrong while processing UnitAction.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
servers:
- url: https://hub.confighub.com/api
description: production
components:
schemas:
ErrorMetadata:
type: object
properties:
EntityID:
type: string
description: Optional ID of the entity this error relates to
x-go-type-skip-optional-pointer: true
EntitySlug:
type: string
description: Optional slug of the entity this error relates to
x-go-type-skip-optional-pointer: true
EntityType:
type: string
description: Optional type of the entity this error relates to
x-go-type-skip-optional-pointer: true
Items:
type: array
items:
$ref: '#/components/schemas/ErrorItem'
description: Collection of error details
x-go-type-skip-optional-pointer: true
UnitAction:
type: object
properties:
Action:
allOf:
- $ref: '#/components/schemas/ActionType'
description: Action is the type of action to be performed by the worker, such as InvokeFunctions or Cancel. UnitActions queued for bridge workers, which have been removed, can carry the actions they performed, such as Apply.
BridgeWorkerID:
type: string
description: BridgeWorkerID is the unique identifier of the worker that will process this operation.
format: uuid
example: 248df4b7-aa70-47b8-a036-33ac447e668d
x-go-type-skip-optional-pointer: true
x-omitzero: true
CreatedAt:
type: string
description: The timestamp when the entity was created in "2023-01-01T12:00:00Z" format.
format: date-time
example: 2006-01-02T15:04:05Z07:00
x-go-type-skip-optional-pointer: true
x-omitzero: true
Data:
type: string
description: 'Data is the result the worker reported for a finished function invocation: its FunctionInvocationResponse, as JSON.'
format: base64
x-go-type-skip-optional-pointer: true
Dependencies:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/UUID'
description: Unused. No longer populated or consulted for delivery; retained for schema compatibility and scheduled for removal.
x-go-type-skip-optional-pointer: true
DryRun:
type: boolean
description: DryRun indicates whether the action is a dry run.
x-go-type-skip-optional-pointer: true
ErrorDetails:
type: array
items:
$ref: '#/components/schemas/ErrorItem'
description: Error details returned by the worker.
x-go-type-skip-optional-pointer: true
ExtraParams:
type: string
description: ExtraParams contains additional parameters for the operation in string format.
x-go-type-skip-optional-pointer: true
OrganizationID:
type: string
description: OrganizationID is the unique identifier of the organization this operation belongs to.
format: uuid
example: 248df4b7-aa70-47b8-a036-33ac447e668d
x-go-type-skip-optional-pointer: true
x-omitzero: true
QueuedOperationID:
type: string
description: QueuedOperationID is the unique identifier for the queued unit action.
format: uuid
example: 248df4b7-aa70-47b8-a036-33ac447e668d
x-go-type-skip-optional-pointer: true
x-omitzero: true
RevisionNum:
type: integer
description: RevisionNum is the revision number this operation was performed on.
format: int64
x-go-type-skip-optional-pointer: true
SpaceID:
type: string
description: SpaceID is the unique identifier of the space of the unit this operation is performed on.
format: uuid
example: 248df4b7-aa70-47b8-a036-33ac447e668d
x-go-type-skip-optional-pointer: true
x-omitzero: true
Status:
enum:
- Initializing
- Pending
- Delivered
- Progressing
- Completed
- Failed
- Aborted
- Canceled
- pending
- delivered
type: string
description: '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).'
x-go-type-skip-optional-pointer: true
TargetID:
type: string
description: TargetID is the unique identifier of the target this operation is directed to.
format: uuid
example: 248df4b7-aa70-47b8-a036-33ac447e668d
x-go-type-skip-optional-pointer: true
x-omitzero: true
UnitActionNum:
type: integer
description: UnitActionNum is the sequence number of this unit action.
format: int64
x-go-type-skip-optional-pointer: true
UnitID:
type: string
description: UnitID is the unique identifier of the unit this operation is performed on.
format: uuid
example: 248df4b7-aa70-47b8-a036-33ac447e668d
x-go-type-skip-optional-pointer: true
x-omitzero: true
UserAgent:
type: string
description: User-Agent string of the API call.
x-go-type-skip-optional-pointer: true
UserID:
type: string
description: UserID of the user the action was performed by.
format: uuid
example: 248df4b7-aa70-47b8-a036-33ac447e668d
x-go-type-skip-optional-pointer: true
x-omitzero: true
UserIsBot:
type: boolean
description: Whether the user who requested the action is a bot user.
x-go-type-skip-optional-pointer: true
UserRole:
type: string
description: Organization-level role of the user who requested the action.
x-go-type-skip-optional-pointer: true
Version:
type: integer
description: 'An entity-specific sequence number used for optimistic concurrency control.
The value read must be sent in calls to Update.'
format: int64
x-go-type-skip-optional-pointer: true
description: UnitAction is a record of an operation queued for a Worker, such as a function invocation on a unit. Operations are delivered to the worker in creation order; if the worker is disconnected, pending operations are delivered when it reconnects. One or more UnitEvents will correspond to each UnitAction.
ErrorItem:
type: object
properties:
Description:
type: string
description: A clear explanation of what went wrong
x-go-type-skip-optional-pointer: true
Item:
type: string
description: The name of the field, resource, or entity that the error relates to
x-go-type-skip-optional-pointer: true
ResponseError:
type: object
properties:
Details:
type: array
items:
type: string
description: Additional context messages
x-go-type-skip-optional-pointer: true
ErrorMetadata:
allOf:
- $ref: '#/components/schemas/ErrorMetadata'
description: Structured error details like field violations
Message:
type: string
description: The primary error message
x-go-type-skip-optional-pointer: true
Status:
type: integer
description: HTTP status code
x-go-type-skip-optional-pointer: true
Type:
type: string
description: 'The category of the error, as a code: UserInput, Validation, Data, Authentication, Permission, NotFound, Conflict, AlreadyExists, Unprocessable, Locked, PreconditionFailed, TooManyRequests, Unexpected, GatewayTimeout, or ServiceUnavailable'
x-go-type-skip-optional-pointer: true
UUID:
type: string
format: uuid
example: 248df4b7-aa70-47b8-a036-33ac447e668d
ActionType:
enum:
- N/A
- Cancel
- InvokeFunctions
- ListFunctions
- Apply
type: string
StandardErrorResponse:
type: object
properties:
Error:
allOf:
- $ref: '#/components/schemas/ResponseError'
description: 'The error: its message, category (Type), HTTP status, details, and structured items.'
message:
type: string
description: 'The error as one string: its message, with any details, items, and individual errors appended. Kept for clients written before Error; new clients read Error.'
x-go-type-skip-optional-pointer: true
description: 'The body of an error response: the error as data (Error), and as one string (message) for clients written before Error.'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer authentication
x-refined-from:
- openapi.json
- confighub-openapi.json