> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Agents

> Search agents by name or description

## Overview

Search across all registered agents in the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Identity Registry by name or description. Returns paginated results with agent metadata.

The search uses a pre-built Redis index that is refreshed every 30 minutes, making queries instant even across 20,000+ agents. Matching is case-insensitive substring search on the agent's name and description fields.

<Info>
  This is a free endpoint (0 Cred Units).
</Info>

## Authentication

| Method       | Header                               | Cost         |
| ------------ | ------------------------------------ | ------------ |
| API Token    | `Authorization: Bearer YOUR_API_KEY` | 0 Cred Units |
| x402 Payment | `X-PAYMENT: <signed_payment>`        | Free         |

## Query Parameters

<ParamField query="q" type="string" required>
  Search query (matches against agent name or description). Minimum 1 character.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number (must be >= 1)
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of agents per page (1-100)
</ParamField>

## Response

<ResponseField name="agents" type="array">
  Array of matching agent objects on this page
</ResponseField>

<ResponseField name="agents[].agent_id" type="integer">
  The ERC-8004 agent ID (ERC-721 token ID)
</ResponseField>

<ResponseField name="agents[].owner" type="string">
  Ethereum address of the agent's owner (checksummed)
</ResponseField>

<ResponseField name="agents[].metadata" type="object">
  Agent registration metadata from tokenURI (null if unavailable)
</ResponseField>

<ResponseField name="agents[].metadata.name" type="string">
  Agent name from registration metadata
</ResponseField>

<ResponseField name="agents[].metadata.description" type="string">
  Agent description from registration metadata
</ResponseField>

<ResponseField name="agents[].metadata.image" type="string">
  Agent image URI from registration metadata
</ResponseField>

<ResponseField name="total_results" type="integer">
  Total number of agents matching the query
</ResponseField>

<ResponseField name="query" type="string">
  The search query that was used
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="limit" type="integer">
  Number of agents per page
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.credprotocol.com/api/v2/agents/search?q=cred&page=1&limit=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const query = 'cred';

  const response = await fetch(`https://api.credprotocol.com/api/v2/agents/search?q=${query}&page=1&limit=10`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  console.log(`Found ${data.total_results} agents matching "${data.query}"`);
  data.agents.forEach(agent => {
    console.log(`Agent #${agent.agent_id} — ${agent.metadata?.name} (owner: ${agent.owner})`);
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.credprotocol.com/api/v2/agents/search',
      params={'q': 'cred', 'page': 1, 'limit': 10},
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  data = response.json()
  print(f"Found {data['total_results']} agents matching \"{data['query']}\"")
  for agent in data['agents']:
      name = agent['metadata']['name'] if agent.get('metadata') else 'Unknown'
      print(f"Agent #{agent['agent_id']} — {name} (owner: {agent['owner']})")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "agents": [
      {
        "agent_id": 42,
        "owner": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "metadata": {
          "name": "Cred Score Agent",
          "description": "On-chain credit scoring for DeFi protocols",
          "image": "ipfs://QmExample123"
        }
      },
      {
        "agent_id": 128,
        "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "metadata": {
          "name": "CredCheck",
          "description": "Automated credential verification",
          "image": "https://example.com/agent.png"
        }
      }
    ],
    "total_results": 2,
    "query": "cred",
    "page": 1,
    "limit": 10
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "page must be >= 1"
  }
  ```

  ```json 422 theme={null}
  {
    "detail": [
      {
        "type": "missing",
        "loc": ["query", "q"],
        "msg": "Field required"
      }
    ]
  }
  ```

  ```json 502 theme={null}
  {
    "detail": "Failed to search agents"
  }
  ```
</ResponseExample>

## Performance

* **Response Time**: Typically under 100ms (reads from a pre-built Redis index)
* **Index Freshness**: Updated every 30 minutes by a background task
* **Data Source**: Agent metadata from on-chain `tokenURI()` calls, cached in Redis