API reference

• clients
  • getList all clients
  • postRegister a new client
  • postRegister multiple clients
  • delUnregister a client
  • delUnregister a client from a specific group
  • postUnregister multiple clients
• discovery
  • getList all clients status
• groups
  • postCreate a new group
  • delDelete a group
  • getGet group details
  • getList all groups
• logs
  • getGet logs for a specific workload
  • getGet proxy logs for a specific workload
• registry
  • postAdd a registry
  • getGet a registry
  • getGet a server from a registry
  • getList registries
  • getList servers in a registry
  • delRemove a registry
  • putUpdate registry configuration
• secrets
  • postCreate a new secret
  • delDelete a secret
  • getGet secrets provider details
  • getList secrets
  • postSetup or reconfigure secrets provider
  • putUpdate a secret
• system
  • getGet OpenAPI specification
  • getHealth check
• version
  • getGet server version
• workloads
  • postCreate a new workload
  • delDelete a workload
  • postDelete workloads in bulk
  • getExport workload configuration
  • getGet workload details
  • getGet workload status
  • getList all workloads
  • postRestart a workload
  • postRestart workloads in bulk
  • postStop a workload
  • postStop workloads in bulk
  • postUpdate workload

API docs by Redocly

ToolHive API (1.0)

Download OpenAPI specification:Download

This is the ToolHive API server.

clients

List all clients

List all registered clients in ToolHive

Responses

http://localhost:8080/api/v1beta/clients

Response samples

• 200

Content type

application/json

[

• {

  • "groups": [

    • "string"

    ],
  • "name": "roo-code"

  }

]

Register a new client

Register a new client with ToolHive

Request Body schema: application/json

required

Client to register

One of

object

Responses

http://localhost:8080/api/v1beta/clients

Request samples

• Payload

Content type

application/json

Example

v1.createClientRequest

{ }

Response samples

• 200
• 400

Content type

application/json

{

• "groups": [

  • "string"

  ],
• "name": "roo-code"

}

Register multiple clients

Register multiple clients with ToolHive

Request Body schema: application/json

required

Clients to register

One of

object

Responses

http://localhost:8080/api/v1beta/clients/register

Request samples

• Payload

Content type

application/json

Example

v1.bulkClientRequest

{ }

Response samples

• 200
• 400

Content type

application/json

[

• {

  • "groups": [

    • "string"

    ],
  • "name": "roo-code"

  }

]

Unregister a client

Unregister a client from ToolHive

path Parameters

name required

string Client name to unregister

Responses

http://localhost:8080/api/v1beta/clients/{name}

Response samples

• 400

Content type

application/json

"string"

Unregister a client from a specific group

Unregister a client from a specific group in ToolHive

path Parameters

name required	string Client name to unregister
group required	string Group name to remove client from

Responses

http://localhost:8080/api/v1beta/clients/{name}/groups/{group}

Response samples

• 400
• 404

Content type

application/json

"string"

Unregister multiple clients

Unregister multiple clients from ToolHive

Request Body schema: application/json

required

Clients to unregister

One of

object

Responses

http://localhost:8080/api/v1beta/clients/unregister

Request samples

• Payload

Content type

application/json

Example

v1.bulkClientRequest

{ }

Response samples

• 400

Content type

application/json

"string"

discovery

List all clients status

List all clients compatible with ToolHive and their status

Responses

http://localhost:8080/api/v1beta/discovery/clients

Response samples

• 200

Content type

application/json

{

• "clients": [

  • {

    • "client_type": "roo-code",
    • "installed": true,
    • "registered": true

    }

  ]

}

groups

Create a new group

Create a new group with the specified name

Request Body schema: application/json

required

Group creation request

One of

object

Responses

http://localhost:8080/api/v1beta/groups

Request samples

• Payload

Content type

application/json

Example

v1.createGroupRequest

{ }

Response samples

• 201
• 400
• 409
• 500

Content type

application/json

{

• "name": "string"

}

Delete a group

Delete a group by name.

path Parameters

name required

string Group name

query Parameters

with-workloads

