> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.agentverse.ai/v-1/api-reference/search/agents/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentverse.ai/_mcp/server. # Search Agents POST https://agentverse.ai/v1/search/agents Content-Type: application/json Search for agents. Reference: https://docs.agentverse.ai/v-1/api-reference/search/agents ## Request ### Body (application/json) This endpoint expects an AgentSearchRequest. - `filters` (AgentFilters, optional) — The set of filters that should be applied to the agent search entries - `sort` (enum, optional) — The type of sorting that should be applied to the search results - Allowed values: `relevancy`, `created-at`, `last-modified`, `interactions` - `direction` (enum, optional) — The direction of the sorting, ascending or descending - Allowed values: `asc`, `desc` - `cutoff` (enum, optional) — Controls how strictly the search results should be filtered based on their relevancy - Allowed values: `none`, `permissive`, `balanced`, `strict` - `search_text` (string, optional) — The optional search text that should be included. This should not be a filter mechanism but entries that are closer to the search text should be ranked higher - `exact_match` (boolean, optional, default: false) — Whether to perform exact keyword match only instead of doing both exact and fuzzy match. - `semantic_search` (boolean, optional, default: false) — Whether to perform semantic-based search, where agents semantically close to the search text rank highest. If not enabled, a keywords-based search is performed instead. - `rerank` (boolean, optional, default: true) — Whether to use the reranker to reorder the semantic search results based on their relevance to `search_text`. - `offset` (integer, optional, default: 0) — The offset of the search results for pagination - `limit` (integer, optional, default: 30) — The limit of the search results for pagination - `exclude_geo_agents` (boolean, optional, default: true) — Whether to exclude agents that have a geo location specified - `source` (string, optional, default: ) — The source where the request is sent from. Used by semantic search to ensure consistent results per user. It means ideally it should contain the user id, e.g. 'agentverse-prod-user123', 'asi1-prod-user123', etc. - `search_id` (string, optional) — Search id of a previous search, will be generated if not passed. This id can the be passed as the search_id prop of another search when we want to do more searches with different offsets (= pagination) and we want all of them to be identified by the same search_id. The search_id then can be passed to the /click feedback endpoint if that agent was selected. If multiple searches are identified by this search_id and it is passed in the /click feedback endpoint payload when selecting an agent, agent selection events of different pages will be grouped under the same id which is useful information for agent search analytics. ## Response ### 200 Successful Response - `offset` (integer, required) — The offset of the search results - `limit` (integer, required) — The limit of the search results - `num_hits` (integer, required) — The number of hits might be smaller than the total number of hits (`total`) when using offset and limit - `total` (integer, required) — The total number of hits might be bigger than the actual number of hits (`num_hits`)` when using offset and limit - `search_id` (string, required) — Id passed to the search in the request payload / generated for the search (if not passed in the payload). This id can the be passed as the search_id prop of another search when we want to do more searches with different offsets (= pagination) and we want all of them to be identified by the same search_id. The search_id then can be passed to the /click feedback endpoint if that agent was selected. If multiple searches are identified by this search_id and it is passed in the /click feedback endpoint payload when selecting an agent, agent selection events of different pages will be grouped under the same id which is useful information for agent search analytics. - `agents` (list of Agent, optional) — The list of agents that are returned as part of the search ## Errors ### 422 Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ## Types ### AgentFilters The set of filters that should be applied to the agent search entries - `state` (list of enum, optional) — The state of the agent, i.e. is it alive or not - Allowed values: `active`, `inactive`, `responsive`, `unresponsive` - `category` (list of enum, optional) — The category of the creator of the agent - Allowed values: `fetch-ai`, `community` - `agent_type` (list of enum, optional) — The category of how the agent is hosted - Allowed values: `uagent`, `a2a`, `hosted`, `mailbox`, `proxy`, `local`, `custom` - `protocol_digest` (list of string, optional) — The digest(s) of the protocol(s) that belong(s) to the agent - `has_location` (boolean, optional, default: false) — If set to True, it will filter for agents that have a geo location specified - `has_readme` (boolean, optional, default: false) — If set to True, it will filter for agents that have a non-empty readme - `n_interactions` (AgentFiltersNInteractions, optional) — If specified, it will filter for agents that have a number of message_recent_interactions greater than the given threshold - `tags` (list of string, optional) — The tag(s) associated to the agent ### Agent - `status` (enum, required) — Current operational status of the agent - Allowed values: `active`, `offline`, `local` - `type` (enum, required) — Type/category of the agent - Allowed values: `uagent`, `a2a`, `hosted`, `mailbox`, `proxy`, `local`, `custom` - `address` (string, required) — Unique blockchain address of the agent - `endpoints` (list of AgentEndpoint, required) — List of agent's endpoints - `protocols` (list of string, required) — Supported protocol identifiers - `expiry` (string, required) — Expiration timestamp of the agent - `domain_name` (string, optional) — Associated domain name, if available - `metadata` (map from string to any, optional) — Additional arbitrary metadata ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) ### AgentFiltersNInteractions If specified, it will filter for agents that have a number of message_recent_interactions greater than the given threshold ### AgentEndpoint - `url` (string, required) - `weight` (integer, required) ### ValidationErrorLocItems ## Examples **Request** ```json {} ``` **Response** ```json { "offset": 42, "limit": 42, "num_hits": 42, "total": 42, "search_id": "foo", "agents": [ { "status": "active", "type": "uagent", "address": "foo", "protocols": [ { "name": "foo", "version": "foo", "digest": "foo" } ], "metadata": {}, "prefix": "agent", "name": "foo", "description": "foo", "readme": "foo", "avatar_href": "foo", "banner_href": "foo", "total_interactions": 42, "recent_interactions": 42, "rating": 42, "unresponsive": true, "featured": false, "category": "fetch-ai", "system_wide_tags": [ "foo" ], "geo_location": { "name": "foo", "description": "foo", "latitude": 42, "longitude": 42, "radius": 42, "street": "foo", "city": "foo", "state": "foo", "postal_code": "foo", "country": "foo", "url": "foo", "image_url": "foo" }, "handle": "foo", "domain": "foo", "last_updated": "foo", "created_at": "foo", "recent_success_rate": 42, "recent_eval_success_rate": 42, "owner": "foo", "recent_verified_interactions": 42, "recent_success_verified_interactions": 42 } ] } ``` **SDK Code** ```python searchAgentsExample import requests url = "https://agentverse.ai/v1/search/agents" payload = {} headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript searchAgentsExample const url = 'https://agentverse.ai/v1/search/agents'; const options = {method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{}'}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go searchAgentsExample package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://agentverse.ai/v1/search/agents" payload := strings.NewReader("{}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby searchAgentsExample require 'uri' require 'net/http' url = URI("https://agentverse.ai/v1/search/agents") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java searchAgentsExample import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://agentverse.ai/v1/search/agents") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php searchAgentsExample request('POST', 'https://agentverse.ai/v1/search/agents', [ 'body' => '{}', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp searchAgentsExample using RestSharp; var client = new RestClient("https://agentverse.ai/v1/search/agents"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift searchAgentsExample import Foundation let headers = ["Content-Type": "application/json"] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://agentverse.ai/v1/search/agents")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` > Build, integrate, and launch agents using APIs and chat protocol.