API reference

• system
  • getGet OpenAPI specification
  • getHealth check
• 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
• servers
  • getList all servers
  • postCreate a new server
  • delDelete a server
  • getGet server details
  • postRestart a server
  • postStop a server
• version
  • getGet server version

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"

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

        • "network": {

          • "outbound": {

            • "allow_host": [

              • "string"

              ],
            • "allow_port": [

              • 0

              ],
            • "allow_transport": [

              • "string"

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

        • "string"

        ],
      • "target_port": 0,
      • "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": {

        • "network": {

          • "outbound": {

            • "allow_host": [

              • "string"

              ],
            • "allow_port": [

              • 0

              ],
            • "allow_transport": [

              • "string"

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

        • "string"

        ],
      • "target_port": 0,
      • "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": {

      • "network": {

        • "outbound": {

          • "allow_host": [

            • "string"

            ],
          • "allow_port": [

            • 0

            ],
          • "allow_transport": [

            • "string"

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

      • "string"

      ],
    • "target_port": 0,
    • "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 Server 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": {

    • "network": {

      • "outbound": {

        • "allow_host": [

          • "string"

          ],
        • "allow_port": [

          • 0

          ],
        • "allow_transport": [

          • "string"

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

    • "string"

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

    • "string"

    ],
  • "transport": "string"

  }

}

servers

List all servers

Get a list of all running servers

Responses

http://localhost:8080/api/v1beta/servers

Response samples

• 200

Content type

application/json

{

• "servers": [

  • {

    • "created": "string",
    • "id": "string",
    • "image": "string",
    • "labels": {

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

      },
    • "name": "string",
    • "ports": [

      • {

        • "containerPort": 0,
        • "hostPort": 0,
        • "protocol": "string"

        }

      ],
    • "state": "string",
    • "status": "string"

    }

  ]

}

Create a new server

Create and start a new server

Request Body schema: application/json

required

Create server 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 server
	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

http://localhost:8080/api/v1beta/servers

Request samples

• Payload

Content type

application/json

{

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

  • "string"

  ],
• "env_vars": [

  • "string"

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

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

  },
• "permission_profile": "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 server

Delete a server

path Parameters

name required

string Server name

query Parameters

force

boolean Force deletion

Responses

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

Response samples

• 204
• 404

Content type

application/json

"string"

Get server details

Get details of a specific server

path Parameters

name required

string Server name

Responses

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

Response samples

• 200
• 404

Content type

application/json

{

• "created": "string",
• "id": "string",
• "image": "string",
• "labels": {

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

  },
• "name": "string",
• "ports": [

  • {

    • "containerPort": 0,
    • "hostPort": 0,
    • "protocol": "string"

    }

  ],
• "state": "string",
• "status": "string"

}

Restart a server

Restart a running server

path Parameters

name required

string Server name

Responses

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

Response samples

• 204
• 404

Content type

application/json

"string"

Stop a server

Stop a running server

path Parameters

name required

string Server name

Responses

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

Response samples

• 204
• 404

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"

}