components: schemas: audit.Config: description: |- DEPRECATED: Middleware configuration. AuditConfig contains the audit logging configuration properties: component: description: |- Component is the component name to use in audit events. +optional type: string enabled: description: |- Enabled controls whether audit logging is enabled. When true, enables audit logging with the configured options. +kubebuilder:default=false +optional type: boolean eventTypes: description: |- EventTypes specifies which event types to audit. If empty, all events are audited. +optional items: type: string type: array uniqueItems: false excludeEventTypes: description: |- ExcludeEventTypes specifies which event types to exclude from auditing. This takes precedence over EventTypes. +optional items: type: string type: array uniqueItems: false includeRequestData: description: |- IncludeRequestData determines whether to include request data in audit logs. +kubebuilder:default=false +optional type: boolean includeResponseData: description: |- IncludeResponseData determines whether to include response data in audit logs. +kubebuilder:default=false +optional type: boolean logFile: description: |- LogFile specifies the file path for audit logs. If empty, logs to stdout. +optional type: string maxDataSize: description: |- MaxDataSize limits the size of request/response data included in audit logs (in bytes). +kubebuilder:default=1024 +optional type: integer type: object auth.TokenValidatorConfig: description: |- DEPRECATED: Middleware configuration. OIDCConfig contains OIDC configuration properties: allowPrivateIP: description: AllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses type: boolean audience: description: Audience is the expected audience for the token type: string authTokenFile: description: AuthTokenFile is the path to file containing bearer token for authentication type: string cacertPath: description: CACertPath is the path to the CA certificate bundle for HTTPS requests type: string clientID: description: ClientID is the OIDC client ID type: string clientSecret: description: ClientSecret is the optional OIDC client secret for introspection type: string insecureAllowHTTP: description: |- InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing WARNING: This is insecure and should NEVER be used in production type: boolean introspectionURL: description: IntrospectionURL is the optional introspection endpoint for validating tokens type: string issuer: description: Issuer is the OIDC issuer URL (e.g., https://accounts.google.com) type: string jwksurl: description: JWKSURL is the URL to fetch the JWKS from type: string resourceURL: description: ResourceURL is the explicit resource URL for OAuth discovery (RFC 9728) type: string scopes: description: |- Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728) If empty, defaults to ["openid"] items: type: string type: array type: object authserver.OAuth2UpstreamRunConfig: description: |- OAuth2Config contains OAuth 2.0-specific configuration. Required when Type is "oauth2", must be nil when Type is "oidc". properties: authorization_endpoint: description: AuthorizationEndpoint is the URL for the OAuth authorization endpoint. type: string client_id: description: ClientID is the OAuth 2.0 client identifier registered with the upstream IDP. type: string client_secret_env_var: description: |- ClientSecretEnvVar is the name of an environment variable containing the client secret. Mutually exclusive with ClientSecretFile. Optional for public clients using PKCE. type: string client_secret_file: description: |- ClientSecretFile is the path to a file containing the OAuth 2.0 client secret. Mutually exclusive with ClientSecretEnvVar. Optional for public clients using PKCE. type: string redirect_uri: description: |- RedirectURI is the callback URL where the upstream IDP will redirect after authentication. When not specified, defaults to `{issuer}/oauth/callback`. type: string scopes: description: Scopes are the OAuth scopes to request from the upstream IDP. items: type: string type: array uniqueItems: false token_endpoint: description: TokenEndpoint is the URL for the OAuth token endpoint. type: string userinfo: $ref: '#/components/schemas/authserver.UserInfoRunConfig' type: object authserver.OIDCUpstreamRunConfig: description: |- OIDCConfig contains OIDC-specific configuration. Required when Type is "oidc", must be nil when Type is "oauth2". properties: client_id: description: ClientID is the OAuth 2.0 client identifier registered with the upstream IDP. type: string client_secret_env_var: description: |- ClientSecretEnvVar is the name of an environment variable containing the client secret. Mutually exclusive with ClientSecretFile. Optional for public clients using PKCE. type: string client_secret_file: description: |- ClientSecretFile is the path to a file containing the OAuth 2.0 client secret. Mutually exclusive with ClientSecretEnvVar. Optional for public clients using PKCE. type: string issuer_url: description: |- IssuerURL is the OIDC issuer URL for automatic endpoint discovery. Must be a valid HTTPS URL. type: string redirect_uri: description: |- RedirectURI is the callback URL where the upstream IDP will redirect after authentication. When not specified, defaults to `{issuer}/oauth/callback`. type: string scopes: description: |- Scopes are the OAuth scopes to request from the upstream IDP. If not specified, defaults to ["openid", "offline_access"]. items: type: string type: array uniqueItems: false userinfo_override: $ref: '#/components/schemas/authserver.UserInfoRunConfig' type: object authserver.RunConfig: description: |- EmbeddedAuthServerConfig contains configuration for the embedded OAuth2/OIDC authorization server. When set, the proxy runner will start an embedded auth server that delegates to upstream IDPs. This is the serializable RunConfig; secrets are referenced by file paths or env var names. properties: allowed_audiences: description: |- AllowedAudiences is the list of valid resource URIs that tokens can be issued for. Per RFC 8707, the "resource" parameter in authorization and token requests is validated against this list. Required for MCP compliance. items: type: string type: array uniqueItems: false hmac_secret_files: description: |- HMACSecretFiles contains file paths to HMAC secrets for signing authorization codes and refresh tokens (opaque tokens). First file is the current secret (must be at least 32 bytes), subsequent files are for rotation/verification of existing tokens. If empty, an ephemeral secret will be auto-generated (development only). items: type: string type: array uniqueItems: false issuer: description: |- Issuer is the issuer identifier for this authorization server. This will be included in the "iss" claim of issued tokens. Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash. type: string schema_version: description: SchemaVersion is the version of the RunConfig schema. type: string scopes_supported: description: |- ScopesSupported lists the OAuth 2.0 scope values advertised in discovery documents. If empty, defaults to ["openid", "offline_access"]. items: type: string type: array uniqueItems: false signing_key_config: $ref: '#/components/schemas/authserver.SigningKeyRunConfig' token_lifespans: $ref: '#/components/schemas/authserver.TokenLifespanRunConfig' upstreams: description: |- Upstreams configures connections to upstream Identity Providers. At least one upstream is required - the server delegates authentication to these providers. Currently only a single upstream is supported. items: $ref: '#/components/schemas/authserver.UpstreamRunConfig' type: array uniqueItems: false type: object authserver.SigningKeyRunConfig: description: |- SigningKeyConfig configures the signing key provider for JWT operations. If nil or empty, an ephemeral signing key will be auto-generated (development only). properties: fallback_key_files: description: |- FallbackKeyFiles are filenames of additional keys for verification (relative to KeyDir). These keys are included in the JWKS endpoint for token verification but are NOT used for signing new tokens. Useful for key rotation. items: type: string type: array uniqueItems: false key_dir: description: |- KeyDir is the directory containing PEM-encoded private key files. All key filenames are relative to this directory. In Kubernetes, this is typically a mounted Secret volume. type: string signing_key_file: description: |- SigningKeyFile is the filename of the primary signing key (relative to KeyDir). This key is used for signing new tokens. type: string type: object 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 authserver.UpstreamProviderType: description: 'Type specifies the provider type: "oidc" or "oauth2".' enum: - oidc - oauth2 type: string x-enum-varnames: - UpstreamProviderTypeOIDC - UpstreamProviderTypeOAuth2 authserver.UpstreamRunConfig: properties: name: description: |- Name uniquely identifies this upstream. Used for routing decisions and session binding in multi-upstream scenarios. If empty when only one upstream is configured, defaults to "default". type: string oauth2_config: $ref: '#/components/schemas/authserver.OAuth2UpstreamRunConfig' oidc_config: $ref: '#/components/schemas/authserver.OIDCUpstreamRunConfig' type: $ref: '#/components/schemas/authserver.UpstreamProviderType' type: object 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 authserver.UserInfoRunConfig: description: UserInfo contains configuration for fetching user information (required for OAuth2). properties: additional_headers: additionalProperties: type: string description: |- AdditionalHeaders contains extra headers to include in the userinfo request. Useful for providers that require specific headers (e.g., GitHub's Accept header). type: object endpoint_url: description: EndpointURL is the URL of the userinfo endpoint. type: string field_mapping: $ref: '#/components/schemas/authserver.UserInfoFieldMappingRunConfig' http_method: description: |- HTTPMethod is the HTTP method to use for the userinfo request. If not specified, defaults to GET. type: string type: object authz.Config: description: |- DEPRECATED: Middleware configuration. AuthzConfig contains the authorization configuration properties: type: description: Type is the type of authorization configuration (e.g., "cedarv1"). type: string version: description: Version is the version of the configuration format. type: string type: object client.MCPClient: description: ClientType is the type of MCP client enum: - roo-code - cline - cursor - vscode-insider - vscode - claude-code - windsurf - windsurf-jetbrains - amp-cli - amp-vscode - amp-cursor - amp-vscode-insider - amp-windsurf - lm-studio - goose - trae - continue - opencode - kiro - antigravity - zed type: string x-enum-varnames: - RooCode - Cline - Cursor - VSCodeInsider - VSCode - ClaudeCode - Windsurf - WindsurfJetBrains - AmpCli - AmpVSCode - AmpCursor - AmpVSCodeInsider - AmpWindsurf - LMStudio - Goose - Trae - Continue - OpenCode - Kiro - Antigravity - Zed client.MCPClientStatus: properties: client_type: $ref: '#/components/schemas/client.MCPClient' installed: description: Installed indicates whether the client is installed on the system type: boolean registered: description: Registered indicates whether the client is registered in the ToolHive configuration type: boolean type: object client.RegisteredClient: properties: groups: items: type: string type: array uniqueItems: false name: $ref: '#/components/schemas/client.MCPClient' type: object core.Workload: properties: created_at: description: CreatedAt is the timestamp when the workload was created. type: string group: description: Group is the name of the group this workload belongs to, if any. type: string labels: additionalProperties: type: string description: Labels are the container labels (excluding standard ToolHive labels) type: object name: description: |- Name is the name of the workload. It is used as a unique identifier. type: string package: description: Package specifies the Workload Package used to create this Workload. type: string port: description: |- Port is the port on which the workload is exposed. This is embedded in the URL. type: integer proxy_mode: description: |- ProxyMode is the proxy mode that clients should use to connect. For stdio transports, this will be the proxy mode (sse or streamable-http). For direct transports (sse/streamable-http), this will be the same as TransportType. type: string remote: description: Remote indicates whether this is a remote workload (true) or a container workload (false). type: boolean started_at: description: StartedAt is when the container was last started (changes on restart) type: string status: $ref: '#/components/schemas/runtime.WorkloadStatus' status_context: description: |- StatusContext provides additional context about the workload's status. The exact meaning is determined by the status and the underlying runtime. type: string tools: description: ToolsFilter is the filter on tools applied to the workload. items: type: string type: array uniqueItems: false transport_type: $ref: '#/components/schemas/types.TransportType' url: description: URL is the URL of the workload exposed by the ToolHive proxy. type: string type: object groups.Group: properties: name: type: string registered_clients: items: type: string type: array uniqueItems: false type: object ignore.Config: description: IgnoreConfig contains configuration for ignore processing properties: loadGlobal: description: Whether to load global ignore patterns type: boolean printOverlays: description: Whether to print resolved overlay paths for debugging type: boolean type: object permissions.InboundNetworkPermissions: description: Inbound defines inbound network permissions properties: allow_host: description: AllowHost is a list of allowed hosts for inbound connections items: type: string type: array uniqueItems: false 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 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 permissions.Profile: description: PermissionProfile is the permission profile to use properties: name: description: Name is the name of the profile type: string network: $ref: '#/components/schemas/permissions.NetworkPermissions' privileged: description: |- Privileged indicates whether the container should run in privileged mode When true, the container has access to all host devices and capabilities Use with extreme caution as this removes most security isolation type: boolean read: description: |- Read is a list of mount declarations that the container can read from These can be in the following formats: - A single path: The same path will be mounted from host to container - host-path:container-path: Different paths for host and container - resource-uri:container-path: Mount a resource identified by URI to a container path items: type: string type: array uniqueItems: false write: description: |- Write is a list of mount declarations that the container can write to These follow the same format as Read mounts but with write permissions items: type: string type: array uniqueItems: false type: object registry.EnvVar: properties: default: description: |- Default is the value to use if the environment variable is not explicitly provided Only used for non-required variables type: string description: description: Description is a human-readable explanation of the variable's purpose type: string name: description: Name is the environment variable name (e.g., API_KEY) type: string required: description: |- Required indicates whether this environment variable must be provided If true and not provided via command line or secrets, the user will be prompted for a value type: boolean secret: description: |- Secret indicates whether this environment variable contains sensitive information If true, the value will be stored as a secret rather than as a plain environment variable type: boolean type: object registry.Group: properties: description: description: Description is a human-readable description of the group's purpose and functionality type: string name: description: Name is the identifier for the group, used when referencing the group in commands type: string remote_servers: additionalProperties: $ref: '#/components/schemas/registry.RemoteServerMetadata' description: RemoteServers is a map of server names to their corresponding remote server definitions within this group type: object servers: additionalProperties: $ref: '#/components/schemas/registry.ImageMetadata' description: Servers is a map of server names to their corresponding server definitions within this group type: object type: object registry.Header: properties: choices: description: Choices provides a list of valid values for the header (optional) items: type: string type: array uniqueItems: false default: description: |- Default is the value to use if the header is not explicitly provided Only used for non-required headers type: string description: description: Description is a human-readable explanation of the header's purpose type: string name: description: Name is the header name (e.g., X-API-Key, Authorization) type: string required: description: |- Required indicates whether this header must be provided If true and not provided via command line or secrets, the user will be prompted for a value type: boolean secret: description: |- Secret indicates whether this header contains sensitive information If true, the value will be stored as a secret rather than as plain text type: boolean type: object registry.ImageMetadata: description: Container server details (if it's a container server) properties: args: description: |- Args are the default command-line arguments to pass to the MCP server container. These arguments will be used only if no command-line arguments are provided by the user. If the user provides arguments, they will override these defaults. items: type: string type: array uniqueItems: false custom_metadata: additionalProperties: {} description: CustomMetadata allows for additional user-defined metadata type: object description: description: Description is a human-readable description of the server's purpose and functionality type: string docker_tags: description: DockerTags lists the available Docker tags for this server image items: type: string type: array uniqueItems: false env_vars: description: EnvVars defines environment variables that can be passed to the server items: $ref: '#/components/schemas/registry.EnvVar' type: array uniqueItems: false image: description: Image is the Docker image reference for the MCP server type: string metadata: $ref: '#/components/schemas/registry.Metadata' name: description: |- Name is the identifier for the MCP server, used when referencing the server in commands If not provided, it will be auto-generated from the registry key type: string permissions: $ref: '#/components/schemas/permissions.Profile' provenance: $ref: '#/components/schemas/registry.Provenance' proxy_port: description: |- ProxyPort is the port for the HTTP proxy to listen on (host port) If not specified, a random available port will be assigned type: integer repository_url: description: RepositoryURL is the URL to the source code repository for the server type: string status: description: Status indicates whether the server is currently active or deprecated type: string tags: description: Tags are categorization labels for the server to aid in discovery and filtering items: type: string type: array uniqueItems: false target_port: description: TargetPort is the port for the container to expose (only applicable to SSE and Streamable HTTP transports) type: integer tier: description: Tier represents the tier classification level of the server, e.g., "Official" or "Community" type: string tools: description: Tools is a list of tool names provided by this MCP server items: type: string type: array uniqueItems: false transport: description: |- Transport defines the communication protocol for the server For containers: stdio, sse, or streamable-http For remote servers: sse or streamable-http (stdio not supported) type: string type: object registry.Metadata: description: Metadata contains additional information about the server such as popularity metrics properties: last_updated: description: LastUpdated is the timestamp when the server was last updated, in RFC3339 format type: string pulls: description: Pulls indicates how many times the server image has been downloaded type: integer stars: description: Stars represents the popularity rating or number of stars for the server type: integer type: object registry.OAuthConfig: description: |- OAuthConfig provides OAuth/OIDC configuration for authentication to the remote server Used with the thv proxy command's --remote-auth flags properties: authorize_url: description: |- AuthorizeURL is the OAuth authorization endpoint URL Used for non-OIDC OAuth flows when issuer is not provided type: string callback_port: description: |- CallbackPort is the specific port to use for the OAuth callback server If not specified, a random available port will be used type: integer client_id: description: ClientID is the OAuth client ID for authentication type: string issuer: description: |- Issuer is the OAuth/OIDC issuer URL (e.g., https://accounts.google.com) Used for OIDC discovery to find authorization and token endpoints type: string oauth_params: additionalProperties: type: string description: |- OAuthParams contains additional OAuth parameters to include in the authorization request These are server-specific parameters like "prompt", "response_mode", etc. type: object resource: description: Resource is the OAuth 2.0 resource indicator (RFC 8707) type: string scopes: description: |- Scopes are the OAuth scopes to request If not specified, defaults to ["openid", "profile", "email"] for OIDC items: type: string type: array uniqueItems: false token_url: description: |- TokenURL is the OAuth token endpoint URL Used for non-OIDC OAuth flows when issuer is not provided type: string use_pkce: description: |- UsePKCE indicates whether to use PKCE for the OAuth flow Defaults to true for enhanced security type: boolean type: object registry.Provenance: description: Provenance contains verification and signing metadata properties: attestation: $ref: '#/components/schemas/registry.VerifiedAttestation' cert_issuer: type: string repository_ref: type: string repository_uri: type: string runner_environment: type: string signer_identity: type: string sigstore_url: type: string type: object registry.Registry: description: Full registry data properties: groups: description: Groups is a slice of group definitions containing related MCP servers items: $ref: '#/components/schemas/registry.Group' type: array uniqueItems: false last_updated: description: LastUpdated is the timestamp when the registry was last updated, in RFC3339 format type: string remote_servers: additionalProperties: $ref: '#/components/schemas/registry.RemoteServerMetadata' description: |- RemoteServers is a map of server names to their corresponding remote server definitions These are MCP servers accessed via HTTP/HTTPS using the thv proxy command type: object servers: additionalProperties: $ref: '#/components/schemas/registry.ImageMetadata' description: Servers is a map of server names to their corresponding server definitions type: object version: description: Version is the schema version of the registry type: string type: object registry.RemoteServerMetadata: description: Remote server details (if it's a remote server) properties: custom_metadata: additionalProperties: {} description: CustomMetadata allows for additional user-defined metadata type: object description: description: Description is a human-readable description of the server's purpose and functionality type: string env_vars: description: |- EnvVars defines environment variables that can be passed to configure the client These might be needed for client-side configuration when connecting to the remote server items: $ref: '#/components/schemas/registry.EnvVar' type: array uniqueItems: false headers: description: |- Headers defines HTTP headers that can be passed to the remote server for authentication These are used with the thv proxy command's authentication features items: $ref: '#/components/schemas/registry.Header' type: array uniqueItems: false metadata: $ref: '#/components/schemas/registry.Metadata' name: description: |- Name is the identifier for the MCP server, used when referencing the server in commands If not provided, it will be auto-generated from the registry key type: string oauth_config: $ref: '#/components/schemas/registry.OAuthConfig' repository_url: description: RepositoryURL is the URL to the source code repository for the server type: string status: description: Status indicates whether the server is currently active or deprecated type: string tags: description: Tags are categorization labels for the server to aid in discovery and filtering items: type: string type: array uniqueItems: false tier: description: Tier represents the tier classification level of the server, e.g., "Official" or "Community" type: string tools: description: Tools is a list of tool names provided by this MCP server items: type: string type: array uniqueItems: false transport: description: |- Transport defines the communication protocol for the server For containers: stdio, sse, or streamable-http For remote servers: sse or streamable-http (stdio not supported) type: string url: description: URL is the endpoint URL for the remote MCP server (e.g., https://api.example.com/mcp) type: string type: object registry.VerifiedAttestation: properties: predicate: {} predicate_type: type: string type: object 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_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_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_token_ref: description: |- RegistrationAccessToken is used to update/delete the client registration. 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_expiry: type: string callback_port: type: integer client_id: type: string client_secret: type: string client_secret_file: type: string env_vars: description: Environment variables for the client items: $ref: '#/components/schemas/registry.EnvVar' type: array uniqueItems: false headers: description: Headers for HTTP requests items: $ref: '#/components/schemas/registry.Header' type: array uniqueItems: false 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 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 runner.HeaderForwardConfig: description: HeaderForward contains configuration for injecting headers into requests to remote servers. properties: add_headers_from_secret: additionalProperties: type: string description: |- AddHeadersFromSecret is a map of header names to secret names. The key is the header name, the value is the secret name in ToolHive's secrets manager. Resolved at runtime via WithSecrets() into resolvedHeaders. The actual secret value is only held in memory, never persisted. type: object add_plaintext_headers: additionalProperties: type: string description: |- AddPlaintextHeaders is a map of header names to literal values to inject into requests. WARNING: These values are stored in plaintext in the configuration. For sensitive values (API keys, tokens), use AddHeadersFromSecret instead. type: object type: object runner.RunConfig: properties: audit_config: $ref: '#/components/schemas/audit.Config' audit_config_path: description: |- DEPRECATED: Middleware configuration. AuditConfigPath is the path to the audit configuration file type: string authz_config: $ref: '#/components/schemas/authz.Config' authz_config_path: description: |- DEPRECATED: Middleware configuration. AuthzConfigPath is the path to the authorization configuration file type: string base_name: description: BaseName is the base name used for the container (without prefixes) type: string cmd_args: description: CmdArgs are the arguments to pass to the container items: type: string type: array uniqueItems: false container_labels: additionalProperties: type: string description: ContainerLabels are the labels to apply to the container type: object container_name: description: ContainerName is the name of the container type: string debug: description: Debug indicates whether debug mode is enabled type: boolean embedded_auth_server_config: $ref: '#/components/schemas/authserver.RunConfig' endpoint_prefix: description: |- EndpointPrefix is an explicit prefix to prepend to SSE endpoint URLs. This is used to handle path-based ingress routing scenarios. type: string env_file_dir: description: |- DEPRECATED: No longer appears to be used. EnvFileDir is the directory path to load environment files from type: string env_vars: additionalProperties: type: string description: EnvVars are the parsed environment variables as key-value pairs type: object group: description: Group is the name of the group this workload belongs to, if any type: string header_forward: $ref: '#/components/schemas/runner.HeaderForwardConfig' host: description: Host is the host for the HTTP proxy type: string ignore_config: $ref: '#/components/schemas/ignore.Config' image: description: Image is the Docker image to run type: string isolate_network: description: IsolateNetwork indicates whether to isolate the network for the container type: boolean jwks_auth_token_file: description: |- DEPRECATED: No longer appears to be used. JWKSAuthTokenFile is the path to file containing auth token for JWKS/OIDC requests type: string k8s_pod_template_patch: description: |- K8sPodTemplatePatch is a JSON string to patch the Kubernetes pod template Only applicable when using Kubernetes runtime type: string middleware_configs: description: |- MiddlewareConfigs contains the list of middleware to apply to the transport and the configuration for each middleware. items: $ref: '#/components/schemas/types.MiddlewareConfig' type: array uniqueItems: false name: description: Name is the name of the MCP server type: string oidc_config: $ref: '#/components/schemas/auth.TokenValidatorConfig' permission_profile: $ref: '#/components/schemas/permissions.Profile' permission_profile_name_or_path: description: PermissionProfileNameOrPath is the name or path of the permission profile type: string port: description: Port is the port for the HTTP proxy to listen on (host port) type: integer proxy_mode: $ref: '#/components/schemas/types.ProxyMode' remote_auth_config: $ref: '#/components/schemas/remote.Config' remote_url: description: RemoteURL is the URL of the remote MCP server (if running remotely) type: string schema_version: description: SchemaVersion is the version of the RunConfig schema type: string secrets: description: |- Secrets are the secret parameters to pass to the container Format: ",target=" items: type: string type: array uniqueItems: false target_host: description: TargetHost is the host to forward traffic to (only applicable to SSE transport) type: string target_port: description: TargetPort is the port for the container to expose (only applicable to SSE transport) type: integer telemetry_config: $ref: '#/components/schemas/telemetry.Config' thv_ca_bundle: description: |- DEPRECATED: No longer appears to be used. ThvCABundle is the path to the CA certificate bundle for ToolHive HTTP operations type: string token_exchange_config: $ref: '#/components/schemas/tokenexchange.Config' tools_filter: description: |- DEPRECATED: Middleware configuration. ToolsFilter is the list of tools to filter items: type: string type: array uniqueItems: false tools_override: additionalProperties: $ref: '#/components/schemas/runner.ToolOverride' description: |- DEPRECATED: Middleware configuration. ToolsOverride is a map from an actual tool to its overridden name and/or description type: object transport: $ref: '#/components/schemas/types.TransportType' trust_proxy_headers: description: TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies type: boolean volumes: description: |- Volumes are the directory mounts to pass to the container Format: "host-path:container-path[:ro]" items: type: string type: array uniqueItems: false type: object runner.ToolOverride: properties: description: description: Description is the redefined description of the tool type: string name: description: Name is the redefined name of the tool type: string type: object runtime.WorkloadStatus: description: Current status of the workload enum: - running - stopped - error - starting - stopping - unhealthy - removing - unknown - unauthenticated type: string x-enum-varnames: - WorkloadStatusRunning - WorkloadStatusStopped - WorkloadStatusError - WorkloadStatusStarting - WorkloadStatusStopping - WorkloadStatusUnhealthy - WorkloadStatusRemoving - WorkloadStatusUnknown - WorkloadStatusUnauthenticated secrets.SecretParameter: description: Bearer token for authentication (alternative to OAuth) properties: name: type: string target: type: string type: object telemetry.Config: description: |- DEPRECATED: Middleware configuration. TelemetryConfig contains the OpenTelemetry configuration properties: customAttributes: additionalProperties: type: string description: |- CustomAttributes contains custom resource attributes to be added to all telemetry signals. These are parsed from CLI flags (--otel-custom-attributes) or environment variables (OTEL_RESOURCE_ATTRIBUTES) as key=value pairs. +optional type: object enablePrometheusMetricsPath: description: |- EnablePrometheusMetricsPath controls whether to expose Prometheus-style /metrics endpoint. The metrics are served on the main transport port at /metrics. This is separate from OTLP metrics which are sent to the Endpoint. +kubebuilder:default=false +optional type: boolean endpoint: description: |- Endpoint is the OTLP endpoint URL +optional type: string environmentVariables: description: |- EnvironmentVariables is a list of environment variable names that should be included in telemetry spans as attributes. Only variables in this list will be read from the host machine and included in spans for observability. Example: ["NODE_ENV", "DEPLOYMENT_ENV", "SERVICE_VERSION"] +optional items: type: string type: array uniqueItems: false headers: additionalProperties: type: string description: |- Headers contains authentication headers for the OTLP endpoint. +optional type: object insecure: description: |- Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint. +kubebuilder:default=false +optional type: boolean metricsEnabled: description: |- MetricsEnabled controls whether OTLP metrics are enabled. When false, OTLP metrics are not sent even if an endpoint is configured. This is independent of EnablePrometheusMetricsPath. +kubebuilder:default=false +optional type: boolean samplingRate: description: |- SamplingRate is the trace sampling rate (0.0-1.0) as a string. Only used when TracingEnabled is true. Example: "0.05" for 5% sampling. +kubebuilder:default="0.05" +optional type: string serviceName: description: |- ServiceName is the service name for telemetry. When omitted, defaults to the server name (e.g., VirtualMCPServer name). +optional type: string serviceVersion: description: |- ServiceVersion is the service version for telemetry. When omitted, defaults to the ToolHive version. +optional type: string tracingEnabled: description: |- TracingEnabled controls whether distributed tracing is enabled. When false, no tracer provider is created even if an endpoint is configured. +kubebuilder:default=false +optional type: boolean type: object 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: tokenTypeAccessToken (default), tokenTypeIDToken, tokenTypeJWT. If empty, defaults to tokenTypeAccessToken. type: string token_url: description: TokenURL is the OAuth 2.0 token endpoint URL type: string type: object types.MiddlewareConfig: properties: parameters: description: |- Parameters is a JSON object containing the middleware parameters. It is stored as a raw message to allow flexible parameter types. type: object type: description: Type is a string representing the middleware type. type: string type: object types.ProxyMode: description: |- ProxyMode is the proxy mode for stdio transport ("sse" or "streamable-http") Note: "sse" is deprecated; use "streamable-http" instead. enum: - sse - streamable-http type: string x-enum-varnames: - ProxyModeSSE - ProxyModeStreamableHTTP types.TransportType: description: Transport is the transport mode (stdio, sse, or streamable-http) enum: - stdio - sse - streamable-http - inspector type: string x-enum-varnames: - TransportTypeStdio - TransportTypeSSE - TransportTypeStreamableHTTP - TransportTypeInspector v1.RegistryType: description: Type of registry (file, url, or default) enum: - file - url - api - default type: string x-enum-varnames: - RegistryTypeFile - RegistryTypeURL - RegistryTypeAPI - RegistryTypeDefault v1.UpdateRegistryRequest: description: Request containing registry configuration updates properties: allow_private_ip: description: Allow private IP addresses for registry URL or API URL type: boolean api_url: description: MCP Registry API URL type: string local_path: description: Local registry file path type: string url: description: Registry URL (for remote registries) type: string type: object v1.UpdateRegistryResponse: description: Response containing update result properties: type: description: Registry type after update type: string type: object v1.bulkClientRequest: properties: groups: description: Groups is the list of groups configured on the client. items: type: string type: array uniqueItems: false names: description: Names is the list of client names to operate on. items: $ref: '#/components/schemas/client.MCPClient' type: array uniqueItems: false type: object v1.bulkOperationRequest: properties: group: description: Group name to operate on (mutually exclusive with names) type: string names: description: Names of the workloads to operate on items: type: string type: array uniqueItems: false type: object v1.clientStatusResponse: properties: clients: items: $ref: '#/components/schemas/client.MCPClientStatus' type: array uniqueItems: false type: object v1.createClientRequest: properties: groups: description: Groups is the list of groups configured on the client. items: type: string type: array uniqueItems: false name: $ref: '#/components/schemas/client.MCPClient' type: object v1.createClientResponse: properties: groups: description: Groups is the list of groups configured on the client. items: type: string type: array uniqueItems: false name: $ref: '#/components/schemas/client.MCPClient' type: object v1.createGroupRequest: properties: name: description: Name of the group to create type: string type: object v1.createGroupResponse: properties: name: description: Name of the created group type: string type: object v1.createRequest: description: Request to create a new workload properties: authz_config: description: Authorization configuration type: string cmd_arguments: description: Command arguments to pass to the container items: type: string type: array uniqueItems: false env_vars: additionalProperties: type: string description: Environment variables to set in the container type: object group: description: Group name this workload belongs to type: string header_forward: $ref: '#/components/schemas/v1.headerForwardConfig' headers: items: $ref: '#/components/schemas/registry.Header' type: array uniqueItems: false host: description: Host to bind to type: string image: description: Docker image to use type: string name: description: Name of the workload type: string network_isolation: description: Whether network isolation is turned on. This applies the rules in the permission profile. type: boolean oauth_config: $ref: '#/components/schemas/v1.remoteOAuthConfig' oidc: $ref: '#/components/schemas/v1.oidcOptions' permission_profile: $ref: '#/components/schemas/permissions.Profile' proxy_mode: description: Proxy mode to use type: string proxy_port: description: Port for the HTTP proxy to listen on type: integer secrets: description: Secret parameters to inject items: $ref: '#/components/schemas/secrets.SecretParameter' type: array uniqueItems: false target_port: description: Port to expose from the container type: integer tools: description: Tools filter items: type: string type: array uniqueItems: false tools_override: additionalProperties: $ref: '#/components/schemas/v1.toolOverride' description: Tools override type: object transport: description: Transport configuration type: string trust_proxy_headers: description: Whether to trust X-Forwarded-* headers from reverse proxies type: boolean url: description: Remote server specific fields type: string volumes: description: Volume mounts items: type: string type: array uniqueItems: false type: object v1.createSecretRequest: description: Request to create a new secret properties: key: description: Secret key name type: string value: description: Secret value type: string type: object v1.createSecretResponse: description: Response after creating a secret properties: key: description: Secret key that was created type: string message: description: Success message type: string type: object v1.createWorkloadResponse: description: Response after successfully creating a workload properties: name: description: Name of the created workload type: string port: description: Port the workload is listening on type: integer type: object v1.getRegistryResponse: description: Response containing registry details properties: last_updated: description: Last updated timestamp type: string name: description: Name of the registry type: string registry: $ref: '#/components/schemas/registry.Registry' server_count: description: Number of servers in the registry type: integer source: description: Source of the registry (URL, file path, or empty string for built-in) type: string type: $ref: '#/components/schemas/v1.RegistryType' version: description: Version of the registry schema type: string type: object v1.getSecretsProviderResponse: description: Response containing secrets provider details properties: capabilities: $ref: '#/components/schemas/v1.providerCapabilitiesResponse' name: description: Name of the secrets provider type: string provider_type: description: Type of the secrets provider type: string type: object v1.getServerResponse: description: Response containing server details properties: is_remote: description: Indicates if this is a remote server type: boolean remote_server: $ref: '#/components/schemas/registry.RemoteServerMetadata' server: $ref: '#/components/schemas/registry.ImageMetadata' type: object v1.groupListResponse: properties: groups: description: List of groups items: $ref: '#/components/schemas/groups.Group' type: array uniqueItems: false type: object v1.headerForwardConfig: description: |- HeaderForward configures headers to inject into requests to remote MCP servers. Use this to add custom headers like X-Tenant-ID or correlation IDs. properties: add_headers_from_secret: additionalProperties: type: string description: |- AddHeadersFromSecret maps header names to secret names in ToolHive's secrets manager. Key: HTTP header name, Value: secret name in the secrets manager type: object add_plaintext_headers: additionalProperties: type: string description: |- AddPlaintextHeaders contains literal header values to inject. WARNING: These values are stored and transmitted in plaintext. Use AddHeadersFromSecret for sensitive data like API keys. type: object type: object v1.listSecretsResponse: description: Response containing a list of secret keys properties: keys: description: List of secret keys items: $ref: '#/components/schemas/v1.secretKeyResponse' type: array uniqueItems: false type: object v1.listServersResponse: description: Response containing a list of servers properties: remote_servers: description: List of remote servers in the registry (if any) items: $ref: '#/components/schemas/registry.RemoteServerMetadata' type: array uniqueItems: false servers: description: List of container servers in the registry items: $ref: '#/components/schemas/registry.ImageMetadata' type: array uniqueItems: false type: object v1.oidcOptions: description: OIDC configuration options properties: audience: description: Expected audience type: string client_id: description: OAuth2 client ID type: string client_secret: description: OAuth2 client secret type: string introspection_url: description: Token introspection URL for OIDC type: string issuer: description: OIDC issuer URL type: string jwks_url: description: JWKS URL for key verification type: string scopes: description: OAuth scopes to advertise in well-known endpoint (RFC 9728) items: type: string type: array uniqueItems: false type: object v1.providerCapabilitiesResponse: description: Capabilities of the secrets provider properties: can_cleanup: description: Whether the provider can cleanup all secrets type: boolean can_delete: description: Whether the provider can delete secrets type: boolean can_list: description: Whether the provider can list secrets type: boolean can_read: description: Whether the provider can read secrets type: boolean can_write: description: Whether the provider can write secrets type: boolean type: object v1.registryInfo: description: Basic information about a registry properties: last_updated: description: Last updated timestamp type: string name: description: Name of the registry type: string server_count: description: Number of servers in the registry type: integer source: description: Source of the registry (URL, file path, or empty string for built-in) type: string type: $ref: '#/components/schemas/v1.RegistryType' version: description: Version of the registry schema type: string type: object v1.registryListResponse: description: Response containing a list of registries properties: registries: description: List of registries items: $ref: '#/components/schemas/v1.registryInfo' type: array uniqueItems: false type: object v1.remoteOAuthConfig: description: OAuth configuration for remote server authentication properties: authorize_url: description: OAuth authorization endpoint URL (alternative to issuer for non-OIDC OAuth) type: string bearer_token: $ref: '#/components/schemas/secrets.SecretParameter' callback_port: description: Specific port for OAuth callback server type: integer client_id: description: OAuth client ID for authentication type: string client_secret: $ref: '#/components/schemas/secrets.SecretParameter' issuer: description: OAuth/OIDC issuer URL (e.g., https://accounts.google.com) type: string oauth_params: additionalProperties: type: string description: Additional OAuth parameters for server-specific customization type: object resource: description: OAuth 2.0 resource indicator (RFC 8707) type: string scopes: description: OAuth scopes to request items: type: string type: array uniqueItems: false skip_browser: description: Whether to skip opening browser for OAuth flow (defaults to false) type: boolean token_url: description: OAuth token endpoint URL (alternative to issuer for non-OIDC OAuth) type: string use_pkce: description: Whether to use PKCE for the OAuth flow type: boolean type: object v1.secretKeyResponse: description: Secret key information properties: description: description: Optional description of the secret type: string key: description: Secret key name type: string type: object v1.setupSecretsRequest: description: Request to setup a secrets provider properties: password: description: |- Password for encrypted provider (optional, can be set via environment variable) TODO Review environment variable for this type: string provider_type: description: Type of the secrets provider (encrypted, 1password, environment) type: string type: object v1.setupSecretsResponse: description: Response after initializing a secrets provider properties: message: description: Success message type: string provider_type: description: Type of the secrets provider that was setup type: string type: object v1.toolOverride: description: Tool override properties: description: description: Description of the tool type: string name: description: Name of the tool type: string type: object v1.updateRequest: description: Request to update an existing workload (name cannot be changed) properties: authz_config: description: Authorization configuration type: string cmd_arguments: description: Command arguments to pass to the container items: type: string type: array uniqueItems: false env_vars: additionalProperties: type: string description: Environment variables to set in the container type: object group: description: Group name this workload belongs to type: string header_forward: $ref: '#/components/schemas/v1.headerForwardConfig' headers: items: $ref: '#/components/schemas/registry.Header' type: array uniqueItems: false host: description: Host to bind to type: string image: description: Docker image to use type: string network_isolation: description: Whether network isolation is turned on. This applies the rules in the permission profile. type: boolean oauth_config: $ref: '#/components/schemas/v1.remoteOAuthConfig' oidc: $ref: '#/components/schemas/v1.oidcOptions' permission_profile: $ref: '#/components/schemas/permissions.Profile' proxy_mode: description: Proxy mode to use type: string proxy_port: description: Port for the HTTP proxy to listen on type: integer secrets: description: Secret parameters to inject items: $ref: '#/components/schemas/secrets.SecretParameter' type: array uniqueItems: false target_port: description: Port to expose from the container type: integer tools: description: Tools filter items: type: string type: array uniqueItems: false tools_override: additionalProperties: $ref: '#/components/schemas/v1.toolOverride' description: Tools override type: object transport: description: Transport configuration type: string trust_proxy_headers: description: Whether to trust X-Forwarded-* headers from reverse proxies type: boolean url: description: Remote server specific fields type: string volumes: description: Volume mounts items: type: string type: array uniqueItems: false type: object v1.updateSecretRequest: description: Request to update an existing secret properties: value: description: New secret value type: string type: object v1.updateSecretResponse: description: Response after updating a secret properties: key: description: Secret key that was updated type: string message: description: Success message type: string type: object v1.versionResponse: properties: version: type: string type: object v1.workloadListResponse: description: Response containing a list of workloads properties: workloads: description: List of container information for each workload items: $ref: '#/components/schemas/core.Workload' type: array uniqueItems: false type: object v1.workloadStatusResponse: description: Response containing workload status information properties: status: $ref: '#/components/schemas/runtime.WorkloadStatus' type: object externalDocs: description: "" url: "" info: description: This is the ToolHive API server. title: ToolHive API version: "1.0" openapi: 3.1.0 paths: /api/openapi.json: get: description: Returns the OpenAPI specification for the API responses: "200": content: application/json: schema: type: object description: OpenAPI specification summary: Get OpenAPI specification tags: - system /api/v1beta/clients: get: description: List all registered clients in ToolHive responses: "200": content: application/json: schema: items: $ref: '#/components/schemas/client.RegisteredClient' type: array description: OK summary: List all clients tags: - clients post: description: Register a new client with ToolHive requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/v1.createClientRequest' description: Client to register summary: client description: Client to register required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.createClientResponse' description: OK "400": content: application/json: schema: type: string description: Invalid request or unsupported client type summary: Register a new client tags: - clients /api/v1beta/clients/{name}: delete: description: Unregister a client from ToolHive parameters: - description: Client name to unregister in: path name: name required: true schema: type: string responses: "204": description: No Content "400": content: application/json: schema: type: string description: Invalid request or unsupported client type summary: Unregister a client tags: - clients /api/v1beta/clients/{name}/groups/{group}: delete: description: Unregister a client from a specific group in ToolHive parameters: - description: Client name to unregister in: path name: name required: true schema: type: string - description: Group name to remove client from in: path name: group required: true schema: type: string responses: "204": description: No Content "400": content: application/json: schema: type: string description: Invalid request or unsupported client type "404": content: application/json: schema: type: string description: Client or group not found summary: Unregister a client from a specific group tags: - clients /api/v1beta/clients/register: post: description: Register multiple clients with ToolHive requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/v1.bulkClientRequest' description: Clients to register summary: clients description: Clients to register required: true responses: "200": content: application/json: schema: items: $ref: '#/components/schemas/v1.createClientResponse' type: array description: OK "400": content: application/json: schema: type: string description: Invalid request or unsupported client type summary: Register multiple clients tags: - clients /api/v1beta/clients/unregister: post: description: Unregister multiple clients from ToolHive requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/v1.bulkClientRequest' description: Clients to unregister summary: clients description: Clients to unregister required: true responses: "204": description: No Content "400": content: application/json: schema: type: string description: Invalid request or unsupported client type summary: Unregister multiple clients tags: - clients /api/v1beta/discovery/clients: get: description: List all clients compatible with ToolHive and their status responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.clientStatusResponse' description: OK summary: List all clients status tags: - discovery /api/v1beta/groups: get: description: Get a list of all groups responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.groupListResponse' description: OK "500": content: application/json: schema: type: string description: Internal Server Error summary: List all groups tags: - groups post: description: Create a new group with the specified name requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/v1.createGroupRequest' description: Group creation request summary: group description: Group creation request required: true responses: "201": content: application/json: schema: $ref: '#/components/schemas/v1.createGroupResponse' description: Created "400": content: application/json: schema: type: string description: Bad Request "409": content: application/json: schema: type: string description: Conflict "500": content: application/json: schema: type: string description: Internal Server Error summary: Create a new group tags: - groups /api/v1beta/groups/{name}: delete: description: Delete a group by name. parameters: - description: Group name in: path name: name required: true schema: type: string - description: 'Delete all workloads in the group (default: false, moves workloads to default group)' in: query name: with-workloads schema: type: boolean responses: "204": content: application/json: schema: type: string description: No Content "404": content: application/json: schema: type: string description: Not Found "500": content: application/json: schema: type: string description: Internal Server Error summary: Delete a group tags: - groups get: description: Get details of a specific group parameters: - description: Group name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/groups.Group' description: OK "404": content: application/json: schema: type: string description: Not Found "500": content: application/json: schema: type: string description: Internal Server Error summary: Get group details tags: - groups /api/v1beta/registry: get: description: Get a list of the current registries responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.registryListResponse' description: OK summary: List registries tags: - registry post: description: Add a new registry requestBody: content: application/json: schema: type: object responses: "501": content: application/json: schema: type: string description: Not Implemented summary: Add a registry tags: - registry /api/v1beta/registry/{name}: delete: description: Remove a specific registry parameters: - description: Registry name in: path name: name required: true schema: type: string responses: "204": content: application/json: schema: type: string description: No Content "404": content: application/json: schema: type: string description: Not Found summary: Remove a registry tags: - registry get: description: Get details of a specific registry parameters: - description: Registry name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.getRegistryResponse' description: OK "404": content: application/json: schema: type: string description: Not Found summary: Get a registry tags: - registry put: description: Update registry URL or local path for the default registry parameters: - description: Registry name (must be 'default') in: path name: name required: true schema: type: string requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/v1.UpdateRegistryRequest' description: Registry configuration summary: body description: Registry configuration required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.UpdateRegistryResponse' description: OK "400": content: application/json: schema: type: string description: Bad Request "404": content: application/json: schema: type: string description: Not Found "502": content: application/json: schema: type: string description: Bad Gateway - Registry validation failed "504": content: application/json: schema: type: string description: Gateway Timeout - Registry unreachable summary: Update registry configuration tags: - registry /api/v1beta/registry/{name}/servers: get: description: Get a list of servers in a specific registry parameters: - description: Registry name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.listServersResponse' description: OK "404": content: application/json: schema: type: string description: Not Found summary: List servers in a registry tags: - registry /api/v1beta/registry/{name}/servers/{serverName}: get: description: Get details of a specific server in a registry parameters: - description: Registry name in: path name: name required: true schema: type: string - description: ImageMetadata name in: path name: serverName required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.getServerResponse' description: OK "404": content: application/json: schema: type: string description: Not Found summary: Get a server from a registry tags: - registry /api/v1beta/secrets: post: description: Setup the secrets provider with the specified type and configuration. requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/v1.setupSecretsRequest' description: Setup secrets provider request summary: request description: Setup secrets provider request required: true responses: "201": content: application/json: schema: $ref: '#/components/schemas/v1.setupSecretsResponse' description: Created "400": content: application/json: schema: type: string description: Bad Request "500": content: application/json: schema: type: string description: Internal Server Error summary: Setup or reconfigure secrets provider tags: - secrets /api/v1beta/secrets/default: get: description: Get details of the default secrets provider responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.getSecretsProviderResponse' description: OK "404": content: application/json: schema: type: string description: Not Found - Provider not setup "500": content: application/json: schema: type: string description: Internal Server Error summary: Get secrets provider details tags: - secrets /api/v1beta/secrets/default/keys: get: description: Get a list of all secret keys from the default provider responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.listSecretsResponse' description: OK "404": content: application/json: schema: type: string description: Not Found - Provider not setup "405": content: application/json: schema: type: string description: Method Not Allowed - Provider doesn't support listing "500": content: application/json: schema: type: string description: Internal Server Error summary: List secrets tags: - secrets post: description: Create a new secret in the default provider (encrypted provider only) requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/v1.createSecretRequest' description: Create secret request summary: request description: Create secret request required: true responses: "201": content: application/json: schema: $ref: '#/components/schemas/v1.createSecretResponse' description: Created "400": content: application/json: schema: type: string description: Bad Request "404": content: application/json: schema: type: string description: Not Found - Provider not setup "405": content: application/json: schema: type: string description: Method Not Allowed - Provider doesn't support writing "409": content: application/json: schema: type: string description: Conflict - Secret already exists "500": content: application/json: schema: type: string description: Internal Server Error summary: Create a new secret tags: - secrets /api/v1beta/secrets/default/keys/{key}: delete: description: Delete a secret from the default provider (encrypted provider only) parameters: - description: Secret key in: path name: key required: true schema: type: string responses: "204": content: application/json: schema: type: string description: No Content "404": content: application/json: schema: type: string description: Not Found - Provider not setup or secret not found "405": content: application/json: schema: type: string description: Method Not Allowed - Provider doesn't support deletion "500": content: application/json: schema: type: string description: Internal Server Error summary: Delete a secret tags: - secrets put: description: Update an existing secret in the default provider (encrypted provider only) parameters: - description: Secret key in: path name: key required: true schema: type: string requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/v1.updateSecretRequest' description: Update secret request summary: request description: Update secret request required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.updateSecretResponse' description: OK "400": content: application/json: schema: type: string description: Bad Request "404": content: application/json: schema: type: string description: Not Found - Provider not setup or secret not found "405": content: application/json: schema: type: string description: Method Not Allowed - Provider doesn't support writing "500": content: application/json: schema: type: string description: Internal Server Error summary: Update a secret tags: - secrets /api/v1beta/version: get: description: Returns the current version of the server responses: "200": content: application/json: schema: $ref: '#/components/schemas/v1.versionResponse' description: OK summary: Get server version tags: - version /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/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/v1.createRequest' description: Create workload request summary: request description: Create workload request required: true responses: "201": content: application/json: schema: $ref: '#/components/schemas/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 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: 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/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/v1.updateRequest' description: Update workload request summary: request description: Update workload request required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/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/runner.RunConfig' description: OK "404": content: application/json: schema: type: string description: Not Found summary: Export workload configuration tags: - workloads /api/v1beta/workloads/{name}/logs: get: description: Retrieve at most 1000 lines of logs for a specific workload by name. parameters: - description: Workload name in: path name: name required: true schema: type: string responses: "200": content: text/plain: schema: type: string description: Logs for the specified workload "400": content: text/plain: schema: type: string description: Invalid workload name "404": content: text/plain: schema: type: string description: Not Found summary: Get logs for a specific workload tags: - logs /api/v1beta/workloads/{name}/proxy-logs: get: description: Retrieve at most 1000 lines of proxy logs for a specific workload by name from the file system. parameters: - description: Workload name in: path name: name required: true schema: type: string responses: "200": content: text/plain: schema: type: string description: Proxy logs for the specified workload "400": content: text/plain: schema: type: string description: Invalid workload name "404": content: text/plain: schema: type: string description: Proxy logs not found for workload summary: Get proxy logs for a specific workload tags: - logs /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/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/delete: post: description: Delete multiple workloads by name or by group requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/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 "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/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/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 /health: get: description: Check if the API is healthy responses: "204": content: application/json: schema: type: string description: No Content summary: Health check tags: - system