boolean Delete all workloads in the group (default: false, moves workloads to default group)

Responses

http://localhost:8080/api/v1beta/groups/{name}

Response samples

• 204
• 404
• 500

Content type

application/json

"string"

Get group details

Get details of a specific group

path Parameters

name required

string Group name

Responses

http://localhost:8080/api/v1beta/groups/{name}

Response samples

• 200
• 404
• 500

Content type

application/json

{

• "name": "string",
• "registered_clients": [

  • "string"

  ]

}

List all groups

Get a list of all groups

Responses

http://localhost:8080/api/v1beta/groups

Response samples

• 200
• 500

Content type

application/json

{

• "groups": [

  • {

    • "name": "string",
    • "registered_clients": [

      • "string"

      ]

    }

  ]

}

logs

Get logs for a specific workload

Retrieve at most 100 lines of logs for a specific workload by name.

path Parameters

name required

string Workload name

Responses

http://localhost:8080/api/v1beta/workloads/{name}/logs

Get proxy logs for a specific workload

Retrieve proxy logs for a specific workload by name from the file system.

path Parameters

name required

string Workload name

Responses

http://localhost:8080/api/v1beta/workloads/{name}/proxy-logs

registry

Add a registry

Add a new registry

Request Body schema: application/json

object

Responses

http://localhost:8080/api/v1beta/registry

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 501

Content type

application/json

"string"

Get a registry

Get details of a specific registry

path Parameters

name required

string Registry name

Responses

http://localhost:8080/api/v1beta/registry/{name}

Response samples

• 200
• 404

Content type

application/json

