API reference

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

API docs by Redocly

ToolHive API (1.0)

Download OpenAPI specification:Download

This is the ToolHive API server.

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"

clients

List all clients

List all registered clients in ToolHive

Responses

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

Response samples

• 200

Content type

application/json

[

• {

  • "name": "string"

  }

]

Register a new client

Register a new client with ToolHive

Request Body schema: application/json

required

Client to register

name	string Name is the type of the client to register.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "name": "string"

}

Response samples

• 200
• 400

Content type

application/json

{

• "name": "string"

}

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"

Register multiple clients

Register multiple clients with ToolHive

Request Body schema: application/json

required

Clients to register

names

Array of strings Names is the list of client names to operate on.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "names": [

  • "string"

  ]

}

Response samples

• 200
• 400

Content type

application/json

[

• {

  • "name": "string"

  }

]

Unregister multiple clients

Unregister multiple clients from ToolHive

Request Body schema: application/json

required

Clients to unregister

names

Array of strings Names is the list of client names to operate on.

Responses

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

Request samples

• Payload

Content type

application/json

{

• "names": [

  • "string"

  ]

}

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": "string",
    • "installed": true,
    • "registered": true

    }

  ]

}

groups

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"

      ]

    }

  ]

}

Create a new group

Create a new group with the specified name

Request Body schema: application/json

required

Group creation request

name	string Name of the group to create

Responses

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

Request samples

• Payload

Content type

application/json

{

• "name": "string"

}

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"

  ]

}

registry

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,
    • "version": "string"

    }

  ]

}

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"

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"

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": {

  • "last_updated": "string",
  • "servers": {

    • "property1": {

      • "args": [

        • "string"

        ],
      • "custom_metadata": {

        • "property1": null,
        • "property2": null

        },
      • "description": "string",
      • "docker_tags": [

        • "string"

        ],
      • "env_vars": [

        • {

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

          }

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

        • "last_updated": "string",
        • "pulls": 0,
        • "stars": 0

        },
      • "name": "string",
      • "permissions": {

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

          • "outbound": {

            • "allow_host": [

              • "string"

              ],
            • "allow_port": [

              • 0

              ],
            • "insecure_allow_all": 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"

        },
      • "repository_url": "string",
      • "status": "string",
      • "tags": [

        • "string"

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

        • "string"

        ],
      • "transport": "string"

      },
    • "property2": {

      • "args": [

        • "string"

        ],
      • "custom_metadata": {

        • "property1": null,
        • "property2": null

        },
      • "description": "string",
      • "docker_tags": [

        • "string"

        ],
      • "env_vars": [

        • {

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

          }

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

        • "last_updated": "string",
        • "pulls": 0,
        • "stars": 0

        },
      • "name": "string",
      • "permissions": {

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

          • "outbound": {

            • "allow_host": [

              • "string"

              ],
            • "allow_port": [

              • 0

              ],
            • "insecure_allow_all": 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"

        },
      • "repository_url": "string",
      • "status": "string",
      • "tags": [

        • "string"

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

        • "string"

        ],
      • "transport": "string"

      }

    },
  • "version": "string"

  },
• "server_count": 0,
• "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

{

• "servers": [

  • {

    • "args": [

      • "string"

      ],
    • "custom_metadata": {

      • "property1": null,
      • "property2": null

      },
    • "description": "string",
    • "docker_tags": [

      • "string"

      ],
    • "env_vars": [

      • {

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

        }

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

      • "last_updated": "string",
      • "pulls": 0,
      • "stars": 0

      },
    • "name": "string",
    • "permissions": {

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

        • "outbound": {

          • "allow_host": [

            • "string"

            ],
          • "allow_port": [

            • 0

            ],
          • "insecure_allow_all": 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"

      },
    • "repository_url": "string",
    • "status": "string",
    • "tags": [

      • "string"

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

      • "string"

      ],
    • "transport": "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

{

• "server": {

  • "args": [

    • "string"

    ],
  • "custom_metadata": {

    • "property1": null,
    • "property2": null

    },
  • "description": "string",
  • "docker_tags": [

    • "string"

    ],
  • "env_vars": [

    • {

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

      }

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

    • "last_updated": "string",
    • "pulls": 0,
    • "stars": 0

    },
  • "name": "string",
  • "permissions": {

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

      • "outbound": {

        • "allow_host": [

          • "string"

          ],
        • "allow_port": [

          • 0

          ],
        • "insecure_allow_all": 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"

    },
  • "repository_url": "string",
  • "status": "string",
  • "tags": [

    • "string"

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

    • "string"

    ],
  • "transport": "string"

  }

}

secrets

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

password	string Password for encrypted provider (optional, can be set via environment variable) TODO Review environment variable for this
provider_type	string Type of the secrets provider (encrypted, 1password, none)

Responses

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

Request samples

• Payload

Content type

application/json

{

• "password": "string",
• "provider_type": "string"

}

Response samples

• 201
• 400
• 500

Content type

application/json

{

• "message": "string",
• "provider_type": "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"

    }

  ]

}

Create a new secret

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

Request Body schema: application/json

required

Create secret request

key	string Secret key name
value	string Secret value

Responses

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

Request samples

• Payload

Content type

application/json

{

• "key": "string",
• "value": "string"

}

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"

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

value

string New secret value

Responses

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

Request samples

• Payload

Content type

application/json

{

• "value": "string"

}

Response samples

• 200
• 400
• 404
• 405
• 500

Content type

application/json

{

• "key": "string",
• "message": "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

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,
    • "status": "string",
    • "status_context": "string",
    • "tool_type": "string",
    • "tools": [

      • "string"

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

    }

  ]

}

Create a new workload

Create and start a new workload

Request Body schema: application/json

required

Create workload request

authz_config	string Authorization configuration
cmd_arguments	Array of strings Command arguments to pass to the container
env_vars	Array of strings Environment variables to set in the container
host	string Host to bind to
image	string Docker image to use
name	string Name of the workload
network_isolation	boolean Whether network isolation is turned on. This applies the rules in the permission profile.
	object (v1.oidcOptions) OIDC configuration options
	object (permissions.Profile) PermissionProfile is the permission profile to use
proxy_mode	string Proxy mode to use
	Array of objects (secrets.SecretParameter) Secret parameters to inject
target_port	integer Port to expose from the container
tools	Array of strings Tools filter
transport	string Transport configuration
volumes	Array of strings Volume mounts

Responses

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

Request samples

• Payload

Content type

application/json

{

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

  • "string"

  ],
• "env_vars": [

  • "string"

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

  • "allow_opaque_tokens": true,
  • "audience": "string",
  • "client_id": "string",
  • "issuer": "string",
  • "jwks_url": "string"

  },
• "permission_profile": {

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

    • "outbound": {

      • "allow_host": [

        • "string"

        ],
      • "allow_port": [

        • 0

        ],
      • "insecure_allow_all": true

      }

    },
  • "read": [

    • "string"

    ],
  • "write": [

    • "string"

    ]

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

  • {

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

    }

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

  • "string"

  ],
• "transport": "string",
• "volumes": [

  • "string"

  ]

}

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"

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

{

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

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

  },
• "name": "string",
• "package": "string",
• "port": 0,
• "status": "string",
• "status_context": "string",
• "tool_type": "string",
• "tools": [

  • "string"

  ],
• "transport_type": "string",
• "url": "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",
  • "event_types": [

    • "string"

    ],
  • "exclude_event_types": [

    • "string"

    ],
  • "include_request_data": true,
  • "include_response_data": true,
  • "log_file": "string",
  • "max_data_size": 0

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

  • "cedar": {

    • "entities_json": "string",
    • "policies": [

      • "string"

      ]

    },
  • "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,
• "env_vars": {

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

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

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

  },
• "image": "string",
• "isolate_network": true,
• "jwks_allow_private_ip": true,
• "jwks_auth_token_file": "string",
• "k8s_pod_template_patch": "string",
• "name": "string",
• "oidc_config": {

  • "allowOpaqueTokens": true,
  • "allowPrivateIP": true,
  • "audience": "string",
  • "authTokenFile": "string",
  • "cacertPath": "string",
  • "clientID": "string",
  • "issuer": "string",
  • "jwksurl": "string"

  },
• "permission_profile": {

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

    • "outbound": {

      • "allow_host": [

        • "string"

        ],
      • "allow_port": [

        • 0

        ],
      • "insecure_allow_all": true

      }

    },
  • "read": [

    • "string"

    ],
  • "write": [

    • "string"

    ]

  },
