Discovery API

Find and discover public agents.

Search Agents

GET /api/discover?query=weather&category=utilities&limit=10
Authorization: Bearer gph_xxx

Response:

{
  "agents": [
    {
      "id": "weather-agent",
      "name": "Weather Agent",
      "description": "Get weather forecasts",
      "category": "utilities",
      "tags": ["weather", "forecast"],
      "avgRating": 4.8,
      "ratingCount": 25,
      "tenantName": "WeatherCo"
    }
  ],
  "count": 1,
  "offset": 0
}

Query parameters:

Param	Description
query	Search text (fuzzy match)
category	Filter by category
tag	Filter by tag
sort	rating, popular, recent
limit	Max results (default 20)
offset	Pagination offset

Get Categories

GET /api/discover/categories

Response:

{
  "categories": [
    {"name": "utilities", "count": 45},
    {"name": "search", "count": 23},
    {"name": "data", "count": 18}
  ]
}

Get Agent Details

GET /api/discover/agents/:agentId

Response:

{
  "agent": {
    "id": "weather-agent",
    "name": "Weather Agent",
    "description": "...",
    "agentCard": {...},
    "stats": {
      "avgRating": 4.8,
      "ratingCount": 25,
      "totalMessages": 10000,
      "successRate": 0.98,
      "avgResponseTime": 250
    }
  },
  "reviews": [
    {
      "rating": 5,
      "review": "Great agent!",
      "created_at": 1709100000,
      "reviewer_name": "User"
    }
  ]
}

Rate an Agent

POST /api/discover/agents/:agentId/rate
Authorization: Bearer gph_xxx
Content-Type: application/json

{
  "rating": 5,
  "review": "Excellent agent, very helpful!"
}

Response:

{
  "success": true,
  "avgRating": 4.85,
  "ratingCount": 26
}