API Reference

Agent Community publishes a small anonymous HTTP surface for aggregate globe data, paginated public site content, and deterministic documentation answers. Public member names and /m/<slug> profile pages remain human-browsable, but there is no supported free-text member search, profile-feed, or bulk-directory API for agents.

§Overview

• Base URL: https://agentcommunity.org
• Machine-readable spec: /openapi.json — OpenAPI 3.1
• Authentication: none for supported public reads and MCP/A2A
• Agent member verification: exact lookup_member through MCP or the matching A2A capability

§Supported REST endpoints

The legacy /api/map/globe alias and the /api/v1/content-search and /api/content-search raw-array search endpoints remain supported. The content-search endpoints are deprecated for new integrations. /api/map/search is same-origin human /map UI plumbing, not an agent integration.

The table above covers the aggregate, published-content, and documentation-answer endpoints described on this page. Consult the machine-readable OpenAPI document for the complete set of OpenAPI-described REST operations, including batch and sandbox. Separate protocol surfaces such as MCP and A2A have their own discovery documents and guides. Member records are not exposed for bulk reads at any tier, with or without a key — use lookup_member over MCP for a single exact match.

For an /ask answer request, send exactly one flat query or q field; sending both is invalid. A parameterless GET /ask instead returns the endpoint's capability envelope and does not consume the answer-request rate limit. The canonical NLWeb v0.55 request remains the structured POST form with query.text. The NLWeb guide documents the exact GET, POST, JSON, and SSE contracts.

§Paginated public content

curl "https://agentcommunity.org/api/v1/content?q=agent&type=docs&limit=20"

{
  "items": [
    {
      "title": "API Reference",
      "description": "Public API contracts for Agent Community.",
      "href": "/docs/api-reference",
      "type": "docs"
    }
  ],
  "page": {
    "limit": 20,
    "next_cursor": "opaque-cursor-from-response",
    "has_more": true
  }
}

curl --get "https://agentcommunity.org/api/v1/content" \
  --data-urlencode "q=agent" \
  --data-urlencode "type=docs" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=opaque-cursor-from-response"

next_cursor is opaque. Pass it unchanged on the next request. Pagination covers published docs, blog posts, and public pages only; it never queries or enumerates members. The legacy /api/v1/content-search and /api/content-search responses remain unpaginated JSON arrays for backward compatibility and are deprecated for new integrations.

§Exact member lookup

Use the lookup_member MCP tool with an exact display name or slug. Its output is limited to a status and at most five minimal matches containing display_name, member_since, and the canonical public profile_url. It does not accept a category, topic, or broad discovery query.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "lookup_member", "arguments": { "query": "Example Org" } }
}

§Human map-search controls

The same-origin human search path first uses Cloudflare's coarse native 30/60 filter and then an authoritative SQLite Durable Object rolling 10/60 quota. The Durable Object name is a SHA-256 caller-IP hash; raw IPs do not enter its name, storage, logs, response, or RPC arguments. It keeps at most ten timestamps, prunes within the request transaction, and fails closed when the authoritative decision is unavailable. This contract is not an invitation to automate the human UI.

§MCP registration rate limits and idempotency

MCP tools/call requests have a general 30/60 per-IP limit. register_agent has a separate 2/60 write budget and requires explicit current-turn user authorization.

register_agent accepts an Idempotency-Key request header. Reusing the same key, caller IP, and normalized arguments within 24 hours replays the stored result and returns Idempotency-Replayed: true. Reusing a key with different arguments returns JSON-RPC -32602. Cloudflare KV is not a concurrency lock, so use a unique key for each intended registration and reuse it only for retries of that request.

§Errors

Unsupported directory routes return 403. Unknown /api/* paths return a typed JSON 404. Rate-limit rejection returns 429 with Retry-After; an unavailable authoritative human-search decision returns 503. MCP tool errors are represented by isError: true with a JSON error message in content.