{"title":"Rate Limits & Quotas","slug":"rate-limits","category":"api","summary":"Rate limit policies for Synapse API — Bearer header (unlimited), ?key= (60/min), public endpoints.","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":326,"read_minutes":2,"llm_context":"Mind Key (Authorization: Bearer header) → NO rate limit\nMind Key (?key= query param) → 60 req/min per IP\nJWT (Authorization: Bearer header) → NO rate limit\nPublic endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit\nRate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After\nRecommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.\n","lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Rate Limits & Quotas\n\nSynapse has a simple, predictable rate limit policy designed to prevent abuse\nwhile not getting in the way of legitimate usage.\n\n## Rate Limit Policy\n\n| Auth Method | Limit | Scope |\n|-------------|-------|-------|\n| Mind Key (`Authorization: Bearer`) | **None** | Per-mind |\n| Mind Key (`?key=`) | 60 req/min | Per-IP |\n| JWT (`Authorization: Bearer`) | **None** | Per-user |\n| Public endpoints | **None** | Global |\n\n> [!TIP]\n> **Always use the `Authorization: Bearer` header** when possible. It has no\n> rate limit. Use `?key=` only for tools that can't set custom headers.\n\n## Rate Limit Headers\n\nWhen you use `?key=` auth, responses include rate limit headers:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\nWhen you exceed the limit:\n\n```\nHTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n \"statusCode\": 429,\n \"error\": \"Too Many Requests\",\n \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\n## When You Hit a Rate Limit\n\nIf you get a 429:\n\n1. **Switch to Authorization header** (recommended):\n ```bash\n # Don't: ?key=YOUR_MIND_KEY (60/min limit)\n curl \".../memory/recall?key=YOUR_MIND_KEY\"\n \n # Do: Authorization header (unlimited)\n curl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n ```\n\n2. **Or wait `Retry-After` seconds** and retry.\n\n## Why the ?key= Limit Exists\n\nThe `?key=` query parameter is convenient for URL-only tools (browsers,\n`open` commands), but it has security and performance implications:\n\n- **Security:** Query parameters are logged in server access logs, browser\n history, and Referer headers. Limiting usage reduces exposure.\n- **Performance:** Query-parameter auth requires an IP-based rate limiter\n (Redis lookup per request), which adds latency. Header auth skips this.\n- **Abuse prevention:** A leaked `?key=` URL could be shared and hammered.\n The IP limit contains the blast radius.\n\n## Recommended Patterns\n\n### LLM agents\n\n```python\n# Always use header auth\nheaders = {\"Authorization\": f\"Bearer {MIND_KEY}\"}\nresponse = requests.get(f\"{URL}/memory/recall\", headers=headers)\n```\n\n### Browser-based tools\n\nIf your tool can only open URLs:\n\n```bash\n# OK for occasional use (under 60/min)\nopen \"https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY\"\n\n# For frequent use, switch to a tool that supports headers\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n```\n\n### MCP server\n\nMCP servers always use header auth via `SYNAPSE_MIND_KEY` env var — no rate\nlimit applies.\n\n### Bulk imports\n\nFor bulk operations (e.g. importing 1000 memories), always use header auth.\nBulk imports via `?key=` will hit the rate limit within 1 minute.\n\n## Quotas (Mind-Level)\n\nThere are currently no per-mind quotas on storage size or memory count. All\nlimits are at the auth/IP level, not the data level. This may change in the\nfuture for multi-tenant fairness.\n\n## Monitoring Your Usage\n\n```bash\n# Check your current rate limit status (with ?key= auth)\ncurl -i \"https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY\" | grep -i ratelimit\n\n# Output:\n# X-RateLimit-Limit: 60\n# X-RateLimit-Remaining: 58\n# X-RateLimit-Reset: 1782567840\n```\n\n## Next Steps\n\n- [Authentication](/docs/getting-started/authentication)\n- [Errors & Error Handling](/docs/api/errors)\n","content_html":"

Rate Limits & Quotas

\n

Synapse has a simple, predictable rate limit policy designed to prevent abuse\nwhile not getting in the way of legitimate usage.

\n

Rate Limit Policy

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Auth MethodLimitScope
Mind Key (Authorization: Bearer)NonePer-mind
Mind Key (?key=)60 req/minPer-IP
JWT (Authorization: Bearer)NonePer-user
Public endpointsNoneGlobal
\n
**Always use the `Authorization: Bearer` header** when possible. It has no\nrate limit. Use `?key=` only for tools that can't set custom headers.

Rate Limit Headers

\n

When you use ?key= auth, responses include rate limit headers:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840

When you exceed the limit:

\n
HTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n  "statusCode": 429,\n  "error": "Too Many Requests",\n  "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}

When You Hit a Rate Limit

\n

If you get a 429:

\n
    \n

  1. Switch to Authorization header (recommended):

    \n
    # Don't: ?key=YOUR_MIND_KEY (60/min limit)\ncurl ".../memory/recall?key=YOUR_MIND_KEY"\n\n# Do: Authorization header (unlimited)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
    2. \n

  2. Or wait Retry-After seconds and retry.

    \n
    3. \n
\n

Why the ?key= Limit Exists

\n

The ?key= query parameter is convenient for URL-only tools (browsers,\nopen commands), but it has security and performance implications:

\n\n

Recommended Patterns

\n

LLM agents

\n
# Always use header auth\nheaders = {"Authorization": f"Bearer {MIND_KEY}"}\nresponse = requests.get(f"{URL}/memory/recall", headers=headers)

Browser-based tools

\n

If your tool can only open URLs:

\n
# OK for occasional use (under 60/min)\nopen "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"\n\n# For frequent use, switch to a tool that supports headers\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

MCP server

\n

MCP servers always use header auth via SYNAPSE_MIND_KEY env var — no rate\nlimit applies.

\n

Bulk imports

\n

For bulk operations (e.g. importing 1000 memories), always use header auth.\nBulk imports via ?key= will hit the rate limit within 1 minute.

\n

Quotas (Mind-Level)

\n

There are currently no per-mind quotas on storage size or memory count. All\nlimits are at the auth/IP level, not the data level. This may change in the\nfuture for multi-tenant fairness.

\n

Monitoring Your Usage

\n
# Check your current rate limit status (with ?key= auth)\ncurl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit\n\n# Output:\n# X-RateLimit-Limit: 60\n# X-RateLimit-Remaining: 58\n# X-RateLimit-Reset: 1782567840

Next Steps

\n\n","urls":{"html":"/docs/api/rate-limits","text":"/docs/api/rate-limits?format=text","json":"/docs/api/rate-limits?format=json","llm":"/docs/api/rate-limits?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}