Rate limits

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api-reference.usecommune.dev/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "REST API MCP server": {
    "url": "https://api-reference.usecommune.dev/mcp"
  }
}

Close

Every request is counted against the credential that made it, never against an address. Three budgets apply:

  • general counts every request.
  • audience, which is tighter, counts only the operations that return subscriber or recipient email addresses.
  • write, equally tight, counts only the operations that change something.

An operation covered by one of the narrow budgets is charged to it and to general, and has to pass both.

From the moment a credential resolves, every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for whichever budget is closest to exhaustion, and RateLimit-Policy listing every budget that applied. RateLimit-Reset is in seconds from now. A 429 additionally carries Retry-After, and its message names the budget that refused: being refused by the audience budget still leaves the rest of the API callable.

GET /rate-limit reports every budget at once, which is what to read rather than inferring the whole picture from the one budget the headers describe.

Example

An audience read, with the audience budget closest to running out, so it is the one the triple describes:

HTTP/1.1 200 OK
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 41
RateLimit-Policy: "general";q=600;w=60, "audience";q=60;w=60

The same budget, spent:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 12
RateLimit-Policy: "general";q=600;w=60, "audience";q=60;w=60
{
  "error": {
    "code": "rate_limited",
    "message": "This key has spent its \"audience\" rate limit budget of 60 requests per 60 seconds. Reads that return subscriber or recipient email addresses, counted separately from and more tightly than everything else. Retry in 12 seconds; RateLimit-Policy on this response lists every budget that applies.",
    "docs_url": "https://usecommune.dev/errors/rate_limited",
    "request_id": "req_6f1c0e9b2d8a4f7c9e3b5a1d0c8f2e4b"
  }
}

Every budget at once:

curl https://api.usecommune.com/rate-limit \
  -H "Authorization: Bearer $COMMUNE_API_KEY" \
  -H "Commune-Version: 2026-08-26"