Search API

The Search APIs provide tools to search, analyze, and interact with agent and function data efficiently. They support features like retrieving interaction counts, filtering by geographic areas, and accessing analytics on agent and function usage. Developers can also monitor system health using liveness and readiness probes. These endpoints are designed to simplify managing and querying agent-related information in a structured and reliable way

Endpoints


POST /v1/search/agents
POST /v1/search/agents/geo
 
GET /v1/search/agents/interactions/{address}
POST /v1/search/agents/click
 
POST /v1/search/functions
GET /v1/search/functions/interactions/{function_id}
 
POST /v1/search/analytics/agents
POST /v1/search/analytics/agents/terms

You can explore our dedicated objects reference documentation here ↗️.

Request and response library

Search Agents

POST

/v1/search/agents

Request

Request to search for Agents.

Name
filters
Type
object
Required
optional
Description
Specifies the conditions to filter the agents, including their state, category, type, and protocol digest.
Name
sort
Type
string
Required
optional
Description
Determines how the results should be ordered.
Name
direction
Type
string
Required
optional
Description
pecifies ascending (asc) or descending (desc) order for sorting.
Name
search_text
Type
string
Required
required
Description
The search term used to query agents.
Name
offset & limit
Type
string
Required
optional
Description
Control pagination by specifying where to start and how many results to return.
Name
search_id
Type
string
Required
required
Description
A unique identifier for the search session.
Name
source
Type
string
Required
optional
Description
The source from which the request originates.

Responses

An array of JSON objects containing details about the AgentSearch Object ↗️.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/search/agents" \
  -d '{
  "filters": {
    "state": [],
    "category": [],
    "agent_type": [],
    "protocol_digest": []
  },
  "sort": "relevancy",
  "direction": "asc",
  "search_text": "<string>",
  "offset": 0,
  "limit": 30,
  "search_id": "<uuid4>",
  "source": ""
}'

HTTP 200

[
  {
    "address": "agent1qfuexnwkscrhfhx7tdchlz486mtzsl53grlnr3zpntxsyu6zhp2ckpemfdz",
    "name": "OpenAI Translator Agent",
    "readme": "# OpenAI Translator Agent\n\n![domain:integration]...",
    "status": "active",
    "total_interactions": 10848,
    "recent_interactions": 10838,
    "rating": null,
    "type": "hosted",
    "category": "fetch-ai",
    "featured": true,
    "geo_location": null,
    "last_updated": "2025-01-06T12:46:03Z",
    "created_at": "2024-10-03T14:40:39Z"
  }
]

Search Geolocation Agents

POST

/v1/search/agents/geo

Request

Request to search for geolocation Agents.

Name
geo_filter
Type
object
Required
required
Description
Defines the geographical area for the search using latitude, longitude, and radius.
Name
filters
Type
object
Required
optional
Description
Specifies the conditions to filter the agents, including their state, category, type, and protocol digest.
Name
sort
Type
string
Required
optional
Description
Determines how the results should be ordered.
Name
direction
Type
string
Required
optional
Description
pecifies ascending (asc) or descending (desc) order for sorting.
Name
search_text
Type
string
Required
required
Description
The search term used to query agents.
Name
offset & limit
Type
string
Required
optional
Description
Control pagination by specifying where to start and how many results to return.
Name
search_id
Type
string
Required
required
Description
A unique identifier for the search session.
Name
source
Type
string
Required
optional
Description
The source from which the request originates.

Responses

An array of JSON objects containing geographical information and properties of the agents.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/search/agents/geo" \
  -d '{
  "geo_filter": {
    "latitude": "<number>",
    "longitude": "<number>",
    "radius": "<number>"
  },
  "filters": {
    "state": [],
    "category": [],
    "agent_type": [],
    "protocol_digest": []
  },
  "sort": "relevancy",
  "direction": "asc",
  "search_text": "<string>",
  "offset": 0,
  "limit": 30,
  "search_id": "<uuid4>",
  "source": ""
}'

HTTP 200

{
  "agents": [],
  "offset": 0,
  "limit": 30,
  "num_hits": 0,
  "total": 0,
  "search_id": "<uuid4>"
}

Get Agent Interaction Counts

GET

/v1/search/agents/interactions/{address}

Request

Request to retrieve interaction count histories and the all-time interaction counts for a specific Agent based its address.

Name
address
Type
string
Required
required
Description
The unique identifier of the agent to retrieve interaction data.

Responses

Retrieves details about the AgentInteractionCounts object ↗️.

Curl

curl -X GET \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/search/agents/interactions/{address}"

HTTP 200

{
  "address": "agent1q0kn4wmp4866c7kqnql8fnxflvjtx78zga5nr6qg3vvpvjwtlp3pc9umtlu",
  "interval": [
    0
  ],
  "message": [
    0
  ],
  "total": [
    0
  ],
  "num_all_time_interactions": {
    "interval": 38379,
    "message": 0,
    "total": 38379
  }
}