• "permission_profile_name_or_path": "string",
• "port": 0,
• "proxy_mode": "string",
• "secrets": [

  • "string"

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

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

    • "string"

    ],
  • "headers": {

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

    },
  • "insecure": true,
  • "samplingRate": 0,
  • "serviceName": "string",
  • "serviceVersion": "string"

  },
• "thv_ca_bundle": "string",
• "tools_filter": [

  • "string"

  ],
• "transport": "string",
• "volumes": [

  • "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"

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"

Delete workloads in bulk

Delete multiple workloads by name or by group

Request Body schema: application/json

required

Bulk delete request (names or group)

group	string Group name to operate on (mutually exclusive with names)
names	Array of strings Names of the workloads to operate on

Responses

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

Request samples

• Payload

Content type

application/json

{

• "group": "string",
• "names": [

  • "string"

  ]

}

Response samples

• 202
• 400

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)

group	string Group name to operate on (mutually exclusive with names)
names	Array of strings Names of the workloads to operate on

Responses

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

Request samples

• Payload

Content type

application/json

{

• "group": "string",
• "names": [

  • "string"

  ]

}

Response samples

• 202
• 400

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)

group	string Group name to operate on (mutually exclusive with names)
names	Array of strings Names of the workloads to operate on

Responses

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

Request samples

• Payload

Content type

application/json

{

• "group": "string",
• "names": [

  • "string"

  ]

}

Response samples

• 202
• 400

Content type

application/json

"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

Response samples

• 200
• 404

Content type

application/jsontext/plainapplication/json

"string"