{

• "last_updated": "string",
• "name": "string",
• "registry": {

  • "groups": [

    • {

      • "description": "string",
      • "name": "string",
      • "remote_servers": {

        • "property1": {

          • "env_vars": [

            • {

              • "default": "string",
              • "description": "string",
              • "name": "string",
              • "required": true,
              • "secret": true

              }

            ],
          • "headers": [

            • {

              • "choices": [

                • "string"

                ],
              • "default": "string",
              • "description": "string",
              • "name": "string",
              • "required": true,
              • "secret": true

              }

            ],
          • "oauth_config": {

            • "authorize_url": "string",
            • "callback_port": 0,
            • "client_id": "string",
            • "issuer": "string",
            • "oauth_params": {

              • "property1": "string",
              • "property2": "string"

              },
            • "resource": "string",
            • "scopes": [

              • "string"

              ],
            • "token_url": "string",
            • "use_pkce": true

            },
          • "url": "string"

          },
        • "property2": {

          • "env_vars": [

            • {

              • "default": "string",
              • "description": "string",
              • "name": "string",
              • "required": true,
              • "secret": true

              }

            ],
          • "headers": [

            • {

              • "choices": [

                • "string"

                ],
              • "default": "string",
              • "description": "string",
              • "name": "string",
              • "required": true,
              • "secret": true

              }

            ],
          • "oauth_config": {

            • "authorize_url": "string",
            • "callback_port": 0,
            • "client_id": "string",
            • "issuer": "string",
            • "oauth_params": {

              • "property1": "string",
              • "property2": "string"

              },
            • "resource": "string",
            • "scopes": [

              • "string"

              ],
            • "token_url": "string",
            • "use_pkce": true

            },
          • "url": "string"

          }

        },
      • "servers": {

        • "property1": {

          • "args": [

            • "string"

            ],
          • "docker_tags": [

            • "string"

            ],
          • "env_vars": [

            • {

              • "default": "string",
              • "description": "string",
              • "name": "string",
              • "required": true,
              • "secret": true

              }

            ],
          • "image": "string",
          • "permissions": {

            • "name": "string",
            • "network": {

              • "inbound": {

                • "allow_host": [

                  • null

                  ]

                },
              • "mode": "string",
              • "outbound": {

                • "allow_host": [

                  • null

                  ],
                • "allow_port": [

                  • null

                  ],
                • "insecure_allow_all": true

                }

              },
            • "privileged": true,
            • "read": [

              • "string"

              ],
            • "write": [

              • "string"

              ]

            },
          • "provenance": {

            • "attestation": {

              • "predicate": null,
              • "predicate_type": "string"

              },
            • "cert_issuer": "string",
            • "repository_ref": "string",
            • "repository_uri": "string",
            • "runner_environment": "string",
            • "signer_identity": "string",
            • "sigstore_url": "string"

            },
          • "target_port": 0

          },
        • "property2": {

          • "args": [

            • "string"

            ],
          • "docker_tags": [

            • "string"

            ],
          • "env_vars": [

            • {

              • "default": "string",
              • "description": "string",
              • "name": "string",
              • "required": true,
              • "secret": true

              }

            ],
          • "image": "string",
          • "permissions": {

            • "name": "string",
            • "network": {

              • "inbound": {

                • "allow_host": [

                  • null

                  ]

                },
              • "mode": "string",
              • "outbound": {

                • "allow_host": [

                  • null

                  ],
                • "allow_port": [

                  • null

                  ],
                • "insecure_allow_all": true

                }

              },
            • "privileged": true,
            • "read": [

              • "string"

              ],
            • "write": [

              • "string"

              ]

            },
          • "provenance": {

            • "attestation": {

              • "predicate": null,
              • "predicate_type": "string"

              },
            • "cert_issuer": "string",
            • "repository_ref": "string",
            • "repository_uri": "string",
            • "runner_environment": "string",
            • "signer_identity": "string",
            • "sigstore_url": "string"

            },
          • "target_port": 0

          }

        }

      }

    ],
  • "last_updated": "string",
  • "remote_servers": {

    • "property1": {

      • "env_vars": [

        • {

          • "default": "string",
          • "description": "string",
          • "name": "string",
          • "required": true,
          • "secret": true

          }

        ],
      • "headers": [

        • {

          • "choices": [

            • "string"

            ],
          • "default": "string",
          • "description": "string",
          • "name": "string",
          • "required": true,
          • "secret": true

          }

        ],
      • "oauth_config": {

        • "authorize_url": "string",
        • "callback_port": 0,
        • "client_id": "string",
        • "issuer": "string",
        • "oauth_params": {

          • "property1": "string",
          • "property2": "string"

          },
        • "resource": "string",
        • "scopes": [

          • "string"

          ],
        • "token_url": "string",
        • "use_pkce": true

        },
      • "url": "string"

      },
    • "property2": {

      • "env_vars": [

        • {

          • "default": "string",
          • "description": "string",
          • "name": "string",
          • "required": true,
          • "secret": true

          }

        ],
      • "headers": [

        • {

          • "choices": [

            • "string"

            ],
          • "default": "string",
          • "description": "string",
          • "name": "string",
          • "required": true,
          • "secret": true

          }

        ],
      • "oauth_config": {

        • "authorize_url": "string",
        • "callback_port": 0,
        • "client_id": "string",
        • "issuer": "string",
        • "oauth_params": {

          • "property1": "string",
          • "property2": "string"

          },
        • "resource": "string",
        • "scopes": [

          • "string"

          ],
        • "token_url": "string",
        • "use_pkce": true

        },
      • "url": "string"

      }

    },
  • "servers": {

    • "property1": {

      • "args": [

        • "string"

        ],
      • "docker_tags": [

        • "string"

        ],
      • "env_vars": [

        • {

          • "default": "string",
          • "description": "string",
          • "name": "string",
          • "required": true,
          • "secret": true

          }

        ],
      • "image": "string",
      • "permissions": {

        • "name": "string",
        • "network": {

          • "inbound": {

            • "allow_host": [

              • "string"

              ]

            },
          • "mode": "string",
          • "outbound": {

            • "allow_host": [

              • "string"

              ],
            • "allow_port": [

              • 0

              ],
            • "insecure_allow_all": true

            }

          },
        • "privileged": true,
        • "read": [

          • "string"

          ],
        • "write": [

          • "string"

          ]

        },
      • "provenance": {

        • "attestation": {

          • "predicate": null,
          • "predicate_type": "string"

          },
        • "cert_issuer": "string",
        • "repository_ref": "string",
        • "repository_uri": "string",
        • "runner_environment": "string",
        • "signer_identity": "string",
        • "sigstore_url": "string"

        },
      • "target_port": 0

      },
    • "property2": {

      • "args": [

        • "string"

        ],
      • "docker_tags": [

        • "string"

        ],
      • "env_vars": [

        • {

          • "default": "string",
          • "description": "string",
          • "name": "string",
          • "required": true,
          • "secret": true

          }

        ],
      • "image": "string",
      • "permissions": {

        • "name": "string",
        • "network": {

          • "inbound": {

            • "allow_host": [

              • "string"

              ]

            },
          • "mode": "string",
          • "outbound": {

            • "allow_host": [

              • "string"

              ],
            • "allow_port": [

              • 0

              ],
            • "insecure_allow_all": true

            }

          },
        • "privileged": true,
        • "read": [

          • "string"

          ],
        • "write": [

          • "string"

          ]

        },
      • "provenance": {

        • "attestation": {

          • "predicate": null,
          • "predicate_type": "string"

          },
        • "cert_issuer": "string",
        • "repository_ref": "string",
        • "repository_uri": "string",
        • "runner_environment": "string",
        • "signer_identity": "string",
        • "sigstore_url": "string"

        },
      • "target_port": 0

      }

    },
  • "version": "string"

  },
• "server_count": 0,
• "source": "string",
• "type": "file",
• "version": "string"

}

