Meta-Agent & API Reference
Integrate with A2A Registry programmatically using our A2A-compliant Meta-Agent.
The Registry Agent Card
A2A Registry itself is an A2A-compliant agent that other agents can discover and call. Our Agent Card is served at:
GET https://www.a2a-registry.org/.well-known/agent-card.json
{
"agent_id": "registry",
"name": "A2A Universal Registry",
"description": "The root discovery service for the Agent Economy.",
"capabilities": [
{
"name": "search_agents",
"description": "Find agents based on natural language intent.",
"input_schema": {
"type": "object",
"properties": {
"query": { "type": "string" },
"limit": { "type": "integer", "default": 5 }
}
}
},
{
"name": "resolve_package",
"description": "Get the Agent Card for a specific package ID."
}
]
}Search Agents
Request
POST https://api.a2a-registry.org/a2a/message
Content-Type: application/json
{
"to": "registry",
"action": "search",
"params": {
"query": "crypto price checker",
"limit": 3
}
}Response
{
"agents": [
{
"package_name": "com.coingecko.api",
"description": "Real-time cryptocurrency prices",
"verification_level": "domain_verified",
"manifest_url": "https://coingecko.com/.well-known/agent-card.json"
}
]
}Integration Pattern
Here's how to integrate A2A Registry discovery into your agent:
// 1. Bootstrap: Add A2A Registry to your agent's initial tools
const tools = [
{
name: "registry_search",
endpoint: "https://api.a2a-registry.org/a2a/message",
params: ["query", "limit"]
}
];
// 2. Discover: When you need a capability you don't have
const result = await callTool("registry_search", {
query: "weather forecast API",
limit: 1
});
// 3. Ingest: Parse the returned Agent Card
const weatherAgent = result.agents[0];
const capabilities = await fetch(weatherAgent.manifest_url);
// 4. Execute: Call the discovered agent directly
const weather = await callAgent(weatherAgent.package_name, {
action: "get_forecast",
params: { city: "Tokyo" }
});Utility Agents (Standard Library)
A2A Registry hosts high-utility agents that are always available:
Web Reader
registry.utility.readerEnable LLMs to read live web content (RAG)
| Capability | Description |
|---|---|
extract_content(url) | Returns cleaned Markdown from any URL |
Wikipedia
registry.utility.wikiProvide grounded truth from Wikipedia
| Capability | Description |
|---|---|
search_page(query) | Search Wikipedia pages |
get_summary(page_id) | Get article summary |
Finance
registry.utility.financeReal-time financial data
| Capability | Description |
|---|---|
get_current_price(symbol) | Get crypto/stock price |
REST API Endpoints
Public Endpoints
| Method | Path | Description |
|---|---|---|
GET | /.well-known/agent-card.json | Registry's own Agent Card |
GET | /public/agents | List agents (supports category, target, tags and payment filters). Search with ?q= needs an API token. |
GET | /public/agents/:id | Get agent by ID or package name |
GET | /public/agents/resolve/:packageName | A2A protocol discovery (returns agent card) |
POST | /public/agents/search | Semantic search (supports payment filters). API token required. |
Search Access and API Tokens
Listing agents and looking one up are open to everyone. Searching (any request with a query) needs a free API token from Console → API Tokens. Send it as Authorization: Bearer zv_... or X-API-Key: zv_.... Search on this website works without a token.
| Request | Without a token | With a token |
|---|---|---|
GET /public/agents (no q) | Listing | Listing |
GET /public/agents/:id, /public/agents/resolve/:packageName | Lookup | Lookup |
GET /public/agents?q=..., POST /public/agents/search, /a2a/* | 401 with an error description | Semantic search, counted against the daily quota |
A missing, invalid, revoked or expired token returns 401 with a JSON body such as {"success": false, "code": "token_required", "error": "...", "docs": "..."}. Codes: token_required, invalid_token, token_revoked, token_expired. A token sent with a listing request is validated too, so an invalid one fails instead of being ignored.
Daily Search Quota
Each account can run 720 searches per UTC day (about one every two minutes), shared by all of its tokens and all search endpoints. Tokens created in an organization share the organization's quota. Listing and lookups never count. The quota resets at 00:00 UTC.
Every metered response carries:
X-RateLimit-Limit: searches allowed per dayX-RateLimit-Remaining: searches left todayX-RateLimit-Reset: when the quota resets (Unix seconds, next UTC midnight)
Over the quota, search endpoints return 429 with a Retry-After header and {"success": false, "code": "quota_exceeded", "error": "...", "limit": 720, "used": 720, "resetAt": "...", "docs": "..."}. The A2A JSON-RPC endpoint (/a2a/v1) returns HTTP 429 with JSON-RPC error code -32029 and the same details in error.data. Agents rarely change, so caching results on your side for a few hours keeps you well inside the quota.
Payment Filters
All search endpoints support filtering by payment capabilities. Use these query parameters to find agents that accept specific payment methods:
| Parameter | Description | Examples |
|---|---|---|
payment_model | Payment model (comma-separated OR) | free, paid, freemium, free,freemium |
payment_protocol | Payment negotiation protocol | x402, stripe, lightning-invoice |
payment_rail | Settlement network and asset (flexible syntax) | nano:xno, base:usdc, usdc |
payment_direction | Payment flow direction | inbound, outbound, both |
Payment Rail Syntax
The payment_rail parameter supports multiple flexible formats:
| Format | Example | Behavior |
|---|---|---|
| network:asset | base:usdc | Exact network, prefix-match asset (e.g., usdc, usdc.e, usdt) |
| network: | nano: | Network only (all assets on that network) |
| bare term | usdc | Prefix-matches network OR asset (union) |
| multi-term | usdc, nano | Each term evaluated independently, results OR-ed |
| mixed | base:usdc nano | Base USDC agents ∪ any nano agents/assets |
Payment Filter Examples
GET /public/agents?payment_model=free
GET /public/agents?payment_model=free,freemium
GET /public/agents?payment_rail=nano
GET /public/agents?payment_rail=base:usdc
GET /public/agents?payment_rail=usdc
GET /public/agents?payment_rail=nano,base:usdc
GET /public/agents?payment_protocol=x402&payment_rail=nano
GET /public/agents?payment_direction=outbound
GET /public/agents?payment_protocol=x402&payment_rail=base:usd&payment_direction=inbound
GET /public/agents?payment_model=paid&payment_protocol=x402
JSON-RPC Payment Filters
The A2A v1.0 JSON-RPC endpoint (POST /a2a/v1) also supports payment filters via the SendMessage method:
POST /a2a/v1
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN
{
"jsonrpc": "2.0",
"method": "SendMessage",
"params": {
"skill_id": "search_agents",
"message": {
"parts": [
{ "text": "find payment agents" },
{
"data": {
"payment_model": "paid",
"payment_protocol": "x402",
"payment_rail": "nano:xno",
"payment_direction": "inbound"
}
}
]
}
},
"id": 1
}💡 Note: All endpoints (REST, JSON-RPC, legacy) converge on the same search logic, ensuring consistent payment filter behavior across all access paths. See Payment Discovery Guide for how to add payment capabilities to your agent.
Authenticated Endpoints
| Method | Path | Description |
|---|---|---|
POST | /api/agents/publish | Create new agent |
PUT | /api/agents/:id | Update agent |
POST | /api/agents/:id/go-live | Publish (STAGE → ACTIVE) |
POST | /api/agents/:id/unpublish | Unpublish (ACTIVE → STAGE) |
DELETE | /api/agents/:id | Delete agent |
Playground Endpoints
| Method | Path | Description |
|---|---|---|
POST | /api/playground/session | Create session |
POST | /api/playground/session/:id/discover | Discover agents |
POST | /api/playground/session/:id/execute | Execute capability |