{"title":"Rate Limits & Quotas","slug":"rate-limits","category":"api","summary":"Rate limit policies for Synapse API — Bearer header (recommended), ?key= deprecated (60/min), public endpoints.","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-11-03","word_count":401,"read_minutes":2,"llm_context":"Mind Key (Authorization: Bearer header) → 120 req/min from external IPs; unlimited for trusted internal networks\nMind Key (?key= query param) → 60 req/min per IP (deprecated; gated by AUTH_QUERY_KEY_MODE, default: deny)\nJWT (Authorization: Bearer header) → 120 req/min from external IPs; unlimited for trusted internal networks\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`) | 120 req/min (external IPs; unlimited for trusted internal networks) | Per-identity |\n| Mind Key (`?key=`) **(deprecated)** | 60 req/min | Per-IP |\n| JWT (`Authorization: Bearer`) | 120 req/min (external IPs; unlimited for trusted internal networks) | Per-user |\n| Public endpoints | **None** | Global |\n\n> [!TIP]\n> **Always use the `Authorization: Bearer` header** when possible. External\n> Bearer clients get 120 req/min per identity, and trusted internal networks\n> (Docker overlay, VPN, loopback) are unlimited. Use `?key=` only as a legacy\n> fallback 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 \"error\": \"rate_limited\",\n \"message\": \"Too many requests with query-param auth. Slow down or use Authorization header.\"\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 is deprecated and gated server-side by\n`AUTH_QUERY_KEY_MODE` (`deny` by default; `allow` re-enables query-param auth).\nIt 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# Legacy fallback (deprecated, 60/min per IP, gated by AUTH_QUERY_KEY_MODE).\n# Never share or bookmark such URLs — the key lands in logs and history.\nopen \"https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY\"\n\n# Preferred: switch to a tool that supports headers\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n```\n\n> [!WARNING]\n> A Mind Key inside a URL leaks into server access logs, browser history and\n> `Referer` headers. If that happens, rotate the key immediately.\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# Rate limit headers are attached to ?key= responses (legacy path):\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)120 req/min (external IPs; unlimited for trusted internal networks)Per-identity
Mind Key (?key=) (deprecated)60 req/minPer-IP
JWT (Authorization: Bearer)120 req/min (external IPs; unlimited for trusted internal networks)Per-user
Public endpointsNoneGlobal
\n
**Always use the `Authorization: Bearer` header** when possible. External\nBearer clients get 120 req/min per identity, and trusted internal networks\n(Docker overlay, VPN, loopback) are unlimited. Use `?key=` only as a legacy\nfallback 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  "error": "rate_limited",\n  "message": "Too many requests with query-param auth. Slow down or use Authorization header."\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 is deprecated and gated server-side by\nAUTH_QUERY_KEY_MODE (deny by default; allow re-enables query-param auth).\nIt 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
# Legacy fallback (deprecated, 60/min per IP, gated by AUTH_QUERY_KEY_MODE).\n# Never share or bookmark such URLs — the key lands in logs and history.\nopen "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"\n\n# Preferred: switch to a tool that supports headers\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
A Mind Key inside a URL leaks into server access logs, browser history and\n`Referer` headers. If that happens, rotate the key immediately.

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
# Rate limit headers are attached to ?key= responses (legacy path):\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"],"wordCount":401,"readMinutes":2,"llmContext":"Mind Key (Authorization: Bearer header) → 120 req/min from external IPs; unlimited for trusted internal networks\nMind Key (?key= query param) → 60 req/min per IP (deprecated; gated by AUTH_QUERY_KEY_MODE, default: deny)\nJWT (Authorization: Bearer header) → 120 req/min from external IPs; unlimited for trusted internal networks\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","requestedLang":"en","contentMarkdown":"\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`) | 120 req/min (external IPs; unlimited for trusted internal networks) | Per-identity |\n| Mind Key (`?key=`) **(deprecated)** | 60 req/min | Per-IP |\n| JWT (`Authorization: Bearer`) | 120 req/min (external IPs; unlimited for trusted internal networks) | Per-user |\n| Public endpoints | **None** | Global |\n\n> [!TIP]\n> **Always use the `Authorization: Bearer` header** when possible. External\n> Bearer clients get 120 req/min per identity, and trusted internal networks\n> (Docker overlay, VPN, loopback) are unlimited. Use `?key=` only as a legacy\n> fallback 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 \"error\": \"rate_limited\",\n \"message\": \"Too many requests with query-param auth. Slow down or use Authorization header.\"\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 is deprecated and gated server-side by\n`AUTH_QUERY_KEY_MODE` (`deny` by default; `allow` re-enables query-param auth).\nIt 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# Legacy fallback (deprecated, 60/min per IP, gated by AUTH_QUERY_KEY_MODE).\n# Never share or bookmark such URLs — the key lands in logs and history.\nopen \"https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY\"\n\n# Preferred: switch to a tool that supports headers\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n```\n\n> [!WARNING]\n> A Mind Key inside a URL leaks into server access logs, browser history and\n> `Referer` headers. If that happens, rotate the key immediately.\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# Rate limit headers are attached to ?key= responses (legacy path):\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","contentHtml":"

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)120 req/min (external IPs; unlimited for trusted internal networks)Per-identity
Mind Key (?key=) (deprecated)60 req/minPer-IP
JWT (Authorization: Bearer)120 req/min (external IPs; unlimited for trusted internal networks)Per-user
Public endpointsNoneGlobal
\n
**Always use the `Authorization: Bearer` header** when possible. External\nBearer clients get 120 req/min per identity, and trusted internal networks\n(Docker overlay, VPN, loopback) are unlimited. Use `?key=` only as a legacy\nfallback 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  "error": "rate_limited",\n  "message": "Too many requests with query-param auth. Slow down or use Authorization header."\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 is deprecated and gated server-side by\nAUTH_QUERY_KEY_MODE (deny by default; allow re-enables query-param auth).\nIt 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
# Legacy fallback (deprecated, 60/min per IP, gated by AUTH_QUERY_KEY_MODE).\n# Never share or bookmark such URLs — the key lands in logs and history.\nopen "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"\n\n# Preferred: switch to a tool that supports headers\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
A Mind Key inside a URL leaks into server access logs, browser history and\n`Referer` headers. If that happens, rotate the key immediately.

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
# Rate limit headers are attached to ?key= responses (legacy path):\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","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}