Get a server from a registry

Get details of a specific server in a registry

path Parameters

name required	string Registry name
serverName required	string ImageMetadata name

Responses

http://localhost:8080/api/v1beta/registry/{name}/servers/{serverName}

Response samples

• 200
• 404

Content type

application/json

{

• "is_remote": true,
• "remote_server": {

  • "env_vars": [

    • {

      • "default": "string",
      • "description": "string",
      • "name": "string",
      • "required": true,
      • "secret": true

      }

    ],
  • "headers": [

    • {

      • "choices": [

        • "string"

        ],
      • "default": "string",
      • "description": "string",
      • "name": "string",
      • "required": true,
      • "secret": true

      }

    ],
  • "oauth_config": {

    • "authorize_url": "string",
    • "callback_port": 0,
    • "client_id": "string",
    • "issuer": "string",
    • "oauth_params": {

      • "property1": "string",
      • "property2": "string"

      },
    • "resource": "string",
    • "scopes": [

      • "string"

      ],
    • "token_url": "string",
    • "use_pkce": true

    },
  • "url": "string"

  },
• "server": {

  • "args": [

    • "string"

    ],
  • "docker_tags": [

    • "string"

    ],
  • "env_vars": [

    • {

      • "default": "string",
      • "description": "string",
      • "name": "string",
      • "required": true,
      • "secret": true

      }

    ],
  • "image": "string",
  • "permissions": {

    • "name": "string",
    • "network": {

      • "inbound": {

        • "allow_host": [

          • "string"

          ]

        },
      • "mode": "string",
      • "outbound": {

        • "allow_host": [

          • "string"

          ],
        • "allow_port": [

          • 0

          ],
        • "insecure_allow_all": true

        }

      },
    • "privileged": true,
    • "read": [

      • "string"

      ],
    • "write": [

      • "string"

      ]

    },
  • "provenance": {

    • "attestation": {

      • "predicate": null,
      • "predicate_type": "string"

      },
    • "cert_issuer": "string",
    • "repository_ref": "string",
    • "repository_uri": "string",
    • "runner_environment": "string",
    • "signer_identity": "string",
    • "sigstore_url": "string"

    },
  • "target_port": 0

  }

}

List registries

Get a list of the current registries

Responses

http://localhost:8080/api/v1beta/registry

Response samples

• 200

Content type

application/json

{

• "registries": [

  • {

    • "last_updated": "string",
    • "name": "string",
    • "server_count": 0,
    • "source": "string",
    • "type": "file",
    • "version": "string"

    }

  ]

}

List servers in a registry

Get a list of servers in a specific registry

