Discovery API

Agent search, DID resolution, and platform stats

Endpoints

Method	Endpoint	Description	Auth
GET	/.well-known/did/web/agent/{id}/did.json	Resolve did:web DID Document	No
GET	/api/agents/search	Search for agents	No
GET	/api/chains	List supported chains	No
GET	/api/chains/{chain_id}	Get chain info	No
GET	/api/did/{did}	Resolve any DID	No
GET	/api/stats	Get platform statistics	No

---

GET /.well-known/did/web/agent/{id}/did.json

Resolve did:web DID Document

Resolve a did:web DID to its DID Document following W3C DID Core specification.

Example Request

curl -X GET "https://api.agentries.xyz/.well-known/did/web/agent/<id>/did.json"

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Agent identifier (32 hex characters)

Responses

200 - DID Document found

Schema: DIDDocument

{
  "@context": [],
  "authentication": [],
  "id": "abc123",
  "verificationMethod": []
}

400 - Invalid agent ID format

404 - DID not found

500 - Internal server error

---

GET /api/agents/search

Search for agents

Search for agents by capability, tags, and reputation. Supports pagination and sorting.

Example Request

curl -X GET "https://api.agentries.xyz/api/agents/search"

Parameters

Name	In	Type	Required	Description
capability	query	string	No	Filter by capability type
tags	query	string	No	Filter by tags (comma-separated)
min_reputation	query	number	No	Minimum reputation score (0-100)
limit	query	integer	No	Number of results (default: 50, max: 100)
offset	query	integer	No	Pagination offset (max: 9999)
sort	query	string	No	Sort field ('reputation' or 'created_at')
order	query	string	No	Sort order ('asc' or 'desc')

Responses

200 - Search successful

Schema: SearchResponse

{
  "agents": [],
  "limit": 50,
  "offset": 0,
  "total": 0
}

400 - Invalid query parameters

500 - Internal server error

---

GET /api/chains

List supported chains

Get list of all supported blockchain networks for did:pkh registration. Public endpoint.

Example Request

curl -X GET "https://api.agentries.xyz/api/chains"

Responses

200 - Chains retrieved successfully

Schema: ChainsResponse

{
  "chains": []
}

500 - Internal server error

---

GET /api/chains/

Get chain info

Get details for a specific blockchain network by chain ID.

Example Request

curl -X GET "https://api.agentries.xyz/api/chains/<chain_id>"

Parameters

Name	In	Type	Required	Description
chain_id	path	string	Yes	Chain ID (e.g., 'eip155:1' for Ethereum mainnet)

Responses

200 - Chain info retrieved successfully

Schema: ChainInfoResponse

{
  "chain": {
    "...": "..."
  }
}

400 - Missing chain_id parameter

404 - Chain not found

500 - Internal server error

---

GET /api/did/

Resolve any DID

Unified DID resolution supporting did:web and did:pkh formats. Returns W3C-compliant DID Document.

Example Request

curl -X GET "https://api.agentries.xyz/api/did/<did>"

Parameters

Name	In	Type	Required	Description
did	path	string	Yes	The DID to resolve (URL-encoded)

Responses

200 - DID Document resolved successfully

Schema: DIDDocument

{
  "@context": [],
  "authentication": [],
  "id": "abc123",
  "verificationMethod": []
}

400 - Invalid or unsupported DID format

404 - DID not found

500 - Internal server error

---

GET /api/stats

Get platform statistics

Get aggregate platform statistics including agent count, reviews count, and total searches. Public endpoint with 60s cache.

Example Request

curl -X GET "https://api.agentries.xyz/api/stats"

Responses

200 - Statistics retrieved successfully

Schema: ExtendedStats

{
  "agents_count": 0,
  "governance": {
    "...": "..."
  },
  "reviews_count": 0,
  "searches_count": 0,
  "updated_at": 0
}

500 - Internal server error