# Briefs System Limits

Operational limits for the sharebriefs.com API (REST, MCP, and OAuth surfaces). Agents should treat these as hard ceilings and back off on `429`/`413` responses rather than retrying immediately.

## Request & content size

| Limit | Value | On violation |
|---|---|---|
| HTTP request body (JSON), default | 1 MB | `413 PAYLOAD_TOO_LARGE` |
| HTTP request body (JSON), page & MCP routes | 6 MB | `413 PAYLOAD_TOO_LARGE` |
| Brief `content` (markdown) | 900 KB | `413 CONTENT_TOO_LARGE` (REST) / `invalid-argument` (callables) |
| Page `html` (single-file) | 5 MB | `413 CONTENT_TOO_LARGE` (REST) / `invalid-argument` (callables) |

The 900 KB brief-content cap sits deliberately under Firestore's ~1 MiB document limit, leaving headroom for the brief's name, ownership, and timestamp fields. The 1 MB default body limit leaves room for the JSON envelope around maximum-size brief content. Briefs approaching the cap should be split into multiple tightly-scoped briefs linked from an index brief.

Pages are larger (up to 5 MB of HTML) and are stored as files, not Firestore documents, so page-write and MCP routes accept a 6 MB request body to carry the HTML plus JSON envelope. See https://sharebriefs.com/brief/pages.

## Rate limits

All limits use fixed windows and return `429` with a `Retry-After` header (seconds) when exceeded. Honor `Retry-After` before retrying.

| Surface | Limit | Window | Keyed by |
|---|---|---|---|
| REST API & MCP (all authenticated routes) | 1,000 requests | 5 min | Bearer token (IP if anonymous) |
| `POST /oauth/token` | 30 requests | 10 min | IP |
| `GET /sso/authorize` | 10 requests | 10 min | IP |
| `POST /oauth/register` (Dynamic Client Registration) | 5 requests | 1 hour | IP |

Notes for agents:

- The global budget (~3.3 requests/sec sustained) is **per token**. Multiple agents sharing one personal access token (`sb_`) share one budget; agents holding their own OAuth tokens get independent budgets.
- Fixed-window counting means bursts can briefly reach ~2× the limit across a window boundary — do not design around that headroom.
- Cache brief content within a conversation instead of re-fetching; repeated `get_brief` calls for the same brief count against the budget.
- Legitimate clients register via DCR once and reuse credentials — never re-register per session.

## File uploads (Storage)

| Limit | Value |
|---|---|
| Max file size | 10 MB |
| Allowed types | `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `application/pdf`, `text/plain`, `text/markdown` |

Uploads outside these constraints are rejected by Storage security rules. (Page HTML is written server-side and is governed by the 5 MB page cap above, not this client-upload allowlist.)

## Pagination

List endpoints (`list_briefs`, `list_pages`, collaborators, org members, invitations) default to 30 items per page. Use `page`/`per_page` parameters rather than assuming a full result set in one response.