path Parameters

name required

string Registry name

Responses

http://localhost:8080/api/v1beta/registry/{name}/servers

Response samples

• 200
• 404

Content type

application/json

{

• "remote_servers": [

  • {

    • "env_vars": [

      • {

        • "default": "string",
        • "description": "string",
        • "name": "string",
        • "required": true,
        • "secret": true

        }

      ],
    • "headers": [

      • {

        • "choices": [

          • "string"

          ],
        • "default": "string",
        • "description": "string",
        • "name": "string",
        • "required": true,
        • "secret": true

        }

      ],
    • "oauth_config": {

      • "authorize_url": "string",
      • "callback_port": 0,
      • "client_id": "string",
      • "issuer": "string",
      • "oauth_params": {

        • "property1": "string",
        • "property2": "string"

        },
      • "resource": "string",
      • "scopes": [

        • "string"

        ],
      • "token_url": "string",
      • "use_pkce": true

      },
    • "url": "string"

    }

  ],
• "servers": [

  • {

    • "args": [

      • "string"

      ],
    • "docker_tags": [

      • "string"

      ],
    • "env_vars": [

      • {

        • "default": "string",
        • "description": "string",
        • "name": "string",
        • "required": true,
        • "secret": true

        }

      ],
    • "image": "string",
    • "permissions": {

      • "name": "string",
      • "network": {

        • "inbound": {

          • "allow_host": [

            • "string"

            ]

          },
        • "mode": "string",
        • "outbound": {

          • "allow_host": [

            • "string"

            ],
          • "allow_port": [

            • 0

            ],
          • "insecure_allow_all": true

          }

        },
      • "privileged": true,
      • "read": [

        • "string"

        ],
      • "write": [

        • "string"

        ]

      },
    • "provenance": {

      • "attestation": {

        • "predicate": null,
        • "predicate_type": "string"

        },
      • "cert_issuer": "string",
      • "repository_ref": "string",
      • "repository_uri": "string",
      • "runner_environment": "string",
      • "signer_identity": "string",
      • "sigstore_url": "string"

      },
    • "target_port": 0

    }

  ]

}

Remove a registry

Remove a specific registry

path Parameters

name required

string Registry name

Responses

http://localhost:8080/api/v1beta/registry/{name}

Response samples

• 204
• 404

Content type

application/json

"string"

Update registry configuration

Update registry URL or local path for the default registry

path Parameters

name required

string Registry name (must be 'default')

Request Body schema: application/json

required

Registry configuration

One of

object

Responses

http://localhost:8080/api/v1beta/registry/{name}

Request samples

• Payload

Content type

application/json

Example

v1.UpdateRegistryRequest

{ }

Response samples

• 200
• 400
• 404

Content type

application/json

{

• "message": "string",
• "type": "string"

}

secrets

Create a new secret

Create a new secret in the default provider (encrypted provider only)

Request Body schema: application/json

required

Create secret request

One of

object

Responses

http://localhost:8080/api/v1beta/secrets/default/keys

Request samples

• Payload

Content type

application/json

Example

v1.createSecretRequest

{ }

Response samples

• 201
• 400
• 404
• 405
• 409
• 500

Content type

application/json

{

• "key": "string",
• "message": "string"

}

Delete a secret

Delete a secret from the default provider (encrypted provider only)

path Parameters

key required

string Secret key

Responses

http://localhost:8080/api/v1beta/secrets/default/keys/{key}

Response samples

• 204
• 404
• 405
• 500

Content type

application/json

"string"

Get secrets provider details

Get details of the default secrets provider

Responses

http://localhost:8080/api/v1beta/secrets/default

Response samples

• 200
• 404
• 500

Content type

application/json

{

• "capabilities": {

  • "can_cleanup": true,
  • "can_delete": true,
  • "can_list": true,
  • "can_read": true,
  • "can_write": true

  },
• "name": "string",
• "provider_type": "string"

}

List secrets

Get a list of all secret keys from the default provider

Responses

http://localhost:8080/api/v1beta/secrets/default/keys

Response samples

