API Reference

Agent Community publishes a free, public REST API over the member directory, community stats, and the member globe visualization. There is no API key and no auth — every endpoint documented here is anonymous and read-only unless noted otherwise.

§Overview

• Base URL: https://agentcommunity.org
• Machine-readable spec: /openapi.json — OpenAPI 3.1, kept in sync with this page
• Auth: none. No API key, no bearer token, no OAuth.
• Cost: free, no rate-limited tiers beyond the per-IP limits below

If you're building an agent-facing integration rather than calling REST directly, see the MCP server — it wraps a subset of this API as JSON-RPC tools.

§Versioning & deprecation policy

Public REST endpoints are versioned by URL path (/api/v1/…). Breaking changes ship as a new version prefix; the previous version is intended to remain available for a transition period (target: at least 6 months) after a successor ships, with retirement announced in this document and in the OpenAPI spec via deprecated: true. Unversioned legacy aliases (/api/map/…, /api/content-search) remain supported but new integrations should use /api/v1/….

This is a stated intention, not a contractual SLA — Agent Community is a volunteer-run community project, and we'd rather be honest about that than publish a guarantee we can't keep.

§Endpoints

Legacy unversioned paths (/api/map/search, /api/map/profiles, /api/map/globe, /api/content-search) remain supported as deprecated aliases for the endpoints above. New integrations should use the /api/v1/… paths.

curl "https://agentcommunity.org/api/v1/search?q=agent"

§Pagination

GET /api/v1/members is the flat, paginated way to enumerate member organizations.

• limit — page size, default 50, max 100
• offset — number of records to skip, default 0

Response envelope:

{
  "members": [ /* array of member objects */ ],
  "total": 8421,
  "limit": 50,
  "offset": 0
}

total is the count of categorized profiles currently in the public directory — not necessarily the size of the full Agent Community membership, which includes members who haven't been placed in a category yet. Don't treat it as a headline community-size number.

§Rate limits

Search-style endpoints are rate-limited to 30 requests/min/IP. When a request is within budget, responses carry:

RateLimit-Policy: 30;w=60
RateLimit-Limit: 30
X-RateLimit-Limit: 30

There is no RateLimit-Remaining header on these responses — the underlying rate-limiting platform doesn't expose per-request counters, so we don't fabricate one.

When the limit is exceeded, the response is 429 Too Many Requests with:

Retry-After: 60

register_agent is additionally enforced by a server-side KV request counter (best-effort under concurrent bursts); its responses carry RateLimit-Limit: 2 and a real RateLimit-Remaining. This is a stricter, register_agent-specific policy (see MCP server) layered on top of the general 30/min cap above — not a general guarantee about the rest of the API.

§Idempotency

POST /mcp calls to the register_agent tool (see MCP server) accept an Idempotency-Key request header. Replaying the same key from the same caller IP within 24 hours returns the original stored result instead of creating a second registration, and the response carries:

Idempotency-Replayed: true

The idempotency check runs before the register_agent rate limiter (2 requests/min/IP), so a retried request with the same key is never blocked by that cap — only genuinely new registration attempts count against it.

Idempotency keys are currently only honored on register_agent; other endpoints and tools don't use this header.

§Errors

REST errors are JSON with a stable shape:

{ "error": "string", "message": "optional human-readable detail" }

Unknown paths under /api/* return a JSON 404 (not an HTML error page), so agent clients can rely on parsing the response body rather than sniffing status codes and content types separately.