Stacklok workloads API
The workloads API from Stacklok — 13 operation(s) for workloads.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
url: https://github.com/stacklok/toolhive
description: 'API for accessing MCP server registry data and deployed server information
This API provides endpoints to query the MCP (Model Context Protocol) server registry,
get information about available servers, and check the status of deployed servers.
Authentication is required by default. Use Bearer token authentication with a valid
OAuth/OIDC access token. The /.well-known/oauth-protected-resource endpoint provides
OAuth discovery metadata (RFC 9728).'
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: ToolHive Registry clients workloads API
version: '0.1'
tags:
- name: workloads
paths:
/api/v1beta/workloads:
get:
description: Get a list of all running workloads, optionally filtered by group
parameters:
- description: List all workloads, including stopped ones
in: query
name: all
schema:
type: boolean
- description: Filter workloads by group name
in: query
name: group
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.workloadListResponse'
description: OK
'404':
content:
application/json:
schema:
type: string
description: Group not found
summary: List all workloads
tags:
- workloads
post:
description: Create and start a new workload
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
- $ref: '#/components/schemas/pkg_api_v1.createRequest'
description: Create workload request
summary: request
description: Create workload request
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.createWorkloadResponse'
description: Created
'400':
content:
application/json:
schema:
type: string
description: Bad Request
'409':
content:
application/json:
schema:
type: string
description: Conflict
summary: Create a new workload
tags:
- workloads
/api/v1beta/workloads/{name}:
delete:
description: 'Delete a workload asynchronously. Returns 202 Accepted immediately.
The deletion happens in the background. Poll the workload list to confirm deletion.'
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
responses:
'202':
content:
application/json:
schema:
type: string
description: Accepted - deletion started
'400':
content:
application/json:
schema:
type: string
description: Bad Request
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Delete a workload
tags:
- workloads
get:
description: Get details of a specific workload
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.createRequest'
description: OK
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Get workload details
tags:
- workloads
/api/v1beta/workloads/{name}/edit:
post:
description: Update an existing workload configuration
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
- $ref: '#/components/schemas/pkg_api_v1.updateRequest'
description: Update workload request
summary: request
description: Update workload request
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.createWorkloadResponse'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad Request
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Update workload
tags:
- workloads
/api/v1beta/workloads/{name}/export:
get:
description: Export a workload's run configuration as JSON
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_runner.RunConfig'
description: OK
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Export workload configuration
tags:
- workloads
/api/v1beta/workloads/{name}/restart:
post:
description: Restart a running workload
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
responses:
'202':
content:
application/json:
schema:
type: string
description: Accepted
'400':
content:
application/json:
schema:
type: string
description: Bad Request
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Restart a workload
tags:
- workloads
/api/v1beta/workloads/{name}/status:
get:
description: Get the current status of a specific workload
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.workloadStatusResponse'
description: OK
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Get workload status
tags:
- workloads
/api/v1beta/workloads/{name}/stop:
post:
description: Stop a running workload
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
responses:
'202':
content:
application/json:
schema:
type: string
description: Accepted
'400':
content:
application/json:
schema:
type: string
description: Bad Request
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Stop a workload
tags:
- workloads
/api/v1beta/workloads/{name}/upgrade:
post:
description: 'Apply a registry-sourced upgrade to a single workload. This
re-resolves and verifies the candidate image, pulls it, and only
then recreates the workload with the new image, preserving the
existing configuration. If the workload is already up to date or
is not registry-sourced, the current check result is returned
unchanged (no-op). Secret values are never accepted or returned.'
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
- $ref: '#/components/schemas/pkg_api_v1.upgradeRequest'
description: Upgrade options
summary: request
description: Upgrade options
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.upgradeCheckResponse'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad Request
'404':
content:
application/json:
schema:
type: string
description: Not Found
'422':
content:
application/json:
schema:
type: string
description: Unprocessable Entity
'500':
content:
application/json:
schema:
type: string
description: Internal Server Error
summary: Apply an available upgrade to a workload
tags:
- workloads
/api/v1beta/workloads/{name}/upgrade-check:
get:
description: 'Check whether a single workload has a newer image available in
its source registry. This is an offline metadata comparison; it
does not pull images. Secret values are never returned.'
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.upgradeCheckResponse'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad Request
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Check a workload for an available upgrade
tags:
- workloads
/api/v1beta/workloads/delete:
post:
description: 'Delete multiple workloads by name or by group asynchronously.
Returns 202 Accepted immediately. Deletion happens in the background.'
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
- $ref: '#/components/schemas/pkg_api_v1.bulkOperationRequest'
description: Bulk delete request (names or group)
summary: request
description: Bulk delete request (names or group)
required: true
responses:
'202':
content:
application/json:
schema:
type: string
description: Accepted - deletion started
'400':
content:
application/json:
schema:
type: string
description: Bad Request
summary: Delete workloads in bulk
tags:
- workloads
/api/v1beta/workloads/restart:
post:
description: Restart multiple workloads by name or by group
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
- $ref: '#/components/schemas/pkg_api_v1.bulkOperationRequest'
description: Bulk restart request (names or group)
summary: request
description: Bulk restart request (names or group)
required: true
responses:
'202':
content:
application/json:
schema:
type: string
description: Accepted
'400':
content:
application/json:
schema:
type: string
description: Bad Request
summary: Restart workloads in bulk
tags:
- workloads
/api/v1beta/workloads/stop:
post:
description: Stop multiple workloads by name or by group
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
- $ref: '#/components/schemas/pkg_api_v1.bulkOperationRequest'
description: Bulk stop request (names or group)
summary: request
description: Bulk stop request (names or group)
required: true
responses:
'202':
content:
application/json:
schema:
type: string
description: Accepted
'400':
content:
application/json:
schema:
type: string
description: Bad Request
summary: Stop workloads in bulk
tags:
- workloads
/api/v1beta/workloads/upgrade-check:
get:
description: 'Check all workloads (optionally filtered by group) for newer
images available in their source registries. This is an offline
metadata comparison; it does not pull images. Secret values are
never returned.'
parameters:
- description: Include stopped workloads
in: query
name: all
schema:
type: boolean
- description: Filter workloads by group name
in: query
name: group
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.upgradeCheckBulkResponse'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad Request
'404':
content:
application/json:
schema:
type: string
description: Group not found
summary: Check workloads for available upgrades
tags:
- workloads
components:
schemas:
github_com_stacklok_toolhive_pkg_auth_awssts.RoleMapping:
properties:
claim:
description: 'Claim is the simple claim value to match (e.g., group name).
Internally compiles to a CEL expression: "<claim_value>" in claims["<role_claim>"]
Mutually exclusive with Matcher.'
type: string
matcher:
description: "Matcher is a CEL expression for complex matching against JWT claims.\nThe expression has access to a \"claims\" variable containing all JWT claims.\nExamples:\n - \"admins\" in claims[\"groups\"]\n - claims[\"sub\"] == \"user123\" && !(\"act\" in claims)\nMutually exclusive with Claim."
type: string
priority:
description: 'Priority determines selection order (lower number = higher priority).
When multiple mappings match, the one with the lowest priority is selected.
When nil (omitted), the mapping has the lowest possible priority, and
configuration order acts as tie-breaker via stable sort.'
type: integer
role_arn:
description: RoleArn is the IAM role ARN to assume when this mapping matches.
type: string
type: object
github_com_stacklok_toolhive_pkg_workloads_upgrade.CheckResult:
description: 'Result is the upgrade-check outcome for the workload. It carries only
metadata (status, image references, drift) and never secret values.'
properties:
candidate_image:
description: CandidateImage is the image reference the registry currently reports.
type: string
config_drift:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_workloads_upgrade.ConfigDrift'
current_image:
description: CurrentImage is the image reference the workload is currently running.
type: string
env_var_drift:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_workloads_upgrade.EnvVarDrift'
reason:
description: Reason provides additional context, primarily for StatusUnknown.
type: string
registry_server:
description: 'RegistryServer is the registry entry name the workload was sourced from.
Empty when the workload is not registry-sourced.'
type: string
status:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_workloads_upgrade.UpgradeStatus'
workload_name:
description: WorkloadName is the name of the workload that was checked.
type: string
type: object
github_com_stacklok_toolhive_pkg_workloads_upgrade.StringChange:
description: 'PermissionProfile is set when the candidate''s permission profile differs
from the workload''s current profile.'
properties:
from:
type: string
to:
type: string
type: object
permissions.OutboundNetworkPermissions:
description: Outbound defines outbound network permissions
properties:
allow_host:
description: AllowHost is a list of allowed hosts
items:
type: string
type: array
uniqueItems: false
allow_port:
description: AllowPort is a list of allowed ports
items:
type: integer
type: array
uniqueItems: false
insecure_allow_all:
description: InsecureAllowAll allows all outbound network connections
type: boolean
type: object
github_com_stacklok_toolhive_pkg_auth_awssts.Config:
description: AWSStsConfig contains AWS STS token exchange configuration for accessing AWS services
properties:
fallback_role_arn:
description: FallbackRoleArn is the IAM role ARN to assume when no role mapping matches.
type: string
region:
description: Region is the AWS region for STS and SigV4 signing.
type: string
role_claim:
description: 'RoleClaim is the JWT claim to use for role mapping (default: "groups").'
type: string
role_mappings:
description: RoleMappings maps JWT claim values to IAM roles with priority.
items:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_auth_awssts.RoleMapping'
type: array
uniqueItems: false
service:
description: 'Service is the AWS service name for SigV4 signing (default: "aws-mcp").'
type: string
session_duration:
description: 'SessionDuration is the duration in seconds for assumed role credentials (default: 3600).'
type: integer
session_name_claim:
description: 'SessionNameClaim is the JWT claim to use for role session name (default: "sub").'
type: string
subject_provider_name:
description: 'SubjectProviderName identifies which upstream provider''s access token to use
for STS AssumeRoleWithWebIdentity. Used by vMCP only. When empty, the bearer
token from the incoming HTTP request is used.'
type: string
type: object
github_com_stacklok_toolhive_pkg_oauthproto_tokenexchange.Config:
description: TokenExchangeConfig contains token exchange configuration for external authentication
properties:
audience:
description: Audience is the target audience for the exchanged token
type: string
client_id:
description: ClientID is the OAuth 2.0 client identifier
type: string
client_secret:
description: ClientSecret is the OAuth 2.0 client secret
type: string
external_token_header_name:
description: ExternalTokenHeaderName is the name of the custom header to use when HeaderStrategy is "custom"
type: string
header_strategy:
description: 'HeaderStrategy determines how to inject the token
Valid values: HeaderStrategyReplace (default), HeaderStrategyCustom'
type: string
scopes:
description: Scopes is the list of scopes to request for the exchanged token
items:
type: string
type: array
uniqueItems: false
subject_token_type:
description: 'SubjectTokenType specifies the type of the subject token being exchanged.
Common values: oauthproto.TokenTypeAccessToken (default), oauthproto.TokenTypeIDToken, oauthproto.TokenTypeJWT.
If empty, defaults to oauthproto.TokenTypeAccessToken.'
type: string
token_url:
description: TokenURL is the OAuth 2.0 token endpoint URL
type: string
type: object
permissions.NetworkPermissions:
description: Network defines network permissions
properties:
inbound:
$ref: '#/components/schemas/permissions.InboundNetworkPermissions'
mode:
description: 'Mode specifies the network mode for the container (e.g., "host", "bridge", "none")
When empty, the default container runtime network mode is used'
type: string
outbound:
$ref: '#/components/schemas/permissions.OutboundNetworkPermissions'
type: object
github_com_stacklok_toolhive_pkg_authserver.UserInfoFieldMappingRunConfig:
description: 'FieldMapping contains custom field mapping configuration for non-standard providers.
If nil, standard OIDC field names are used ("sub", "name", "email").'
properties:
email_fields:
description: 'EmailFields is an ordered list of field names to try for the email address.
The first non-empty value found will be used.
Default: ["email"]'
items:
type: string
type: array
uniqueItems: false
name_fields:
description: 'NameFields is an ordered list of field names to try for the display name.
The first non-empty value found will be used.
Default: ["name"]'
items:
type: string
type: array
uniqueItems: false
subject_fields:
description: 'SubjectFields is an ordered list of field names to try for the user ID.
The first non-empty value found will be used.
Default: ["sub"]'
items:
type: string
type: array
uniqueItems: false
type: object
github_com_stacklok_toolhive_pkg_authserver.TokenLifespanRunConfig:
description: 'TokenLifespans configures the duration that various tokens are valid.
If nil, defaults are applied (access: 1h, refresh: 7d, authCode: 10m).'
properties:
access_token_lifespan:
description: 'AccessTokenLifespan is the duration that access tokens are valid.
If empty, defaults to 1 hour.'
type: string
auth_code_lifespan:
description: 'AuthCodeLifespan is the duration that authorization codes are valid.
If empty, defaults to 10 minutes.'
type: string
refresh_token_lifespan:
description: 'RefreshTokenLifespan is the duration that refresh tokens are valid.
If empty, defaults to 7 days (168h).'
type: string
type: object
github_com_stacklok_toolhive_pkg_ratelimit_types.ToolRateLimitConfig:
properties:
name:
description: 'Name is the MCP tool name this limit applies to.
+kubebuilder:validation:Required
+kubebuilder:validation:MinLength=1'
type: string
perUser:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_ratelimit_types.RateLimitBucket'
shared:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_ratelimit_types.RateLimitBucket'
type: object
v1.Duration:
description: 'RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
The effective refill rate is maxTokens / refillPeriod tokens per second.
Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
+kubebuilder:validation:Required'
type: object
github_com_stacklok_toolhive_pkg_workloads_upgrade.UpgradeStatus:
description: Status is the upgrade status for the workload.
enum:
- up-to-date
- upgrade-available
- not-registry-sourced
- server-not-found
- unknown
type: string
x-enum-varnames:
- StatusUpToDate
- StatusUpgradeAvailable
- StatusNotRegistrySourced
- StatusServerNotFound
- StatusUnknown
github_com_stacklok_toolhive_pkg_authserver.UpstreamProviderType:
description: 'Type specifies the provider type: "oidc" or "oauth2".'
enum:
- oidc
- oauth2
type: string
x-enum-varnames:
- UpstreamProviderTypeOIDC
- UpstreamProviderTypeOAuth2
github_com_stacklok_toolhive_pkg_authserver_storage.RedisRunConfig:
description: RedisConfig is the Redis-specific configuration when Type is "redis".
properties:
acl_user_config:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.ACLUserRunConfig'
addr:
description: 'Addr is the Redis server address (host:port). Required for standalone and cluster modes.
Mutually exclusive with SentinelConfig.'
type: string
auth_type:
description: AuthType must be "aclUser" - only ACL user authentication is supported.
type: string
cluster_mode:
description: ClusterMode enables the Redis Cluster protocol. Requires Addr to be set.
type: boolean
dial_timeout:
description: DialTimeout is the timeout for establishing connections (e.g., "5s").
type: string
key_prefix:
description: KeyPrefix for multi-tenancy, typically "thv:auth:{ns}:{name}:".
type: string
read_timeout:
description: ReadTimeout is the timeout for read operations (e.g., "3s").
type: string
sentinel_config:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.SentinelRunConfig'
sentinel_tls:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.RedisTLSRunConfig'
tls:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.RedisTLSRunConfig'
write_timeout:
description: WriteTimeout is the timeout for write operations (e.g., "3s").
type: string
type: object
github_com_stacklok_toolhive_pkg_webhook.FailurePolicy:
description: FailurePolicy determines behavior when the webhook call fails.
enum:
- fail
- ignore
type: string
x-enum-varnames:
- FailurePolicyFail
- FailurePolicyIgnore
github_com_stacklok_toolhive_pkg_auth_remote.Config:
description: RemoteAuthConfig contains OAuth configuration for remote MCP servers
properties:
authorize_url:
type: string
bearer_token:
description: Bearer token configuration (alternative to OAuth)
type: string
bearer_token_file:
type: string
cached_cimd_client_id:
description: 'CachedCIMDClientID stores the CIMD metadata URL used as client_id when CIMD
authentication was used. Kept separate from CachedClientID (which holds
DCR-issued IDs) so the two can have independent lifecycles — DCR credential
rotation clears CachedClientID without touching the stable CIMD URL.
Read by resolveClientCredentials to send the correct client_id on token refresh.'
type: string
cached_client_id:
description: 'Cached DCR client credentials for persistence across restarts.
These are obtained during Dynamic Client Registration and needed to refresh tokens.
ClientID is stored as plain text since it''s public information.'
type: string
cached_client_secret_ref:
type: string
cached_dcr_callback_port:
description: 'CachedDCRCallbackPort is the callback port that was actually registered
during DCR. It may differ from CallbackPort when the requested port was
unavailable and a fallback port was selected.'
type: integer
cached_refresh_token_ref:
description: 'Cached OAuth token reference for persistence across restarts.
The refresh token is stored securely in the secret manager, and this field
contains the reference to retrieve it (e.g., "OAUTH_REFRESH_TOKEN_workload").
This enables session restoration without requiring a new browser-based login.'
type: string
cached_reg_client_uri:
description: 'CachedRegClientURI is the registration_client_uri from the DCR response.
This is the endpoint used for RFC 7592 client read/update/delete operations.
Stored as plain text since it is not sensitive.'
type: string
cached_reg_token_ref:
description: 'CachedRegTokenRef is a secret manager reference to the registration_access_token
returned in the DCR response. Used for RFC 7592 client update operations.
Stored as a secret reference since it''s sensitive.'
type: string
cached_secret_expiry:
description: 'ClientSecretExpiresAt indicates when the client secret expires (if provided by the DCR server).
A zero value means the secret does not expire.'
type: string
cached_token_auth_method:
description: 'CachedTokenEndpointAuthMethod is the auth method used for the token endpoint
(e.g., "client_secret_basic", "none"). Persisted for RFC 7592 updates.'
type: string
cached_token_expiry:
type: string
callback_port:
type: integer
client_id:
type: string
client_secret:
type: string
client_secret_file:
type: string
issuer:
description: OAuth endpoint configuration (from registry)
type: string
oauth_params:
additionalProperties:
type: string
description: OAuth parameters for server-specific customization
type: object
resource:
description: Resource is the OAuth 2.0 resource indicator (RFC 8707).
type: string
scope_param_name:
description: 'ScopeParamName overrides the query parameter name used to send scopes in the
authorization URL. When empty, the standard "scope" parameter is used.
Some providers require a non-standard name (e.g., Slack uses "user_scope").'
type: string
scopes:
items:
type: string
type: array
uniqueItems: false
skip_browser:
type: boolean
timeout:
example: 5m
type: string
token_url:
type: string
use_pkce:
type: boolean
type: object
pkg_api_v1.updateRequest:
description: Request to update an existing workload (name cannot be changed)
properties:
allow_docker_gateway:
description: 'Whether to permit outbound connections to Docker gateway addresses
(host.docker.internal, gateway.docker.i
# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stacklok/refs/heads/main/openapi/stacklok-workloads-api-openapi.yml