• 200
• 404
• 405
• 500

Content type

application/json

{

• "keys": [

  • {

    • "description": "string",
    • "key": "string"

    }

  ]

}

Setup or reconfigure secrets provider

Setup the secrets provider with the specified type and configuration.

Request Body schema: application/json

required

Setup secrets provider request

One of

object

Responses

http://localhost:8080/api/v1beta/secrets

Request samples

• Payload

Content type

application/json

Example

v1.setupSecretsRequest

{ }

Response samples

• 201
• 400
• 500

Content type

application/json

{

• "message": "string",
• "provider_type": "string"

}

Update a secret

Update an existing secret in the default provider (encrypted provider only)

path Parameters

key required

string Secret key

Request Body schema: application/json

required

Update secret request

One of

object

Responses

http://localhost:8080/api/v1beta/secrets/default/keys/{key}

Request samples

• Payload

Content type

application/json

Example

v1.updateSecretRequest

{ }

Response samples

• 200
• 400
• 404
• 405
• 500

Content type

application/json

{

• "key": "string",
• "message": "string"

}

system

Get OpenAPI specification

Returns the OpenAPI specification for the API

Responses

http://localhost:8080/api/openapi.json

Response samples

• 200

Content type

application/json

{ }

Health check

Check if the API is healthy

Responses

http://localhost:8080/health

Response samples

• 204

Content type

application/json

"string"

version

Get server version

Returns the current version of the server

Responses

http://localhost:8080/api/v1beta/version

Response samples

• 200

Content type

application/json

{

• "version": "string"

}

workloads

Create a new workload

Create and start a new workload

Request Body schema: application/json

required

Create workload request

One of

object

Responses

http://localhost:8080/api/v1beta/workloads

Request samples

• Payload

Content type

application/json

Example

v1.createRequest

{ }

Response samples

• 201
• 400
• 409

Content type

application/json

{

• "name": "string",
• "port": 0

}

Delete a workload

Delete a workload

path Parameters

name required

string Workload name

Responses

http://localhost:8080/api/v1beta/workloads/{name}

Response samples

• 202
• 400
• 404

Content type

application/json

"string"

Delete workloads in bulk

Delete multiple workloads by name or by group

Request Body schema: application/json

required

Bulk delete request (names or group)

One of

object

Responses

http://localhost:8080/api/v1beta/workloads/delete

Request samples

• Payload

Content type

application/json

Example

v1.bulkOperationRequest

{ }

Response samples

• 202
• 400

Content type

application/json

"string"

Export workload configuration

Export a workload's run configuration as JSON

path Parameters

name required

string Workload name

Responses

http://localhost:8080/api/v1beta/workloads/{name}/export

Response samples

• 200
• 404

Content type

application/json