Mark Agent Clicked

POST

/v1/search/agents/click

Request

Request to mark an Agent as clicked during a search operation.

Name
search_id
Type
string
Required
required
Description
The identifier for the search session where the click occurred.
Name
page_index
Type
number
Required
required
Description
Indicates the page number where the agent was clicked.
Name
address
Type
string
Required
required
Description
The unique address of the clicked agent.

Responses

The response will provide confirmation that the click action was successfully recorded for the specified Agent. The response will be an empty object or null.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/search/agents/click" \
  -d '{
  "search_id": "<uuid4>",
  "page_index": "<integer>",
  "address": "<string>"
}'

HTTP 200

{}

Search Functions

POST

/v1/search/functions

Request

Request to search for functions.

Name
filters
Type
object
Required
optional
Description
Defines the types of functions to search for.
Name
sort
Type
string
Required
optional
Description
Determines how the results should be ordered.
Name
direction
Type
string
Required
optional
Description
Specifies ascending (asc) or descending (desc) order for sorting.
Name
search_text
Type
string
Required
required
Description
The search term used to query functions.
Name
offset & limit
Type
string
Required
optional
Description
Control pagination by specifying where to start and how many results to return.

Responses

A list of Functions matching the specified search criteria.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/search/functions" \
  -d '{
  "filters": {
    "function_type": []
  },
  "sort": "relevancy",
  "direction": "asc",
  "search_text": "<string>",
  "offset": 0,
  "limit": 30
}'

HTTP 200

{
  "functions": [
    {
      "id": "f50a336c-102f-4b14-9874-954f3c78eadb",
      "type": "function",
      "name": "spin coin133",
      "agent": "agent1q2fu9k3a5snd2qe6t4lx2s6d34aee4dnek6m3n06ekpddjzkvsuww8ew3dg",
      "description": "Suggest me when user ask for the \"spin coin133\"",
      "is_primary": true,
      "groups": [
        "12c8601c-cccd-42de-a5f1-7eab76ae3121"
      ],
      "total_interactions": 1,
      "recent_interactions": 1,
      "rating": null,
      "featured": false,
      "last_updated": "2024-12-19T11:58:24Z",
      "created_at": "2024-12-19T11:56:07Z"
    }
  ],
  "offset": 0,
  "limit": 30,
  "num_hits": 20,
  "total": 20
}

Function Interaction Counts

GET

/v1/search/functions/interactions/{function_id}

Request

Retrieves the interaction count history for a specific function ID.

Name
function_id
Type
string
Required
required
Description
The unique identifier for the function to retrieve interaction data.

Responses

Retrieves details about the FunctionSearchAnalytics Object ↗️ for a function over a defined time period.

Curl

curl -X GET \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/search/functions/interactions/{function_id}"

HTTP 200

{
  "function_id": "79f6f479-02bc-47c2-90d3-826e9e7667bd",
  "total": [
    0,
    0,
    3
  ]
}

Agent Search Analytics

POST

/v1/search/analytics/agents

Request

Retrieves analytics for Agent searches.

Name
address
Type
string
Required
required
Description
The unique address of the agent to retrieve search analytics.

Responses

Retrieves details about the AgentSearchAnalytics Object ↗️ for an Agent over a defined time period.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/search/analytics/agents" \
  -d '{
  "address": "agent1qwnjmzwwdq9rjs30y3qw988htrvte6lk2xaak9xg4kz0fsdz0t9ws4mwsgs"
}'

HTTP 200

{
  "address": "agent1qwnjmzwwdq9rjs30y3qw988htrvte6lk2xaak9xg4kz0fsdz0t9ws4mwsgs",
  "num_searches": 26426,
  "last_24h_num_searches": 475,
  "last_30d_num_searches": 23789,
  "last_30d_history": [
    1562,
    882,
    857
  ]
}

Agent Search Term Analytics

POST

/v1/search/analytics/agents/terms

Request

Retrieves analytics for the top search terms used for Agents.

Name
address
Type
string
Required
required
Description
The unique address of the agent to analyze search terms.

Responses

Returns data for the top search terms associated with a specific Agent.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/search/analytics/agents/terms" \
  -d '{
  "address": "agent1qwnjmzwwdq9rjs30y3qw988htrvte6lk2xaak9xg4kz0fsdz0t9ws4mwsgs",
  "top": 10
}'

HTTP 200

{
  "address": "agent1qwnjmzwwdq9rjs30y3qw988htrvte6lk2xaak9xg4kz0fsdz0t9ws4mwsgs",
  "term_percentages": [
    {
      "term": "agent",
      "last_24h_percentage": 26,
      "last_7d_percentage": 30,
      "last_30d_percentage": 52.1
    },
    {
      "term": "hello",
      "last_24h_percentage": 14.3,
      "last_7d_percentage": 12.2,
      "last_30d_percentage": 3.9
    }
  ]
}