Guest Machines
API referenceCapabilities

Search tools

GET/api/v1/tools/search

Search the caller-visible tool catalog by name and description and return matches ranked by relevance.

Required access

Credentials: service principal, delegated token, user session

Search is restricted to the same caller-visible catalog as the tool list.

Authorization

AuthorizationBearer <token>

An organization-owned automation key, prefixed gsmc_sk_. Already bound to one organization, so it needs no X-Org-Id header. It carries no user identity: it never reaches a private resource however it is scoped, and a run it starts has no user for an interactive tool to reach.

In: header

Query Parameters

namespace?|null
origin?|null
enabled_only?Enabled Only
Defaulttrue
capability?array<>|null
risk_level?array<>|null
q*Q
Length1 <= length <= 200

Header Parameters

X-Org-Id?|

Selects the active organization for a credential that belongs to more than one. Service-principal keys are bound to a single organization and ignore it.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/tools/search?q=string" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"
{  "items": [    {      "origin": "builtin",      "source_id": "string",      "canonical_name": "string",      "display_name": "string",      "namespace": "string",      "summary": "string",      "management_mode": "agent_assignable",      "ui_visibility": "user_catalog",      "enabled": true,      "owned_by_caller": true,      "risk_level": "string",      "capabilities": [        "string"      ]    }  ],  "total": 0,  "truncated": true,  "namespace_counts": {}}
{  "detail": "string",  "error_code": "string",  "request_id": "string"}
{  "detail": "string",  "error_code": "string",  "request_id": "string"}
{  "detail": "string",  "error_code": "string",  "request_id": "string"}
{  "detail": "string",  "error_code": "string",  "request_id": "string"}
{  "detail": "string",  "error_code": "string",  "request_id": "string"}

List tool namespaces GET

List the tool namespaces visible to the caller together with a per-namespace tool count, for building grouped pickers without retrieving the complete catalog.

Retrieve a tool GET

Retrieve one tool's complete public definition, including its risk and capability classifications, by its catalog name.