{

• "audit_config": {

  • "component": "string",
  • "enabled": true,
  • "eventTypes": [

    • "string"

    ],
  • "excludeEventTypes": [

    • "string"

    ],
  • "includeRequestData": true,
  • "includeResponseData": true,
  • "logFile": "string",
  • "maxDataSize": 0

  },
• "audit_config_path": "string",
• "authz_config": {

  • "type": "string",
  • "version": "string"

  },
• "authz_config_path": "string",
• "base_name": "string",
• "cmd_args": [

  • "string"

  ],
• "container_labels": {

  • "property1": "string",
  • "property2": "string"

  },
• "container_name": "string",
• "debug": true,
• "endpoint_prefix": "string",
• "env_file_dir": "string",
• "env_vars": {

  • "property1": "string",
  • "property2": "string"

  },
• "group": "string",
• "host": "string",
• "ignore_config": {

  • "loadGlobal": true,
  • "printOverlays": true

  },
• "image": "string",
• "isolate_network": true,
• "jwks_auth_token_file": "string",
• "k8s_pod_template_patch": "string",
• "middleware_configs": [

  • {

    • "parameters": { },
    • "type": "string"

    }

  ],
• "name": "string",
• "oidc_config": {

  • "allowPrivateIP": true,
  • "audience": "string",
  • "authTokenFile": "string",
  • "cacertPath": "string",
  • "clientID": "string",
  • "clientSecret": "string",
  • "insecureAllowHTTP": true,
  • "introspectionURL": "string",
  • "issuer": "string",
  • "jwksurl": "string",
  • "resourceURL": "string",
  • "scopes": [

    • "string"

    ]

  },
• "permission_profile": {

  • "name": "string",
  • "network": {

    • "inbound": {

      • "allow_host": [

        • "string"

        ]

      },
    • "mode": "string",
    • "outbound": {

      • "allow_host": [

        • "string"

        ],
      • "allow_port": [

        • 0

        ],
      • "insecure_allow_all": true

      }

    },
  • "privileged": true,
  • "read": [

    • "string"

    ],
  • "write": [

    • "string"

    ]

  },
• "permission_profile_name_or_path": "string",
• "port": 0,
• "proxy_mode": "sse",
• "remote_auth_config": {

  • "authorize_url": "string",
  • "bearer_token": "string",
  • "bearer_token_file": "string",
  • "callback_port": 0,
  • "client_id": "string",
  • "client_secret": "string",
  • "client_secret_file": "string",
  • "env_vars": [

    • {

      • "default": "string",
      • "description": "string",
      • "name": "string",
      • "required": true,
      • "secret": true

      }

    ],
  • "headers": [

    • {

      • "choices": [

        • "string"

        ],
      • "default": "string",
      • "description": "string",
      • "name": "string",
      • "required": true,
      • "secret": true

      }

    ],
  • "issuer": "string",
  • "oauth_params": {

    • "property1": "string",
    • "property2": "string"

    },
  • "resource": "string",
  • "scopes": [

    • "string"

    ],
  • "skip_browser": true,
  • "timeout": "5m",
  • "token_url": "string",
  • "use_pkce": true

  },
• "remote_url": "string",
• "schema_version": "string",
• "secrets": [

  • "string"

  ],
• "target_host": "string",
• "target_port": 0,
• "telemetry_config": {

  • "customAttributes": {

    • "property1": "string",
    • "property2": "string"

    },
  • "enablePrometheusMetricsPath": true,
  • "endpoint": "string",
  • "environmentVariables": [

    • "string"

    ],
  • "headers": {

    • "property1": "string",
    • "property2": "string"

    },
  • "insecure": true,
  • "metricsEnabled": true,
  • "samplingRate": "string",
  • "serviceName": "string",
  • "serviceVersion": "string",
  • "tracingEnabled": true

  },
• "thv_ca_bundle": "string",
• "token_exchange_config": {

  • "audience": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "external_token_header_name": "string",
  • "header_strategy": "string",
  • "scopes": [

    • "string"

    ],
  • "subject_token_type": "string",
  • "token_url": "string"

  },
• "tools_filter": [

  • "string"

  ],
• "tools_override": {

  • "property1": {

    • "description": "string",
    • "name": "string"

    },
  • "property2": {

    • "description": "string",
    • "name": "string"

    }

  },
• "transport": "stdio",
• "trust_proxy_headers": true,
• "volumes": [

  • "string"

  ]

}

Get workload details

Get details of a specific workload

path Parameters

name required

string Workload name

Responses

http://localhost:8080/api/v1beta/workloads/{name}

Response samples

• 200
• 404

Content type

application/json

