---
title: API Reference
description: Supported Agent Community HTTP APIs, NLWeb documentation answers, exact member verification through MCP, rate limits, idempotency, and typed JSON errors.
---

# 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`](https://agentcommunity.org/openapi.json) — OpenAPI 3.1
- **Authentication:** none for supported public reads and MCP/A2A
- **Agent member verification:** exact `lookup_member` through [MCP](/docs/mcp-server) or the matching A2A capability

## Supported REST endpoints

| Method | Path | Params | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/globe` | — | Aggregate geographic member data for the globe visualization. |
| `GET` | `/api/v1/content` | `q`, `type`, `limit`, `cursor` (all optional) | Deterministically page published blog, documentation, and static-page content. |
| `GET`, `POST` | `/ask` | Exactly one of `query` or `q`; see [NLWeb documentation answers](/docs/nlweb) | Return a deterministic cited answer from published documentation as JSON or SSE. `query` is preferred; `q` is a PAGE compatibility alias, not an NLWeb v0.55 field. |

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](/docs/mcp-server) 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](/docs/nlweb) documents the exact GET, POST, JSON, and SSE contracts.

## Paginated public content

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

```json
{
  "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
  }
}
```

```bash
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.

```json
{
  "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`.