Skip to main content

API reference

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

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

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "name": "roo-code"
}

Register multiple clients

Register multiple clients with ToolHive

Request Body schema: application/json
required

Clients to register

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
[
  • {
    }
]

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"

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

Response samples

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

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
"string"

discovery

List all clients status

List all clients compatible with ToolHive and their status. Each object includes supports_skills when ToolHive can install skills for that client.

Responses

Response samples

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

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

Request samples

Content type
application/json
Example
{ }

Response samples

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

Response samples

Content type
application/json
"string"

Get group details

Get details of a specific group

path Parameters
name
required
string

Group name

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "registered_clients": [
    ],
  • "skills": [
    ]
}

List all groups

Get a list of all groups

Responses

Response samples

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

logs

Get logs for a specific workload

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

path Parameters
name
required
string

Workload name

Responses

Get proxy logs for a specific workload

Retrieve at most 1000 lines of proxy logs for a specific workload by name from the file system.

path Parameters
name
required
string

Workload name

Responses

registry

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"

Get a registry

Get details of a specific registry

path Parameters
name
required
string

Registry name

Responses

Response samples

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

Response samples

Content type
application/json
{
  • "is_remote": true,
  • "remote_server": {
    },
  • "server": {
    }
}

List registries

Get a list of the current registries

Responses

Response samples

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

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
{
  • "remote_servers": [
    ],
  • "servers": [
    ]
}

Refresh registry cache

Force a refresh of the server-side registry cache for the default registry

path Parameters
name
required
string

Registry name (must be 'default')

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Registry login

Trigger an interactive OAuth flow to authenticate with the configured registry. Only available in serve mode.

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Registry logout

Clear cached OAuth tokens for the configured registry. Only available in serve mode.

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Remove a registry

Remove a specific registry

path Parameters
name
required
string

Registry name

Responses

Response samples

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

Request samples

Content type
application/json
Example
{ }

Response samples

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

registry-servers

Get a registry server

Retrieve a single server by name. Names use reverse-DNS format; URL-encode slashes.

path Parameters
registryName
required
string

Registry name (currently ignored, uses the default provider)

serverName
required
string

Server name (URL-encoded reverse-DNS format)

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  • "_meta": {
    },
  • "description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
  • "icons": [],
  • "name": "io.github.user/weather",
  • "packages": [
    ],
  • "remotes": [
    ],
  • "repository": {},
  • "title": "Weather API",
  • "version": "1.0.2",
  • "websiteUrl": "https://modelcontextprotocol.io/examples"
}

List available registry servers

Get a paginated list of servers from the registry. Supports optional full-text search and pagination.

path Parameters
registryName
required
string

Registry name (currently ignored, uses the default provider)

query Parameters
q
string

Search filter — matches against server name and description

page
integer

Page number, 1-based (default: 1)

limit
integer

Items per page, max 200 (default: 50)

Responses

Response samples

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

registry-skills

Get a registry skill

Retrieve a single skill by its namespace and name from the registry.

path Parameters
registryName
required
string

Registry name (currently ignored, uses the default provider)

namespace
required
string

Skill namespace in reverse-DNS format (e.g. io.github.stacklok)

skillName
required
string

Skill name

Responses

Response samples

Content type
application/json
{
  • "_meta": {
    },
  • "allowedTools": [
    ],
  • "compatibility": "string",
  • "description": "string",
  • "icons": [
    ],
  • "license": "string",
  • "metadata": {
    },
  • "name": "string",
  • "namespace": "string",
  • "packages": [
    ],
  • "repository": {
    },
  • "status": "string",
  • "title": "string",
  • "version": "string"
}

List available registry skills

Get a paginated list of skills from the registry. Supports optional full-text search and pagination.

path Parameters
registryName
required
string

Registry name (currently ignored, uses the default provider)

query Parameters
q
string

Search filter — matches against skill name, namespace, and description

page
integer

Page number, 1-based (default: 1)

limit
integer

Items per page, max 200 (default: 50)

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "skills": [
    ]
}

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

Request samples

Content type
application/json
Example
{ }

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"

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": [
    ]
}

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

Request samples

Content type
application/json
Example
{ }

Response samples

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

Request samples

Content type
application/json
Example
{ }

Response samples

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

skills

Build a skill

Build a skill from a local directory

Request Body schema: application/json
required

Build request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Delete a locally-built skill artifact

Remove a locally-built OCI skill artifact and its blobs from the local store

path Parameters
tag
required
string

Artifact tag

Responses

Response samples

Content type
application/json
"string"

Get skill content

Retrieve the SKILL.md body and file listing from an artifact without installing it. Accepts OCI refs, git refs, or local tags.

query Parameters
ref
required
string

OCI reference or local build tag

Responses

Response samples

Content type
application/json
{
  • "body": "string",
  • "description": "string",
  • "files": [
    ],
  • "license": "string",
  • "name": "string",
  • "version": "string"
}

Get skill details

Get detailed information about a specific skill

path Parameters
name
required
string

Skill name

query Parameters
scope
string
Enum: "user" "project"

Filter by scope (user or project)

project_root
string

Project root path for project-scoped skills

Responses

Response samples

Content type
application/json
{
  • "installed_skill": {
    },
  • "metadata": {
    }
}

Install a skill

Install a skill from a remote source

Request Body schema: application/json
required

Install request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

List all installed skills

Get a list of all installed skills

query Parameters
scope
string
Enum: "user" "project"

Filter by scope (user or project)

client
string

Filter by client app

project_root
string

Filter by project root path

group
string

Filter by group name

Responses

Response samples

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

List locally-built skill artifacts