{

• "authz_config": "string",
• "cmd_arguments": [

  • "string"

  ],
• "env_vars": {

  • "property1": "string",
  • "property2": "string"

  },
• "group": "string",
• "headers": [

  • {

    • "choices": [

      • "string"

      ],
    • "default": "string",
    • "description": "string",
    • "name": "string",
    • "required": true,
    • "secret": true

    }

  ],
• "host": "string",
• "image": "string",
• "name": "string",
• "network_isolation": true,
• "oauth_config": {

  • "authorize_url": "string",
  • "bearer_token": {

    • "name": "string",
    • "target": "string"

    },
  • "callback_port": 0,
  • "client_id": "string",
  • "client_secret": {

    • "name": "string",
    • "target": "string"

    },
  • "issuer": "string",
  • "oauth_params": {

    • "property1": "string",
    • "property2": "string"

    },
  • "resource": "string",
  • "scopes": [

    • "string"

    ],
  • "skip_browser": true,
  • "token_url": "string",
  • "use_pkce": true

  },
• "oidc": {

  • "audience": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "introspection_url": "string",
  • "issuer": "string",
  • "jwks_url": "string",
  • "scopes": [

    • "string"

    ]

  },
• "permission_profile": {

  • "name": "string",
  • "network": {

    • "inbound": {

      • "allow_host": [

        • "string"

        ]

      },
    • "mode": "string",
    • "outbound": {

      • "allow_host": [

        • "string"

        ],
      • "allow_port": [

        • 0

        ],
      • "insecure_allow_all": true

      }

    },
  • "privileged": true,
  • "read": [

    • "string"

    ],
  • "write": [

    • "string"

    ]

  },
• "proxy_mode": "string",
• "proxy_port": 0,
• "secrets": [

  • {

    • "name": "string",
    • "target": "string"

    }

  ],
• "target_port": 0,
• "tools": [

  • "string"

  ],
• "tools_override": {

  • "property1": {

    • "description": "string",
    • "name": "string"

    },
  • "property2": {

    • "description": "string",
    • "name": "string"

    }

  },
• "transport": "string",
• "trust_proxy_headers": true,
• "url": "string",
• "volumes": [

  • "string"

  ]

}

Get workload status

Get the current status of a specific workload

path Parameters

name required

string Workload name

Responses

http://localhost:8080/api/v1beta/workloads/{name}/status

Response samples

• 200
• 404

Content type

application/json

{

• "status": "running"

}

List all workloads

Get a list of all running workloads, optionally filtered by group

query Parameters

all	boolean List all workloads, including stopped ones
group	string Filter workloads by group name

Responses

http://localhost:8080/api/v1beta/workloads

Response samples

• 200
• 404

Content type

application/json

{

• "workloads": [

  • {

    • "created_at": "string",
    • "group": "string",
    • "labels": {

      • "property1": "string",
      • "property2": "string"

      },
    • "name": "string",
    • "package": "string",
    • "port": 0,
    • "proxy_mode": "string",
    • "remote": true,
    • "status": "running",
    • "status_context": "string",
    • "tools": [

      • "string"

      ],
    • "transport_type": "stdio",
    • "url": "string"

    }

  ]

}

Restart a workload

Restart a running workload

path Parameters

name required

string Workload name

Responses

http://localhost:8080/api/v1beta/workloads/{name}/restart

Response samples

• 202
• 400
• 404

Content type

application/json

"string"

Restart workloads in bulk

Restart multiple workloads by name or by group

Request Body schema: application/json

required

Bulk restart request (names or group)

One of

object

Responses

http://localhost:8080/api/v1beta/workloads/restart

Request samples

• Payload

Content type

application/json

Example

v1.bulkOperationRequest

{ }

Response samples

• 202
• 400

Content type

application/json

"string"

Stop a workload

Stop a running workload

path Parameters

name required

string Workload name

Responses

http://localhost:8080/api/v1beta/workloads/{name}/stop

Response samples

• 202
• 400
• 404

Content type

application/json

"string"

Stop workloads in bulk

Stop multiple workloads by name or by group

Request Body schema: application/json

required

Bulk stop request (names or group)

One of

object

Responses

http://localhost:8080/api/v1beta/workloads/stop

Request samples

• Payload

Content type

application/json

Example

v1.bulkOperationRequest

{ }

Response samples

• 202
• 400

Content type

application/json

"string"

Update workload

Update an existing workload configuration

path Parameters

name required

string Workload name

Request Body schema: application/json

required

Update workload request

One of

object

Responses

http://localhost:8080/api/v1beta/workloads/{name}/edit

Request samples

• Payload

Content type

application/json

Example

v1.updateRequest

{ }

Response samples

• 200
• 400
• 404

Content type

application/json

{

• "name": "string",
• "port": 0

}