components: schemas: github_com_stacklok_toolhive-registry-server_internal_config.APIConfig: properties: endpoint: description: |- Endpoint is the base API URL (without path) The registry handler will append the appropriate paths for the MCP Registry API v0.1: - /v0.1/servers - List all servers - /v0.1/servers/{name}/versions - List server versions - /v0.1/servers/{name}/versions/{version} - Get specific version Example: "http://my-registry-api.default.svc.cluster.local/registry" type: string timeout: description: |- Timeout is the per-request timeout for HTTP requests to the API endpoint Accepts a Go duration string (e.g., "30s", "1m"); must be > 0 and <= 5m Defaults to 10s if not specified Useful for public or occasionally-slow upstreams where the default is too aggressive type: string type: object github_com_stacklok_toolhive-registry-server_internal_config.FileConfig: properties: data: description: |- Data is the inline registry data as a JSON string Mutually exclusive with Path and URL - exactly one must be specified Useful for API-created registries where the data is provided directly type: string path: description: |- Path is the path to the registry.json file on the local filesystem Can be absolute or relative to the working directory Mutually exclusive with URL and Data - exactly one must be specified type: string timeout: description: |- Timeout is the timeout for HTTP requests when using URL Defaults to 30s if not specified Only applicable when URL is set type: string url: description: |- URL is the HTTP/HTTPS URL to fetch the registry file from Mutually exclusive with Path and Data - exactly one must be specified HTTPS is required unless the host is localhost or THV_REGISTRY_INSECURE_URL=true type: string type: object github_com_stacklok_toolhive-registry-server_internal_config.FilterConfig: properties: names: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.NameFilterConfig' tags: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.TagFilterConfig' type: object github_com_stacklok_toolhive-registry-server_internal_config.GitAuthConfig: properties: passwordFile: description: |- PasswordFile is the path to a file containing the Git password/token Must be an absolute path; whitespace is trimmed from the content type: string username: description: Username is the Git username for HTTP Basic authentication type: string type: object github_com_stacklok_toolhive-registry-server_internal_config.GitConfig: properties: auth: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.GitAuthConfig' description: Auth contains optional authentication for private repositories branch: description: Branch is the Git branch to use (mutually exclusive with Tag and Commit) type: string commit: description: Commit is the Git commit SHA to use (mutually exclusive with Branch and Tag) type: string path: description: Path is the path to the registry file within the repository type: string repository: description: Repository is the Git repository URL (HTTP/HTTPS/SSH) type: string tag: description: Tag is the Git tag to use (mutually exclusive with Branch and Commit) type: string type: object github_com_stacklok_toolhive-registry-server_internal_config.KubernetesConfig: type: object github_com_stacklok_toolhive-registry-server_internal_config.ManagedConfig: type: object github_com_stacklok_toolhive-registry-server_internal_config.NameFilterConfig: properties: exclude: items: type: string type: array uniqueItems: false include: items: type: string type: array uniqueItems: false type: object github_com_stacklok_toolhive-registry-server_internal_config.SourceType: enum: - git - api - file - managed - kubernetes type: string x-enum-varnames: - SourceTypeGit - SourceTypeAPI - SourceTypeFile - SourceTypeManaged - SourceTypeKubernetes github_com_stacklok_toolhive-registry-server_internal_config.SyncPolicyConfig: properties: interval: type: string type: object github_com_stacklok_toolhive-registry-server_internal_config.TagFilterConfig: properties: exclude: items: type: string type: array uniqueItems: false include: items: type: string type: array uniqueItems: false type: object github_com_stacklok_toolhive-registry-server_internal_service.CreationType: enum: - API - CONFIG type: string x-enum-varnames: - CreationTypeAPI - CreationTypeCONFIG github_com_stacklok_toolhive-registry-server_internal_service.EntryVersionInfo: properties: createdAt: type: string description: type: string title: type: string updatedAt: type: string version: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.Plugin: properties: _meta: additionalProperties: {} type: object createdAt: type: string description: type: string icons: items: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.PluginIcon' type: array uniqueItems: false id: type: string isLatest: type: boolean license: type: string metadata: additionalProperties: {} type: object name: type: string namespace: type: string packages: items: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.PluginPackage' type: array uniqueItems: false repository: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.PluginRepository' status: type: string title: type: string updatedAt: type: string version: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.PluginIcon: properties: label: type: string size: type: string src: type: string type: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.PluginPackage: properties: commit: type: string digest: type: string identifier: type: string mediaType: type: string ref: type: string registryType: type: string subfolder: type: string url: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.PluginRepository: properties: type: type: string url: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.RegistryCreateRequest: properties: claims: additionalProperties: {} description: Authorization claims type: object sources: description: ordered list of source names items: type: string type: array uniqueItems: false type: object github_com_stacklok_toolhive-registry-server_internal_service.RegistryEntriesResponse: properties: entries: items: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryEntryInfo' type: array uniqueItems: false type: object github_com_stacklok_toolhive-registry-server_internal_service.RegistryEntryInfo: properties: createdAt: type: string description: type: string entryType: type: string name: type: string position: type: integer sourceName: type: string title: type: string updatedAt: type: string version: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo: properties: claims: additionalProperties: {} type: object createdAt: type: string creationType: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.CreationType' name: type: string sources: items: type: string type: array uniqueItems: false updatedAt: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.Skill: properties: _meta: additionalProperties: {} type: object allowedTools: items: type: string type: array uniqueItems: false compatibility: type: string createdAt: type: string description: type: string icons: items: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SkillIcon' type: array uniqueItems: false id: type: string isLatest: type: boolean license: type: string metadata: additionalProperties: {} type: object name: type: string namespace: type: string packages: items: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SkillPackage' type: array uniqueItems: false repository: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SkillRepository' status: type: string title: type: string updatedAt: type: string version: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.SkillIcon: properties: label: type: string size: type: string src: type: string type: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.SkillPackage: properties: commit: type: string digest: type: string identifier: type: string mediaType: type: string ref: type: string registryType: type: string subfolder: type: string url: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.SkillRepository: properties: type: type: string url: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.SourceCreateRequest: properties: api: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.APIConfig' description: API endpoint source claims: additionalProperties: {} description: Authorization claims type: object file: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.FileConfig' description: Local file or URL source filter: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.FilterConfig' description: Name/tag filtering rules git: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.GitConfig' description: Git repository source kubernetes: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.KubernetesConfig' description: Kubernetes discovery source managed: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.ManagedConfig' description: Managed registry (no sync) syncPolicy: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.SyncPolicyConfig' description: Sync schedule configuration type: object github_com_stacklok_toolhive-registry-server_internal_service.SourceEntriesResponse: properties: entries: items: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceEntryInfo' type: array uniqueItems: false type: object github_com_stacklok_toolhive-registry-server_internal_service.SourceEntryInfo: properties: claims: additionalProperties: {} type: object entryType: type: string name: type: string versions: items: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.EntryVersionInfo' type: array uniqueItems: false type: object github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo: properties: claims: additionalProperties: {} description: Authorization claims type: object createdAt: type: string creationType: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.CreationType' description: API or CONFIG filterConfig: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.FilterConfig' description: Filtering rules name: type: string sourceConfig: description: Type-specific source configuration sourceType: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.SourceType' description: git, api, file, managed, kubernetes syncSchedule: description: Sync interval string type: string syncStatus: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceSyncStatus' type: description: MANAGED, FILE, REMOTE, KUBERNETES type: string updatedAt: type: string type: object github_com_stacklok_toolhive-registry-server_internal_service.SourceListResponse: properties: sources: items: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo' type: array uniqueItems: false type: object github_com_stacklok_toolhive-registry-server_internal_service.SourceSyncStatus: properties: attemptCount: description: Number of sync attempts type: integer lastAttempt: description: Last sync attempt type: string lastSyncTime: description: Last completed sync attempt type: string message: description: Status or error message type: string phase: description: complete, syncing, failed type: string pluginCount: description: Number of plugins in registry type: integer serverCount: description: Number of servers in registry type: integer skillCount: description: Number of skills in registry type: integer type: object internal_api_v1.entryClaimsResponse: properties: claims: additionalProperties: {} type: object type: object internal_api_v1.meResponse: properties: roles: items: type: string type: array uniqueItems: false subject: type: string type: object internal_api_v1.publishEntryRequest: properties: claims: additionalProperties: {} type: object plugin: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.Plugin' server: $ref: '#/components/schemas/v0.ServerJSON' skill: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.Skill' type: object internal_api_v1.registryListResponse: properties: registries: items: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo' type: array uniqueItems: false type: object internal_api_v1.updateEntryClaimsRequest: properties: claims: additionalProperties: {} type: object type: object internal_api_x_plugins.PluginListMetadata: properties: count: type: integer nextCursor: type: string type: object internal_api_x_plugins.PluginListResponse: properties: metadata: $ref: '#/components/schemas/internal_api_x_plugins.PluginListMetadata' plugins: items: $ref: '#/components/schemas/registry.Plugin' type: array uniqueItems: false type: object internal_api_x_skills.SkillListMetadata: properties: count: type: integer nextCursor: type: string type: object internal_api_x_skills.SkillListResponse: properties: metadata: $ref: '#/components/schemas/internal_api_x_skills.SkillListMetadata' skills: items: $ref: '#/components/schemas/registry.Skill' type: array uniqueItems: false type: object model.Argument: properties: choices: items: type: string type: array uniqueItems: false default: type: string description: type: string format: $ref: '#/components/schemas/model.Format' isRepeated: type: boolean isRequired: type: boolean isSecret: type: boolean name: example: --port type: string placeholder: type: string type: $ref: '#/components/schemas/model.ArgumentType' example: positional value: type: string valueHint: example: file_path type: string variables: additionalProperties: $ref: '#/components/schemas/model.Input' type: object type: object model.ArgumentType: enum: - positional - named type: string x-enum-varnames: - ArgumentTypePositional - ArgumentTypeNamed model.Format: enum: - string - number - boolean - filepath type: string x-enum-varnames: - FormatString - FormatNumber - FormatBoolean - FormatFilePath model.Icon: properties: mimeType: example: image/png type: string sizes: items: type: string type: array uniqueItems: false src: example: https://example.com/icon.png format: uri maxLength: 255 type: string theme: type: string type: object model.Input: properties: choices: items: type: string type: array uniqueItems: false default: type: string description: type: string format: $ref: '#/components/schemas/model.Format' isRequired: type: boolean isSecret: type: boolean placeholder: type: string value: type: string type: object model.KeyValueInput: properties: choices: items: type: string type: array uniqueItems: false default: type: string description: type: string format: $ref: '#/components/schemas/model.Format' isRequired: type: boolean isSecret: type: boolean name: example: SOME_VARIABLE type: string placeholder: type: string value: type: string variables: additionalProperties: $ref: '#/components/schemas/model.Input' type: object type: object model.Package: properties: environmentVariables: description: EnvironmentVariables are set when running the package items: $ref: '#/components/schemas/model.KeyValueInput' type: array uniqueItems: false fileSha256: description: FileSHA256 is the SHA-256 hash for integrity verification (required for mcpb, optional for others) example: fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce pattern: ^[a-f0-9]{64}$ type: string identifier: description: |- Identifier is the package identifier: - For NPM/PyPI/NuGet: package name or ID - For OCI: full image reference (e.g., "ghcr.io/owner/repo:v1.0.0") - For MCPB: direct download URL example: '@modelcontextprotocol/server-brave-search' minLength: 1 type: string packageArguments: description: PackageArguments are passed to the package's binary items: $ref: '#/components/schemas/model.Argument' type: array uniqueItems: false registryBaseUrl: description: RegistryBaseURL is the base URL of the package registry (used by npm, pypi, nuget, cargo; not used by oci, mcpb) example: https://registry.npmjs.org format: uri type: string registryType: description: RegistryType indicates how to download packages (e.g., "npm", "pypi", "cargo", "oci", "nuget", "mcpb") example: npm minLength: 1 type: string runtimeArguments: description: RuntimeArguments are passed to the package's runtime command (e.g., docker, npx) items: $ref: '#/components/schemas/model.Argument' type: array uniqueItems: false runtimeHint: description: RunTimeHint suggests the appropriate runtime for the package example: npx type: string transport: $ref: '#/components/schemas/model.Transport' description: Transport is required and specifies the transport protocol configuration version: description: Version is the package version (required for npm, pypi, nuget; optional for mcpb; not used by oci where version is in the identifier) example: 1.0.2 maxLength: 255 minLength: 1 type: string type: object model.Repository: properties: id: example: b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9 type: string source: example: github type: string subfolder: example: src/everything type: string url: example: https://github.com/modelcontextprotocol/servers format: uri type: string type: object model.Status: enum: - active - deprecated - deleted type: string x-enum-varnames: - StatusActive - StatusDeprecated - StatusDeleted model.Transport: properties: headers: items: $ref: '#/components/schemas/model.KeyValueInput' type: array uniqueItems: false type: example: stdio type: string url: example: https://api.example.com/mcp type: string variables: additionalProperties: $ref: '#/components/schemas/model.Input' type: object type: object registry.Plugin: properties: _meta: additionalProperties: {} description: Meta is an opaque payload with extended meta data details of the plugin. type: object description: description: Description is the description of the plugin. type: string icons: description: Icons is the list of icons for the plugin. items: $ref: '#/components/schemas/registry.SkillIcon' type: array uniqueItems: false license: description: License is the SPDX license identifier of the plugin. type: string metadata: additionalProperties: {} description: |- Metadata is the official metadata of the plugin as reported in the plugin manifest file. type: object name: description: |- Name is the name of the plugin. The format is that of identifiers, e.g. "my-plugin". type: string namespace: description: |- Namespace is the namespace of the plugin. The format is reverse-DNS, e.g. "io.github.user". type: string packages: description: Packages is the list of packages for the plugin. items: $ref: '#/components/schemas/registry.SkillPackage' type: array uniqueItems: false provenance: $ref: '#/components/schemas/registry.Provenance' description: |- Provenance contains the expected certificate identity and attestation constraints for the plugin artifact. repository: $ref: '#/components/schemas/registry.SkillRepository' description: Repository is the source repository of the plugin. status: description: |- Status is the status of the plugin. Can be one of "active", "deprecated", or "archived". type: string title: description: |- Title is the title of the plugin. This is for human consumption, not an identifier. type: string version: description: |- Version is the version of the plugin. Any non-empty string is valid, but ideally it should be either a semantic version or a commit hash. type: string type: object registry.Provenance: properties: attestation: $ref: '#/components/schemas/registry.VerifiedAttestation' cert_issuer: type: string repository_ref: type: string repository_uri: type: string runner_environment: type: string signer_identity: type: string sigstore_url: type: string type: object registry.Skill: properties: _meta: additionalProperties: {} description: Meta is an opaque payload with extended meta data details of the skill. type: object allowedTools: description: |- AllowedTools is the list of tools that the skill is compatible with. This is experimental. items: type: string type: array uniqueItems: false compatibility: description: Compatibility is the environment requirements of the skill. type: string description: description: Description is the description of the skill. type: string icons: description: Icons is the list of icons for the skill. items: $ref: '#/components/schemas/registry.SkillIcon' type: array uniqueItems: false license: description: License is the SPDX license identifier of the skill. type: string metadata: additionalProperties: {} description: |- Metadata is the official metadata of the skill as reported in the SKILL.md file. type: object name: description: |- Name is the name of the skill. The format is that of identifiers, e.g. "my-skill". type: string namespace: description: |- Namespace is the namespace of the skill. The format is reverse-DNS, e.g. "io.github.user". type: string packages: description: Packages is the list of packages for the skill. items: $ref: '#/components/schemas/registry.SkillPackage' type: array uniqueItems: false provenance: $ref: '#/components/schemas/registry.Provenance' description: |- Provenance is the expected signer identity for this skill, checked on first install instead of trust-on-first-use. Absent means unconstrained — most catalog entries won't have this for a while, and that must not break installs; it's an opt-in tightening per entry, not a requirement. Each field constrains independently, and an empty string leaves that dimension unconstrained. Attestation is the exception: setting it at all, even to an empty struct, requires the artifact to be attested, so verification fails against a signature carrying no statement. Its own PredicateType and Predicate then follow the usual rule and constrain only when set. Predicate must be a JSON object; anything else can never match, and Validate rejects it rather than letting it through as a constraint that silently fails every artifact. repository: $ref: '#/components/schemas/registry.SkillRepository' description: Repository is the source repository of the skill. status: description: |- Status is the status of the skill. Can be one of "active", "deprecated", or "archived". type: string title: description: |- Title is the title of the skill. This is for human consumption, not an identifier. type: string version: description: |- Version is the version of the skill. Any non-empty string is valid, but ideally it should be either a semantic version or a commit hash. type: string type: object registry.SkillIcon: properties: label: description: Label is the label of the icon. type: string size: description: Size is the size of the icon. type: string src: description: Src is the source of the icon. type: string type: description: Type is the type of the icon. type: string type: object registry.SkillPackage: properties: commit: description: Commit is the commit of the package. type: string digest: description: Digest is the digest of the package. type: string identifier: description: Identifier is the OCI identifier of the package. type: string mediaType: description: MediaType is the media type of the package. type: string ref: description: Ref is the reference of the package. type: string registryType: description: |- RegistryType is the type of registry the package is from. Can be "oci" or "git". type: string subfolder: description: Subfolder is the subfolder of the package. type: string url: description: URL is the URL of the package. type: string type: object registry.SkillRepository: properties: type: description: Type is the type of the repository. type: string url: description: URL is the URL of the repository. type: string type: object registry.VerifiedAttestation: properties: predicate: {} predicate_type: type: string type: object v0.Metadata: properties: count: type: integer nextCursor: type: string type: object v0.RegistryExtensions: properties: isLatest: type: boolean publishedAt: format: date-time type: string status: $ref: '#/components/schemas/model.Status' statusChangedAt: format: date-time type: string statusMessage: type: string updatedAt: format: date-time type: string type: object v0.ResponseMeta: properties: io.modelcontextprotocol.registry/official: $ref: '#/components/schemas/v0.RegistryExtensions' type: object v0.ServerJSON: properties: $schema: example: https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json format: uri minLength: 1 type: string _meta: $ref: '#/components/schemas/v0.ServerMeta' description: example: MCP server providing weather data and forecasts via OpenWeatherMap API maxLength: 100 minLength: 1 type: string icons: items: $ref: '#/components/schemas/model.Icon' type: array uniqueItems: false name: example: io.github.user/weather maxLength: 200 minLength: 3 pattern: ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$ type: string packages: items: $ref: '#/components/schemas/model.Package' type: array uniqueItems: false remotes: items: $ref: '#/components/schemas/model.Transport' type: array uniqueItems: false repository: $ref: '#/components/schemas/model.Repository' title: example: Weather API maxLength: 100 minLength: 1 type: string version: example: 1.0.2 maxLength: 255 minLength: 1 type: string websiteUrl: example: https://modelcontextprotocol.io/examples format: uri type: string type: object v0.ServerListResponse: properties: metadata: $ref: '#/components/schemas/v0.Metadata' servers: items: $ref: '#/components/schemas/v0.ServerResponse' type: array uniqueItems: false type: object v0.ServerMeta: properties: io.modelcontextprotocol.registry/publisher-provided: additionalProperties: {} type: object type: object v0.ServerResponse: properties: _meta: $ref: '#/components/schemas/v0.ResponseMeta' server: $ref: '#/components/schemas/v0.ServerJSON' type: object securitySchemes: BearerAuth: description: 'OAuth 2.0 Bearer token authentication. Format: "Bearer {token}"' in: header name: Authorization type: apiKey externalDocs: description: "" url: "" info: contact: url: https://github.com/stacklok/toolhive description: |- API for accessing MCP server registry data and deployed server information This API provides endpoints to query the MCP (Model Context Protocol) server registry, get information about available servers, and check the status of deployed servers. Authentication is required by default. Use Bearer token authentication with a valid OAuth/OIDC access token. The /.well-known/oauth-protected-resource endpoint provides OAuth discovery metadata (RFC 9728). license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html title: ToolHive Registry API version: "0.1" openapi: 3.1.0 paths: /openapi.json: get: description: Get the OpenAPI 3.1.0 specification for this API responses: "200": content: application/json: schema: type: object description: OpenAPI 3.1.0 specification "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal Server Error summary: OpenAPI specification tags: - system /registry/{registryName}/v0.1/servers: get: description: Get a list of available servers from a specific registry parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: Pagination cursor for retrieving next set of results in: query name: cursor schema: type: string - description: Maximum number of items to return in: query name: limit schema: type: integer - description: Search servers by name (substring match) in: query name: search schema: type: string - description: Filter by version ('latest' for latest version, or an exact version like '1.2.3') in: query name: version schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/v0.ServerListResponse' description: OK "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "401": content: application/json: schema: additionalProperties: type: string type: object description: Unauthorized "404": content: application/json: schema: additionalProperties: type: string type: object description: Registry not found security: - BearerAuth: [] summary: List servers in specific registry tags: - registry /registry/{registryName}/v0.1/servers/{serverName}/versions: get: description: Returns all available versions for a specific MCP server from a specific registry parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: URL-encoded server name (e.g., \ in: path name: serverName required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/v0.ServerListResponse' description: A list of all versions for the server "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "401": content: application/json: schema: additionalProperties: type: string type: object description: Unauthorized "404": content: application/json: schema: additionalProperties: type: string type: object description: Server not found security: - BearerAuth: [] summary: List all versions of an MCP server in specific registry tags: - registry /registry/{registryName}/v0.1/servers/{serverName}/versions/{version}: get: description: |- Returns detailed information about a specific version of an MCP server from a specific registry. Use the special version `latest` to get the latest version. parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: URL-encoded server name (e.g., \ in: path name: serverName required: true schema: type: string - description: URL-encoded version to retrieve (e.g., \ in: path name: version required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/v0.ServerResponse' description: Detailed server information "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "401": content: application/json: schema: additionalProperties: type: string type: object description: Unauthorized "404": content: application/json: schema: additionalProperties: type: string type: object description: Server or version not found security: - BearerAuth: [] summary: Get specific MCP server version in specific registry tags: - registry /registry/{registryName}/v0.1/x/dev.toolhive/plugins: get: description: List plugins in a registry (paginated, latest versions). parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: Filter by name/description substring in: query name: search schema: type: string - description: Filter by status (comma-separated, e.g. active,deprecated) in: query name: status schema: type: string - description: Max results (default 50, max 100) in: query name: limit schema: type: integer - description: Pagination cursor in: query name: cursor schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/internal_api_x_plugins.PluginListResponse' description: List of plugins "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error security: - BearerAuth: [] summary: List plugins in registry tags: - plugins /registry/{registryName}/v0.1/x/dev.toolhive/plugins/{namespace}/{name}: get: description: Get the latest version of a plugin by namespace and name. parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: Plugin namespace (reverse-DNS) in: path name: namespace required: true schema: type: string - description: Plugin name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/registry.Plugin' description: Plugin details "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Plugin not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error security: - BearerAuth: [] summary: Get latest plugin version tags: - plugins /registry/{registryName}/v0.1/x/dev.toolhive/plugins/{namespace}/{name}/versions: get: description: List all versions of a plugin. parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: Plugin namespace (reverse-DNS) in: path name: namespace required: true schema: type: string - description: Plugin name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/internal_api_x_plugins.PluginListResponse' description: List of plugin versions "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Plugin not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error security: - BearerAuth: [] summary: List plugin versions tags: - plugins /registry/{registryName}/v0.1/x/dev.toolhive/plugins/{namespace}/{name}/versions/{version}: get: description: Get a specific version of a plugin. parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: Plugin namespace (reverse-DNS) in: path name: namespace required: true schema: type: string - description: Plugin name in: path name: name required: true schema: type: string - description: Plugin version in: path name: version required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/registry.Plugin' description: Plugin details "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Plugin or version not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error security: - BearerAuth: [] summary: Get specific plugin version tags: - plugins /registry/{registryName}/v0.1/x/dev.toolhive/skills: get: description: List skills in a registry (paginated, latest versions). parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: Filter by name/description substring in: query name: search schema: type: string - description: Filter by status (comma-separated, e.g. active,deprecated) in: query name: status schema: type: string - description: Max results (default 50, max 100) in: query name: limit schema: type: integer - description: Pagination cursor in: query name: cursor schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/internal_api_x_skills.SkillListResponse' description: List of skills "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error security: - BearerAuth: [] summary: List skills in registry tags: - skills /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}: get: description: Get the latest version of a skill by namespace and name. parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: Skill namespace (reverse-DNS) in: path name: namespace required: true schema: type: string - description: Skill name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/registry.Skill' description: Skill details "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Skill not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error security: - BearerAuth: [] summary: Get latest skill version tags: - skills /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions: get: description: List all versions of a skill. parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: Skill namespace (reverse-DNS) in: path name: namespace required: true schema: type: string - description: Skill name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/internal_api_x_skills.SkillListResponse' description: List of skill versions "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Skill not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error security: - BearerAuth: [] summary: List skill versions tags: - skills /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions/{version}: get: description: Get a specific version of a skill. parameters: - description: Registry name in: path name: registryName required: true schema: type: string - description: Skill namespace (reverse-DNS) in: path name: namespace required: true schema: type: string - description: Skill name in: path name: name required: true schema: type: string - description: Skill version in: path name: version required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/registry.Skill' description: Skill details "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Skill or version not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error security: - BearerAuth: [] summary: Get specific skill version tags: - skills /v1/entries: post: description: Publish a new server, skill, or plugin entry. Exactly one of 'server', 'skill', or 'plugin' must be provided. requestBody: content: application/json: schema: $ref: '#/components/schemas/internal_api_v1.publishEntryRequest' description: Entry to publish (server, skill, or plugin) summary: request description: Entry to publish (server, skill, or plugin) required: true responses: "201": content: application/json: schema: type: object description: Published entry (server or skill) "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "409": content: application/json: schema: additionalProperties: type: string type: object description: Conflict "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Publish entry tags: - v1 /v1/entries/{type}/{name}/claims: get: description: |- Get the claims for an API-published entry name within the managed source. Claims are stored at the entry-name level and are shared by every version of that name. Synced-source entries (git/api/file/kubernetes) are out of scope: their claims come from upstream (the source manifest or the `toolhive.stacklok.dev/authz-claims` annotation) and are surfaced through the `/v1/sources/{name}/entries` and `/v1/registries/{name}/entries` lists. parameters: - description: Entry Type (server or skill) in: path name: type required: true schema: type: string - description: Entry Name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/internal_api_v1.entryClaimsResponse' description: Entry claims "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "403": content: application/json: schema: additionalProperties: type: string type: object description: Forbidden "404": content: application/json: schema: additionalProperties: type: string type: object description: Not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Get entry claims tags: - v1 put: description: Update claims for a published entry name parameters: - description: Entry Type (server or skill) in: path name: type required: true schema: type: string - description: Entry Name in: path name: name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/internal_api_v1.updateEntryClaimsRequest' description: Claims to set summary: request description: Claims to set required: true responses: "204": description: No Content "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "403": content: application/json: schema: additionalProperties: type: string type: object description: Forbidden "404": content: application/json: schema: additionalProperties: type: string type: object description: Not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Update entry claims tags: - v1 /v1/entries/{type}/{name}/versions/{version}: delete: description: Delete a published entry version parameters: - description: Entry Type (server, skill, or plugin) in: path name: type required: true schema: type: string - description: Entry Name in: path name: name required: true schema: type: string - description: Version in: path name: version required: true schema: type: string responses: "204": description: No Content "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Delete published entry tags: - v1 /v1/me: get: description: Returns the authenticated caller's identity and roles responses: "200": content: application/json: schema: $ref: '#/components/schemas/internal_api_v1.meResponse' description: Caller identity and roles "401": content: application/json: schema: additionalProperties: type: string type: object description: Unauthorized summary: Get current user info tags: - v1 /v1/registries: get: description: List all registries responses: "200": content: application/json: schema: $ref: '#/components/schemas/internal_api_v1.registryListResponse' description: Registries list "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: List registries tags: - v1 /v1/registries/{name}: delete: description: Delete a registry by name parameters: - description: Registry Name in: path name: name required: true schema: type: string responses: "204": description: Registry deleted "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "403": content: application/json: schema: additionalProperties: type: string type: object description: Cannot modify config-created registry "404": content: application/json: schema: additionalProperties: type: string type: object description: Registry not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Delete registry tags: - v1 get: description: Get a registry by name parameters: - description: Registry Name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo' description: Registry details "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Registry not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Get registry tags: - v1 put: description: Create a new registry or update an existing one parameters: - description: Registry Name in: path name: name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryCreateRequest' description: Registry configuration summary: request description: Registry configuration required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo' description: Registry updated "201": content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo' description: Registry created "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "403": content: application/json: schema: additionalProperties: type: string type: object description: Cannot modify config-created registry "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Create or update registry tags: - v1 /v1/registries/{name}/entries: get: description: List all entries for a registry parameters: - description: Registry Name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryEntriesResponse' description: Registry entries "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Registry not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: List registry entries tags: - v1 /v1/sources: get: description: List all sources responses: "200": content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceListResponse' description: Sources list "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: List sources tags: - v1 /v1/sources/{name}: delete: description: Delete a source by name parameters: - description: Source Name in: path name: name required: true schema: type: string responses: "204": description: Source deleted "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "403": content: application/json: schema: additionalProperties: type: string type: object description: Cannot modify config-created source "404": content: application/json: schema: additionalProperties: type: string type: object description: Source not found "409": content: application/json: schema: additionalProperties: type: string type: object description: Source in use "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Delete source tags: - v1 get: description: Get a source by name parameters: - description: Source Name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo' description: Source details "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Source not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Get source tags: - v1 put: description: Create a new source or update an existing one parameters: - description: Source Name in: path name: name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceCreateRequest' description: Source configuration summary: request description: Source configuration required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo' description: Source updated "201": content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo' description: Source created "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "403": content: application/json: schema: additionalProperties: type: string type: object description: Cannot modify config-created source "409": content: application/json: schema: additionalProperties: type: string type: object description: Managed source limit reached "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: Create or update source tags: - v1 /v1/sources/{name}/entries: get: description: List all entries for a source parameters: - description: Source Name in: path name: name required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceEntriesResponse' description: Source entries "400": content: application/json: schema: additionalProperties: type: string type: object description: Bad request "404": content: application/json: schema: additionalProperties: type: string type: object description: Source not found "500": content: application/json: schema: additionalProperties: type: string type: object description: Internal server error summary: List source entries tags: - v1