Per-endpoint rate limits are too restrictive for AI agent workflows and not configurable

[ian-vannman]

Problem

Outline's per-endpoint rate limits are hard-coded in the route definitions and cannot be adjusted by self-hosted operators. The global rate limiter has environment variables (RATE_LIMITER_REQUESTS, RATE_LIMITER_DURATION_WINDOW), but per-endpoint overrides ignore these and use fixed values from RateLimiterStrategy.

This is increasingly a problem as AI agents become a primary API consumer — a use case Outline is actively embracing with the built-in MCP server (v1.6.0). A single logical agent operation like "review a document and post feedback" can involve a burst of API calls that exceeds these limits. For example, comments.create is capped at 10 requests per minute. An agent posting 11 comments on a document review hits 429 on the 11th call. The MCP endpoint itself allows 1,000 requests/hour, but the underlying API routes it calls have their own stricter limits — so the MCP rate limit is misleading.

This was also raised in Discussion #6458 where a user building a static site generator hit 429s and noted the limits felt very low.

Current behavior

Per-route rate limits are defined in code with no way to override them:

// server/routes/api/comments/comments.ts
router.post("comments.create", rateLimiter(RateLimiterStrategy.TenPerMinute), ...);
 
// server/routes/api/documents/documents.ts  
router.post("documents.create", rateLimiter(RateLimiterStrategy.TwentyFivePerMinute), ...);
router.post("documents.update", rateLimiter(RateLimiterStrategy.OneHundredPerMinute), ...);

The strategies in RateLimiterStrategy are also fixed constants — there's no mechanism to adjust them.

Meanwhile, the global defaults are configurable:

RATE_LIMITER_ENABLED=true
RATE_LIMITER_REQUESTS=1000
RATE_LIMITER_DURATION_WINDOW=60

But these only apply to routes that don't have a per-endpoint override — which is most of the write endpoints.

Affected endpoints (agent-relevant subset)

Endpoint	Current limit	Agent impact
comments.create	10/min	Document review with multiple comments
documents.create	25/min	Batch content creation
documents.update	100/min	Iterative editing
attachments.create	10/min	Uploading images/files
collections.create	10/hour	Project setup
MCP endpoint	1000/hour	Appears generous but underlying routes are stricter

Proposal

Allow self-hosted operators to override per-endpoint rate limits via environment variables, without needing to fork the codebase. Two possible approaches:

Option A: Per-endpoint env var overrides

Follow the existing naming convention with endpoint-specific variables:

RATE_LIMITER_COMMENTS_CREATE_REQUESTS=100
RATE_LIMITER_COMMENTS_CREATE_DURATION=60

The rateLimiter() middleware would check for an env override before falling back to the hard-coded strategy.

Option B: Multiplier for API-key / MCP-authenticated requests

Recognize that agent traffic has different burst characteristics than interactive use. Apply a configurable multiplier to rate limits when the request is authenticated via API key or MCP token:

RATE_LIMITER_API_MULTIPLIER=10

This would give comments.create an effective limit of 100/min for API consumers while keeping the interactive limit at 10/min.

Context

We're a team running self-hosted Outline as a knowledge base with AI agents (Claude via MCP) as first-class participants — reading, editing, and commenting on documents. The agent workflow involves structured document reviews where Claude reads a document and posts multiple targeted comments, which is exactly the kind of burst that hits the comments.create limit. We expect this pattern to become more common as the MCP server adoption grows.

Workarounds (current)

• Set RATE_LIMITER_ENABLED=false — disables all rate limiting, which is too broad
• Fork and change RateLimiterStrategy constants — works but creates a maintenance burden
• Add delays between agent API calls — works but unnecessarily slows down workflows

None of these are great for production use.

[tommoor]

RATE_LIMITER_MULTIPLIER will be available in the next release. I'll also bump the limits on some of these common agent paths given the new usage patterns