Get a list of all locally-built OCI skill artifacts in the local store

Responses

Response samples

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

Push a skill

Push a built skill artifact to a remote registry

Request Body schema: application/json
required

Push request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
"string"

Uninstall a skill

Remove an installed skill

path Parameters
name
required
string

Skill name

query Parameters
scope
string
Enum: "user" "project"

Scope to uninstall from (user or project)

project_root
string

Project root path for project-scoped skills

Responses

Response samples

Content type
application/json
"string"

Validate a skill

Validate a skill definition

Request Body schema: application/json
required

Validate request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "valid": true,
  • "warnings": [
    ]
}

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"

version

Get server version

Returns the current version of the server

Responses

Response samples

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

workloads

Apply an available upgrade to a workload

Apply a registry-sourced upgrade to a single workload. This re-resolves and verifies the candidate image, pulls it, and only then recreates the workload with the new image, preserving the existing configuration. If the workload is already up to date or is not registry-sourced, the current check result is returned unchanged (no-op). Secret values are never accepted or returned.

path Parameters
name
required
string

Workload name

Request Body schema: application/json

Upgrade options

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Check a workload for an available upgrade

Check whether a single workload has a newer image available in its source registry. This is an offline metadata comparison; it does not pull images. Secret values are never returned.

path Parameters
name
required
string

Workload name

Responses

Response samples

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

Check workloads for available upgrades

Check all workloads (optionally filtered by group) for newer images available in their source registries. This is an offline metadata comparison; it does not pull images. Secret values are never returned.

query Parameters
all
boolean

Include stopped workloads

group
string

Filter workloads by group name

Responses

Response samples

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

Create a new workload

Create and start a new workload

Request Body schema: application/json
required

Create workload request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Delete a workload

Delete a workload asynchronously. Returns 202 Accepted immediately. The deletion happens in the background. Poll the workload list to confirm deletion.

path Parameters
name
required
string

Workload name

Responses

Response samples

Content type
application/json
"string"

Delete workloads in bulk

Delete multiple workloads by name or by group asynchronously. Returns 202 Accepted immediately. Deletion happens in the background.

Request Body schema: application/json
required

Bulk delete request (names or group)

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
"string"

Export workload configuration

Export a workload's run configuration as JSON

path Parameters
name
required
string

Workload name

Responses

Response samples

Content type
application/json
{
  • "allow_docker_gateway": true,
  • "audit_config": {
    },
  • "audit_config_path": "string",
  • "authz_config": {
    },
  • "authz_config_path": "string",
  • "aws_sts_config": {
    },
  • "base_name": "string",
  • "cmd_args": [
    ],
  • "container_labels": {
    },
  • "container_name": "string",
  • "debug": true,
  • "embedded_auth_server_config": {
    },
  • "endpoint_prefix": "string",
  • "env_file_dir": "string",
  • "env_vars": {
    },
  • "group": "string",
  • "header_forward": {
    },
  • "host": "string",
  • "ignore_config": {
    },
  • "image": "string",
  • "isolate_network": true,
  • "jwks_auth_token_file": "string",
  • "k8s_pod_template_patch": "string",
  • "mcpserver_generation": 0,
  • "middleware_configs": [
    ],
  • "mutating_webhooks": [
    ],
  • "name": "string",
  • "oidc_config": {
    },
  • "permission_profile_name_or_path": "string",
  • "port": 0,
  • "proxy_mode": "sse",
  • "publish": [
    ],
  • "rate_limit_config": {
    },
  • "rate_limit_namespace": "string",
  • "registry_api_url": "string",
  • "registry_server_name": "string",
  • "registry_url": "string",
  • "remote_auth_config": {
    },
  • "remote_url": "string",
  • "runtime_config": {
    },
  • "scaling_config": {
    },
  • "schema_version": "string",
  • "secrets": [
    ],
  • "session_ttl": "2h",
  • "stateless": true,
  • "target_host": "string",
  • "target_port": 0,
  • "telemetry_config": {
    },
  • "thv_ca_bundle": "string",
  • "token_exchange_config": {
    },
  • "tools_filter": [
    ],
  • "tools_override": {
    },
  • "transport": "stdio",
  • "trust_proxy_headers": true,
  • "upstream_swap_config": {
    },
  • "validating_webhooks": [
    ],
  • "volumes": [
    ]
}

Get workload details

Get details of a specific workload

path Parameters
name
required
string

Workload name

Responses

Response samples

Content type
application/json
{
  • "authz_config": "string",
  • "cmd_arguments": [
    ],
  • "env_vars": {
    },
  • "group": "string",
  • "header_forward": {
    },
  • "headers": [
    ],
  • "host": "string",
  • "image": "string",
  • "name": "string",
  • "network_isolation": true,
  • "oauth_config": {
    },
  • "oidc": {
    },
  • "permission_profile": {
    },
  • "proxy_mode": "string",
  • "proxy_port": 0,
  • "registry": "string",
  • "runtime_config": {
    },
  • "secrets": [
    ],
  • "server": "string",
  • "target_port": 0,
  • "tools": [
    ],
  • "tools_override": {
    },
  • "transport": "string",
  • "trust_proxy_headers": true,
  • "url": "string",
  • "volumes": [
    ]
}

Get workload status

Get the current status of a specific workload

path Parameters
name
required
string

Workload name

Responses

Response samples

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

Response samples

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

Restart a workload

Restart a running workload

path Parameters
name
required
string

Workload name

Responses

Response samples

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

Request samples

Content type
application/json
Example
{ }

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"

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

Request samples

Content type
application/json
Example
{ }

Response samples

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

Request samples

Content type
application/json
Example
{ }

Response samples

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