API reference
Register a new client
Register a new client with ToolHive
Request Body schema: application/jsonrequired
Client to register
name | string Name is the type of the client to register. |
Responses
Request samples
- Payload
{- "name": "string"
}
Response samples
- 200
- 400
{- "name": "string"
}
Register multiple clients
Register multiple clients with ToolHive
Request Body schema: application/jsonrequired
Clients to register
names | Array of strings Names is the list of client names to operate on. |
Responses
Request samples
- Payload
{- "names": [
- "string"
]
}
Response samples
- 200
- 400
[- {
- "name": "string"
}
]
Unregister multiple clients
Unregister multiple clients from ToolHive
Request Body schema: application/jsonrequired
Clients to unregister
names | Array of strings Names is the list of client names to operate on. |
Responses
Request samples
- Payload
{- "names": [
- "string"
]
}
Response samples
- 400
"string"
Get a registry
Get details of a specific registry
path Parameters
name required | string Registry name |
Responses
Response samples
- 200
- 404
{- "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
], - "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": {
- "name": "string",
- "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
Response samples
- 200
- 404
{- "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
], - "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 ImageMetadata name |
Responses
Response samples
- 200
- 404
{- "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
], - "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"
}
}
Setup or reconfigure secrets provider
Setup the secrets provider with the specified type and configuration.
Request Body schema: application/jsonrequired
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
- Payload
{- "password": "string",
- "provider_type": "string"
}
Response samples
- 201
- 400
- 500
{- "message": "string",
- "provider_type": "string"
}
Create a new secret
Create a new secret in the default provider (encrypted provider only)
Request Body schema: application/jsonrequired
Create secret request
key | string Secret key name |
value | string Secret value |
Responses
Request samples
- Payload
{- "key": "string",
- "value": "string"
}
Response samples
- 201
- 400
- 404
- 405
- 409
- 500
{- "key": "string",
- "message": "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/jsonrequired
Update secret request
value | string New secret value |
Responses
Request samples
- Payload
{- "value": "string"
}
Response samples
- 200
- 400
- 404
- 405
- 500
{- "key": "string",
- "message": "string"
}
List all workloads
Get a list of all running workloads
query Parameters
all | boolean List all workloads, including stopped ones |
Responses
Response samples
- 200
{- "workloads": [
- {
- "created_at": "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/jsonrequired
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
- Payload
{- "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
{- "name": "string",
- "port": 0
}
Get workload details
Get details of a specific workload
path Parameters
name required | string Workload name |
Responses
Response samples
- 200
- 404
{- "created_at": "string",
- "name": "string",
- "package": "string",
- "port": 0,
- "status": "string",
- "status_context": "string",
- "tool_type": "string",
- "transport_type": "string",
- "url": "string"
}
Delete workloads in bulk
Delete multiple workloads by name
Request Body schema: application/jsonrequired
Bulk delete request
names | Array of strings Names of the workloads to operate on |
Responses
Request samples
- Payload
{- "names": [
- "string"
]
}
Response samples
- 202
- 400
"string"
Restart workloads in bulk
Restart multiple workloads by name
Request Body schema: application/jsonrequired
Bulk restart request
names | Array of strings Names of the workloads to operate on |
Responses
Request samples
- Payload
{- "names": [
- "string"
]
}
Response samples
- 202
- 400
"string"
Stop workloads in bulk
Stop multiple workloads by name
Request Body schema: application/jsonrequired
Bulk stop request
names | Array of strings Names of the workloads to operate on |
Responses
Request samples
- Payload
{- "names": [
- "string"
]
}
Response samples
- 202
- 400
"string"