Skip to main content

API reference

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

Response samples

Content type
application/json
{ }

Health check

Check if the API is healthy

Responses

Response samples

Content type
application/json
"string"

clients

List all clients

List all registered clients in ToolHive

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "name": "string"
}

Unregister a client

Unregister a client from ToolHive

path Parameters
name
required
string

Client name to unregister

Responses

Response samples

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

Request samples

Content type
application/json
{
  • "names": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "names": [
    ]
}

Response samples

Content type
application/json
"string"

discovery

List all clients status

List all clients compatible with ToolHive and their status

Responses

Response samples

Content type
application/json
{
  • "clients": [
    ]
}

registry

List registries

Get a list of the current registries

Responses

Response samples

Content type
application/json
{
  • "registries": [
    ]
}

Add a registry

Add a new registry

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
"string"

Remove a registry

Remove a specific registry

path Parameters
name
required
string

Registry name

Responses

Response samples

Content type
application/json
"string"

Get a registry

Get details of a specific registry

path Parameters
name
required
string

Registry name

Responses

Response samples

Content type
application/json
{
  • "last_updated": "string",
  • "name": "string",
  • "registry": {
    },
  • "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

Response samples

Content type
application/json
{
  • "servers": [
    ]
}

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

Response samples

Content type
application/json
{
  • "server": {
    }
}

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

Request samples

Content type
application/json
{
  • "password": "string",
  • "provider_type": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "provider_type": "string"
}

Get secrets provider details

Get details of the default secrets provider

Responses

Response samples

Content type
application/json
{
  • "capabilities": {
    },
  • "name": "string",
  • "provider_type": "string"
}

List secrets

Get a list of all secret keys from the default provider

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

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

Request samples

Content type
application/json
{
  • "key": "string",
  • "value": "string"
}

Response samples

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

Response samples

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

Request samples

Content type
application/json
{
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "key": "string",
  • "message": "string"
}

version

Get server version

Returns the current version of the server

Responses

Response samples

Content type
application/json
{
  • "version": "string"
}

workloads

List all workloads

Get a list of all running workloads

query Parameters
all
boolean

List all workloads, including stopped ones

Responses

Response samples

Content type
application/json
{
  • "workloads": [
    ]
}

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

object (v1.oidcOptions)

OIDC configuration options

permission_profile
string

Permission profile to apply

Array of objects (secrets.SecretParameter)

Secret parameters to inject

target_port
integer

Port to expose from the container

transport
string

Transport configuration

volumes
Array of strings

Volume mounts

Responses

Request samples

Content type
application/json
{
  • "authz_config": "string",
  • "cmd_arguments": [
    ],
  • "env_vars": [
    ],
  • "host": "string",
  • "image": "string",
  • "name": "string",
  • "oidc": {
    },
  • "permission_profile": "string",
  • "secrets": [
    ],
  • "target_port": 0,
  • "transport": "string",
  • "volumes": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "port": 0
}

Delete a workload

Delete a workload

path Parameters
name
required
string

Workload name

Responses

Response samples

Content type
application/json
"string"

Get workload details

Get details of a specific workload

path Parameters
name
required
string

Workload name

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "name": "string",
  • "package": "string",
  • "port": 0,
  • "status": "string",
  • "status_context": "string",
  • "tool_type": "string",
  • "transport_type": "string",
  • "url": "string"
}

Restart a workload

Restart a running workload

path Parameters
name
required
string

Workload name

Responses

Response samples

Content type
application/json
"string"

Stop a workload

Stop a running workload

path Parameters
name
required
string

Workload name

Responses

Response samples

Content type
application/json
"string"

Delete workloads in bulk

Delete multiple workloads by name

Request Body schema: application/json
required

Bulk delete request

names
Array of strings

Names of the workloads to operate on

Responses

Request samples

Content type
application/json
{
  • "names": [
    ]
}

Response samples

Content type
application/json
"string"

Restart workloads in bulk

Restart multiple workloads by name

Request Body schema: application/json
required

Bulk restart request

names
Array of strings

Names of the workloads to operate on

Responses

Request samples

Content type
application/json
{
  • "names": [
    ]
}

Response samples

Content type
application/json
"string"

Stop workloads in bulk

Stop multiple workloads by name

Request Body schema: application/json
required

Bulk stop request

names
Array of strings

Names of the workloads to operate on

Responses

Request samples

Content type
application/json
{
  • "names": [
    ]
}

Response samples

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

Response samples

Content type
"string"