Stacklok workloads API

openapi: 3.2.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_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
    github_com_stacklok_toolhive_pkg_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
    github_com_stacklok_toolhive_pkg_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
    permissions.Profile:
      description: Permission profile to apply
      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
    github_com_stacklok_toolhive_pkg_authserver.DCRUpstreamConfig:
      description: 'DCRConfig enables RFC 7591 Dynamic Client Registration against the

        upstream authorization server. When set, the client credentials are

        obtained at runtime rather than being pre-provisioned via ClientID /

        ClientSecretFile / ClientSecretEnvVar, and ClientID must be left empty.

        Mutually exclusive with ClientID.'
      properties:
        discovery_url:
          description: 'DiscoveryURL is the exact RFC 8414 / OIDC Discovery document URL to

            fetch at runtime. The resolver issues a single GET against this URL

            (no well-known-path fallback) and reads registration_endpoint,

            authorization_endpoint, token_endpoint,

            token_endpoint_auth_methods_supported, and scopes_supported from the

            response. Per RFC 8414 §3.3, the document''s "issuer" field must

            exactly match the upstream issuer configured on the parent

            run-config.


            Use this field when the upstream publishes discovery metadata at a

            path that differs from the issuer-derived well-known paths — for

            example a multi-tenant IdP whose metadata lives at

            https://idp.example.com/tenants/acme/.well-known/openid-configuration.


            Mutually exclusive with RegistrationEndpoint.'
          type: string
        initial_access_token_env_var:
          description: 'InitialAccessTokenEnvVar is the name of an environment variable

            containing the RFC 7591 initial access token. Mutually exclusive with

            InitialAccessTokenFile.'
          type: string
        initial_access_token_file:
          description: 'InitialAccessTokenFile is the path to a file containing the RFC 7591

            initial access token presented to the registration endpoint. Mutually

            exclusive with InitialAccessTokenEnvVar. Both may be omitted for open

            registration endpoints.'
          type: string
        registration_endpoint:
          description: 'RegistrationEndpoint is the RFC 7591 registration endpoint URL used

            directly, bypassing discovery. Because no discovery is performed,

            server-capability fields (token_endpoint_auth_methods_supported,

            scopes_supported) are unavailable on this code path; the caller is

            expected to also supply AuthorizationEndpoint, TokenEndpoint, and an

            explicit Scopes list on the parent OAuth2UpstreamRunConfig. Auth

            method falls back to the resolver''s default (client_secret_basic).


            Mutually exclusive with DiscoveryURL.'
          type: string
        software_id:
          description: 'SoftwareID is the RFC 7591 "software_id" registration metadata value,

            identifying the client software independent of any particular

            registration instance.'
          type: string
        software_statement:
          description: 'SoftwareStatement is the RFC 7591 "software_statement" JWT asserting

            metadata about the client software, signed by a party the authorization

            server trusts.'
          type: string
      type: object
    pkg_api_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
    github_com_stacklok_toolhive_pkg_container_runtime.WorkloadStatus:
      description: Current status of the workload
      enum:
      - running
      - stopped
      - error
      - starting
      - stopping
      - unhealthy
      - removing
      - unknown
      - unauthenticated
      - auth_retrying
      - policy_stopped
      - running
      - stopped
      - error
      - starting
      - stopping
      - unhealthy
      - removing
      - unknown
      - unauthenticated
      - auth_retrying
      - policy_stopped
      - running
      - stopped
      - error
      - starting
      - stopping
      - unhealthy
      - removing
      - unknown
      - unauthenticated
      - auth_retrying
      - policy_stopped
      type: string
      x-enum-varnames:
      - WorkloadStatusRunning
      - WorkloadStatusStopped
      - WorkloadStatusError
      - WorkloadStatusStarting
      - WorkloadStatusStopping
      - WorkloadStatusUnhealthy
      - WorkloadStatusRemoving
      - WorkloadStatusUnknown
      - WorkloadStatusUnauthenticated
      - WorkloadStatusAuthRetrying
      - WorkloadStatusPolicyStopped
    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
    github_com_stacklok_toolhive_pkg_authserver_storage.ACLUserRunConfig:
      description: ACLUserConfig contains ACL user authentication configuration.
      properties:
        password_env_var:
          description: PasswordEnvVar is the environment variable containing the Redis password.
          type: string
        username_env_var:
          description: UsernameEnvVar is the environment variable containing the Redis username.
          type: string
      type: object
    github_com_stacklok_toolhive_pkg_authserver.OAuth2UpstreamRunConfig:
      description: 'OAuth2Config contains OAuth 2.0-specific configuration.

        Required when Type is "oauth2", must be nil when Type is "oidc".'
      properties:
        additional_authorization_params:
          additionalProperties:
            type: string
          description: 'AdditionalAuthorizationParams are extra query parameters to include in

            authorization requests. Useful for provider-specific parameters like

            Google''s access_type=offline.'
          type: object
        allow_private_ips:
          description: 'AllowPrivateIPs permits the upstream provider''s HTTP client to connect to

            private IP ranges (RFC-1918, link-local). When DCRConfig is set, this

            also gates the DCR discovery and registration calls made on this

            upstream''s behalf (see pkg/authserver/runner/dcr_adapter.go), so a

            single flag covers the whole upstream rather than needing a separate

            DCR-specific setting. Use only when the upstream is hosted inside the

            same cluster and has no public endpoint. HTTP-scheme restrictions are

            unchanged — HTTPS is still required for non-localhost hosts. Defaults

            to false.'
          type: boolean
        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.

            Mutually exclusive with DCRConfig: when DCRConfig is set, ClientID is obtained

            at runtime via RFC 7591 Dynamic Client Registration and must be left empty.'
          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
        dcr_config:
          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver.DCRUpstreamConfig'
        identity_from_token:
          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver.IdentityFromTokenRunConfig'
        insecure_allow_http:
          description: 'InsecureAllowHTTP permits plain-HTTP authorization and token endpoint URLs

            for this upstream. Only for in-cluster development environments (e.g. an

            OAuth2 provider served over HTTP in a kind cluster) where TLS is not

            available. Never set this in production.'
          type: boolean
        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
        token_response_mapping:
          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver.TokenResponseMappingRunConfig'
        userinfo:
          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver.UserInfoRunConfig'
      type: object
    pkg_api_v1.upgradeRequest:
      description: Request to apply an available upgrade to a workload. All fields are optional; an empty body applies the upgrade preserving the workload's existing configuration.
      properties:
        env:
          additionalProperties:
            type: string
          description: 'Env holds additional or overriding environment variables to merge into the

            upgraded workload''s configuration.'
          type: object
        secrets:
          description: 'Secrets holds additional secret parameters (`<name>,target=<env>`) to merge

            into the upgraded workload''s configuration. Only references are accepted;

            no secret values are transmitted in the request.'
          items:
            type: string
          type: array
          uniqueItems: false
      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.internal, 172.17.0.1). These are

            blocked by default in the egress proxy even when network isolation is on.

            Only applicable to Docker deployments with network isolation enabled.'
          type: boolean
        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/pkg_api_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.

            Pointer so that omitting the field defaults to network isolation ENABLED (matching the

            `thv run` CLI default); set it explicitly to false to disable network isolation.

            This also applies on update: a request that omits this field enables isolation, so

            clients that build update requests from scratch should send it explicitly to avoid

            unintentionally turning isolation on for a workload that had it off.'
          type: boolean
        oauth_config:
          $ref: '#/components/schemas/pkg_api_v1.remoteOAuthConfig'
        oidc:
          $ref: '#/components/schemas/pkg_api_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
        runtime_config:
          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_container_templates.RuntimeConfig'
        secrets:
          description: Secret parameters to inject
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_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/pkg_api_v1.toolOverride'
          description: Tools over

# --- 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