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

    }

  ]

}

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"

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

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

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

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

query Parameters

all	boolean List all workloads, including stopped ones

Responses

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

Response samples

• 200

Content type

application/json

{

• "workloads": [

  • {

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

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

      },
    • "name": "string",
    • "package": "string",
    • "port": 0,
    • "status": "string",
    • "status_context": "string",
    • "tool_type": "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) Permission profile to apply
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
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,
• "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",
• "labels": {

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

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

Request Body schema: application/json

required

Bulk delete request

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

{

• "names": [

  • "string"

  ]

}

Response samples

• 202
• 400

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

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

Request samples

• Payload

Content type

application/json

{

• "names": [

  • "string"

  ]

}

Response samples

• 202
• 400

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

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

Request samples

• Payload

Content type

application/json

{

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