# Rate Limits & Quotas
SUMMARY: Rate limit policies for Synapse API — Bearer header (unlimited), ?key= (60/min), public endpoints.

KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.

Rate Limits & Quotas
Synapse has a simple, predictable rate limit policy designed to prevent abuse
while not getting in the way of legitimate usage.
Rate Limit Policy
| Auth Method | Limit | Scope |
|-------------|-------|-------|
| Mind Key () | None | Per-mind |
| Mind Key () | 60 req/min | Per-IP |
| JWT () | None | Per-user |
| Public endpoints | None | Global |
> [!TIP]
> Always use the  header when possible. It has no
> rate limit. Use  only for tools that can't set custom headers.
Rate Limit Headers
When you use  auth, responses include rate limit headers:
[CODE BLOCK]
When you exceed the limit:
[CODE BLOCK]
When You Hit a Rate Limit
If you get a 429:
1. Switch to Authorization header (recommended):
   [CODE BLOCK]
2. Or wait  seconds and retry.
Why the ?key= Limit Exists
The  query parameter is convenient for URL-only tools (browsers,
 commands), but it has security and performance implications:
- Security: Query parameters are logged in server access logs, browser
  history, and Referer headers. Limiting usage reduces exposure.
- Performance: Query-parameter auth requires an IP-based rate limiter
  (Redis lookup per request), which adds latency. Header auth skips this.
- Abuse prevention: A leaked  URL could be shared and hammered.
  The IP limit contains the blast radius.
Recommended Patterns
LLM agents
[CODE BLOCK]
Browser-based tools
If your tool can only open URLs:
[CODE BLOCK]
MCP server
MCP servers always use header auth via  env var — no rate
limit applies.
Bulk imports
For bulk operations (e.g. importing 1000 memories), always use header auth.
Bulk imports via  will hit the rate limit within 1 minute.
Quotas (Mind-Level)
There are currently no per-mind quotas on storage size or memory count. All
limits are at the auth/IP level, not the data level. This may change in the
future for multi-tenant fairness.
Monitoring Your Usage
[CODE BLOCK]
Next Steps
- Authentication
- Errors & Error Handling