docs: align billing, analytics and legacy reference pages with the API (#1814)

Fixes billing, analytics, security and legacy reference pages. - **Operations.** `rewriteQuery`, rerank/aggregate and forget-matching each bill one operation. - **Profile metering.** v5 profile is documented as 1 search query per call. - **Analytics:** - The errors response shape is fixed. - Usage `byKey` includes `tokensUsed`, and the log `output` example has the right shape. - The 90-day range limit doesn't exist. - **Smaller fixes:** - Only 2 billing endpoints need an admin. - The `credits` response shape. - The 2FA gate is in the feature table. - The security page points to the one-call namespace delete for data erasure. - Container-tag merge takes several sources. - A stale "after API deploy" note is removed. Checked against the current API and the published SDKs (TS 5.0.1, Python 5.0.0). Legacy v3/v4 docs are unchanged apart from factual fixes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-10-27 06:15:15 +00:00 · 2026-10-15 18:52:42 +00:00 · 2026-10-15 18:52:42 +00:00 · 23983bffae
commit 23983bffae
parent acbb05f837
5 changed files with 79 additions and 74 deletions
--- a/apps/docs/api-reference/container-tags.mdx
+++ b/apps/docs/api-reference/container-tags.mdx
@ -16,7 +16,7 @@ v5 calls these **namespaces**. Same values. New integrations should use [v5 name
 | `GET /v3/container-tags/{containerTag}` | Read tag settings |
 | `PATCH /v3/container-tags/{containerTag}` | Update tag settings |
 | `DELETE /v3/container-tags/{containerTag}` | Delete a container and its data |
-| `POST /v3/container-tags/merge` | Merge one tag into another |
+| `POST /v3/container-tags/merge` | Merge exactly two listed tags into either listed tag or a new target tag |
 | `GET /v3/container-tags/merge/{mergeId}` | Poll merge status |

 **Guide:** [Container tags](/concepts/container-tags) · [Filtering](/concepts/filtering)
--- a/apps/docs/api-reference/overview.mdx
+++ b/apps/docs/api-reference/overview.mdx
@ -63,7 +63,7 @@ Official clients wrap this API:

 See [Supermemory SDK](/integrations/supermemory-sdk).

-Playground snippets come from the OpenAPI spec: official **TypeScript / Python SDK** samples via `x-codeSamples`, plus cURL. (After API deploy — until then you may still see generic HTTP snippets.)
+The API's OpenAPI generator supplies official **TypeScript / Python SDK** samples via `x-codeSamples`, plus cURL. Playground snippets use the deployed spec, so their availability depends on the API version serving it.

 SDK generation is migrating off Stainless SaaS to **stlc** soon; documented OpenAPI samples will then be produced by the SDK build instead of a hand-maintained map.

--- a/apps/docs/overview/analytics.mdx
+++ b/apps/docs/overview/analytics.mdx
@ -12,7 +12,7 @@ The Analytics API provides comprehensive insights into your Supermemory usage:

 - **Usage Statistics**: Track API calls by type, hourly trends, and per-API key breakdown
 - **Error Monitoring**: Identify top error types and patterns
- **Detailed Logs**: Access complete request/response logs for debugging
+- **Detailed Logs**: Inspect stored request logs and compacted response data for debugging
 - **Performance Metrics**: Monitor average response times and processing duration

 <Note>
@ -33,7 +33,7 @@ Get comprehensive usage statistics including hourly breakdowns and per-key metri
 |-----------|------|-------------|
 | `from` | string (ISO 8601) | Start date/time for the period |
 | `to` | string (ISO 8601) | End date/time for the period |
-| `period` | string | Alternative to `from`: `1h`, `24h`, `7d`, `30d` |
+| `period` | string | Alternative to `from`: `24h`, `7d`, `30d`, `all`. Use `from` and `to` for other windows |
 | `page` | integer | Page number for pagination (default: 1) |
 | `limit` | integer | Items per page (default: 20, max: 100) |

@ -105,7 +105,8 @@ curl -X GET "https://api.supermemory.ai/v3/analytics/usage?from=2024-01-01T00:00
      "keyName": "Production API",
      "count": 2341,
      "avgDuration": 98.7,
-      "lastUsed": "2024-01-15T14:35:00Z"
+      "lastUsed": "2024-01-15T14:35:00Z",
+      "tokensUsed": 182340
    }
  ],
  "totalMemories": 45678,
@ -118,6 +119,8 @@ curl -X GET "https://api.supermemory.ai/v3/analytics/usage?from=2024-01-01T00:00
 }
 ```

+`tokensUsed` sums recorded `finalTokens` for the listed keys, including chat usage. It is not the billable ingestion-token meter, and ordinary memory request logs do not necessarily populate it.
+
 ## Error monitoring

 Track and analyze errors to identify issues and improve reliability.
@ -148,7 +151,7 @@ const data = await errors.json();
 ```python Python
 # Monitor errors and alert on spikes
 response = requests.get(
-    'https://api.supermemory.ai/v3/analytics/errors?period=1h',
+    'https://api.supermemory.ai/v3/analytics/errors?period=24h',
    headers={'Authorization': f'Bearer {SUPERMEMORY_API_KEY}'}
 )

@ -167,41 +170,53 @@ curl -X GET "https://api.supermemory.ai/v3/analytics/errors?period=7d" \

 ```json
 {
-  "totalErrors": 234,
-  "errorRate": 0.023,
-  "topErrors": [
+  "summary": [
    {
-      "type": "ValidationError",
+      "type": "search_v4",
+      "totalRequests": 3421,
+      "successRate": 97.4,
+      "errorRate": 2.6,
+      "lastRequest": "2024-01-15T14:35:00Z"
+    }
+  ],
+  "errors": [
+    {
+      "type": "search_v4",
+      "statusCode": 400,
      "count": 89,
-      "statusCodes": [400],
-      "lastOccurred": "2024-01-15T14:30:00Z"
-    },
-    {
-      "type": "RateLimitError",
-      "count": 45,
-      "statusCodes": [429],
-      "lastOccurred": "2024-01-15T13:15:00Z"
+      "percentage": 100
    }
  ],
-  "timeline": [
+  "hourly": [
    {
-      "time": "2024-01-15T14:00:00Z",
-      "count": 12,
-      "types": ["ValidationError", "NotFoundError"]
+      "hour": "2024-01-15T14:00:00Z",
+      "count": 156,
+      "errorCount": 4,
+      "errorRate": 2.56
    }
  ],
-  "byStatusCode": {
-    "400": 89,
-    "404": 34,
-    "429": 45,
-    "500": 66
+  "byKey": [
+    {
+      "keyId": "key_abc123",
+      "keyName": "Production API",
+      "count": 2341,
+      "errorCount": 61,
+      "errorRate": 2.61,
+      "lastUsed": "2024-01-15T14:35:00Z"
+    }
+  ],
+  "pagination": {
+    "currentPage": 1,
+    "limit": 20,
+    "totalItems": 3421,
+    "totalPages": 172
  }
 }
 ```

 ## Detailed logs

-Access complete request/response logs for debugging and auditing.
+Inspect stored request logs for debugging. Response data is compacted: strings, arrays, fields, and nesting can be truncated. The ordinary request tracker skips HTTP `402`, `404`, and `500` responses, so this is not a complete audit trail.

 ### Endpoint

@ -209,18 +224,14 @@ Access complete request/response logs for debugging and auditing.

 ### Parameters

-Same as usage endpoint, plus optional filters:
- `type`: Filter by request type (add, search, update, delete)
- `statusCode`: Filter by HTTP status code
- `keyId`: Filter by specific API key
+Use `from`, `to`, `period`, `page`, and `limit` as above. The current `/logs` handler filters by organization and time only; it does not apply `type`, `statusCode`, or `keyId` filters.

 ### Example request

 <CodeGroup>

 ```typescript TypeScript
-// Get recent failed requests
-const logs = await fetch('https://api.supermemory.ai/v3/analytics/logs?period=1h&statusCode=500', {
+const logs = await fetch('https://api.supermemory.ai/v3/analytics/logs?period=24h', {
  headers: {
    'Authorization': `Bearer ${SUPERMEMORY_API_KEY}`
  }
@ -230,11 +241,9 @@ const data = await logs.json();
 ```

 ```python Python
-# Debug specific API key usage
 response = requests.get(
    'https://api.supermemory.ai/v3/analytics/logs',
    params={
-        'keyId': 'key_abc123',
        'period': '24h'
    },
    headers={'Authorization': f'Bearer {SUPERMEMORY_API_KEY}'}
@ -246,7 +255,7 @@ logs = response.json()['logs']

 ```bash cURL
 # Get all logs for debugging
-curl -X GET "https://api.supermemory.ai/v3/analytics/logs?period=1h&limit=50" \
+curl -X GET "https://api.supermemory.ai/v3/analytics/logs?period=24h&limit=50" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
 ```

@ -263,13 +272,10 @@ curl -X GET "https://api.supermemory.ai/v3/analytics/logs?period=1h&limit=50" \
      "type": "search",
      "statusCode": 200,
      "duration": 89,
-      "input": {
-        "q": "user query",
-        "limit": 10
-      },
+      "input": "{\"q\":\"user query\",\"limit\":10}",
      "output": {
-        "results": 10,
-        "processingTime": 85
+        "type": "search",
+        "response": { "results": [], "timing": 85, "total": 0 }
      }
    }
  ],
@ -282,13 +288,10 @@ curl -X GET "https://api.supermemory.ai/v3/analytics/logs?period=1h&limit=50" \
 }
 ```

-## Rate limits
+## Limits and retention

-Analytics endpoints have the following rate limits:
- 100 requests per minute per organization
- Maximum time range: 90 days
- Maximum page size: 100 items
+The maximum page size is 100 items. Normal API request rate limits also apply; this page does not establish a separate analytics-specific allowance.

 <Warning>
-Analytics data is retained for 90 days. For longer retention, export and store the data in your own systems.
+An accepted date range does not guarantee that historical logs are still retained. Confirm the applicable service retention policy with Supermemory, and export data to your own systems when you need longer retention.
 </Warning>
--- a/apps/docs/overview/billing.mdx
+++ b/apps/docs/overview/billing.mdx
@ -29,7 +29,7 @@ USD CREDIT BALANCE  ──draw──►  METERS
 1. You hold a **USD credit balance** (`usd_credits`).
 2. Product activity increments **meters** (tokens, queries, operations).
 3. Each meter unit multiplies by a **USD-per-unit** rate and debits the balance.
-4. **Re-ingesting the same document under the same `id` only bills the net-new token delta** — already-seen content is effectively **fully discounted**.
+4. **Re-ingesting a document under the same `id` can reuse unchanged content** — token charges follow added or changed text, not simply growth in the document's total length.

 ---

@ -41,8 +41,8 @@ USD CREDIT BALANCE  ──draw──►  METERS
 | `sm_tokens_rich` | Memory tokens (rich) | Billable **new** tokens on Memory-path ingest for multimodal / extraction-heavy types (PDF, media, etc.) | tokens |
 | `sm_superrag_text` | SuperRAG tokens (text) | Billable **new** tokens when the task type is SuperRAG (text) | tokens |
 | `sm_superrag_rich` | SuperRAG tokens (rich) | Billable **new** tokens when the task type is SuperRAG (rich) | tokens |
-| `sm_search_queries` | Search queries | Each search / profile call that runs retrieval (v3 search, v4 search, v4 profile with search) | queries |
-| `sm_operations` | Operations | Counted platform operations not fully attributed to token meters (e.g. certain ingest modes such as **instant dreaming**, and other non-token platform actions) | operations |
+| `sm_search_queries` | Search queries | Gated v5 namespace search, v3/v4 search, and v4 profile calls that include a non-blank `q` query | queries |
+| `sm_operations` | Operations | Counted platform operations not attributed to token or query meters: **instant dreaming**, and search add-ons such as query rewriting, reranking and aggregation | operations |

 ### List rates (USD)

@ -73,7 +73,8 @@ Text-like document types bill on the **text** meters; everything else bills as *
 **`sm_operations`** is the meter for discrete platform work that is not “how many tokens did we embed.” Examples include:

 - `dreaming: "instant"` extracts a document's memories immediately instead of waiting for the next dynamic batch. It costs **one extra operation per document** on top of normal token metering. See [processing modes](/ingestion/add-memories#processing-modes).
- Other non-token platform actions the product attributes to the operations meter (console: “counted platform operations not attributed to token or search meters”).
+- Search add-ons: query rewriting (`rewriteQuery`), reranking and aggregation (v5 `rerank: "order"` / `"aggregate"`, v3/v4 `rerank`, v4 `aggregate`) each add **one operation** when they run successfully. Failed or skipped add-ons do not necessarily charge an operation.
+- Query-based `POST /v4/memories/forget-matching` adds **one operation per search round**, up to five, including `dryRun` previews. Applying an explicit `ids` list bypasses that query-operation charge.

 Search is primarily metered as **`sm_search_queries`** (one unit per gated search/profile request). Prefer thinking of operations as **extra platform work**, not as a synonym for “API call.”

@ -81,14 +82,18 @@ Search is primarily metered as **`sm_search_queries`** (one unit per gated searc

 | Call | Typical meter |
 |---|---|
-| `POST /ns/{namespace}/search`, `supermemory.search()` | `sm_search_queries` (+1) |
-| `POST /ns/{namespace}/profile`, `supermemory.profile()` when it runs retrieval | `sm_search_queries` (+1) |
+| `POST /ns/{namespace}/search`, `supermemory.search()` | `sm_search_queries` (+1), plus `sm_operations` for any add-ons that run |
+| `POST /ns/{namespace}/profile`, `supermemory.profile()` | No search-query meter in the current API implementation |
+| Legacy `POST /v3/search`, `POST /v4/search` | `sm_search_queries` (+1), plus `sm_operations` for any add-ons that run |
+| Legacy `POST /v4/profile` with a non-empty `q` | `sm_search_queries` (+1) |

-If the org is out of balance, search/profile can return **402** (payment required) depending on gate configuration.
+Blocking metered cloud calls can return **402** (payment required) when the applicable balance or quota is exhausted. Billing exclusions, unlimited contracts, disabled billing, and gate configuration can differ. The current v5 profile route does not install a search-query billing gate; this is not a guarantee of future pricing.

 ---

-## Full discount on already-seen tokens (diff billing)
+<span id="full-discount-on-already-seen-tokens-diff-billing" />
+
+## Reusing unchanged content (diff billing)

 This is the most important cost control in production agents.

@ -96,17 +101,13 @@ This is the most important cost control in production agents.

 When you re-add content under the **same `id`** (same org / document identity), the pipeline:

-1. Loads the **previous extracted content** for that document
-2. Computes **full** token count of the merged/updated document
-3. Bills only:
+1. Loads the document's active chunks and plans the updated content.
+2. Reuses unchanged chunks where possible.
+3. Meters newly appended text on an append path, or added replacement chunks on a replace path.

-```text
-billableTokens = max(0, fullTokenCount - previousTokenCount)
-```
+This is not a subtraction of the old total token count from the new one. A same-length replacement can still incur charges if its content changed; an identical replacement can reuse its chunks without new token charges. Chunk boundaries and overlap can also affect the billable delta.

-So **tokens Supermemory has already processed are not billed again**. Unchanged content costs nothing on the token meters; only the net-new delta, and any new extraction on it, draws credits.
-
-This is why long-lived agent loops stay cheap: re-sync the same conversation `id`, re-upload the same policy doc, or connector re-sync with stable IDs — you pay for **new** material, not the whole history every time.
+Stable IDs let long-lived conversations and repeated document syncs reuse unchanged work rather than billing the whole history every time. Operation surcharges can still apply.

 ### Requirements

@ -114,7 +115,7 @@ This is why long-lived agent loops stay cheap: re-sync the same conversation `id
 |---|---|
 | **Stable `id`** | Identity for “this is the same document.” Max length 255. |
 | **Same org / key** | Documents are org-scoped. |
-| **Update path, not full replace** | Full replace clears previous content for billing purposes (`isFullReplace` treats previous tokens as 0). Prefer append/update with the same `id` for chat. |
+| **Choose append or replace deliberately** | Append meters the newly appended text; replace compares chunks and can reuse unchanged ones. Changed replacement chunks can bill even without net document growth. |

 ### Practical patterns

@ -127,12 +128,12 @@ await supermemory.add(userId, {
 });
 ```

-Connectors already use stable IDs (e.g. Drive file id, Gmail thread id, `s3://bucket/key`) so re-syncs diff-bill automatically.
+Connectors use stable IDs (e.g. Drive file id, Gmail thread id, `s3://bucket/key`), so re-syncs can reuse unchanged content. Changed replacement chunks can still incur token charges.

 ### What is not free

 - **First** ingest of content still bills full token count
- **Search / profile** still bill query meters every call
+- **Gated searches** still bill the query meter every call; legacy v4 profile does so only with a non-blank `q`. The current v5 profile implementation does not charge this meter.
 - **Instant dreaming** still bills the **operation** surcharge when used
 - **Brand-new `id`** = brand-new document = full tokens

@ -191,6 +192,7 @@ Usage meters are shared; **feature gates** differ by tier.
 | Gmail connector | — | — | Yes | Yes | Yes |
 | GitHub, S3, Web Crawler connectors | — | — | — | Yes | Yes |
 | User Insights | — | — | — | Yes | Yes |
+| Two-factor authentication | — | — | — | Yes | Yes |
 | Org seat limit (members) | 1 | 3 | 3 | Unlimited | Unlimited |
 | Auto top-up in the console | — | Yes | Yes | Yes | Contract |
 | Auto top-up purchase limits | — | Yes | Yes | Yes | Contract |
@ -211,7 +213,7 @@ Overrides can be applied per org in metadata (`featureOverrides`) for enterprise

 ## Programmatic access

-All of the following require an **org-admin capable** credential. **Scoped API keys cannot read billing** (403).
+**Scoped API keys cannot read billing** (403). `GET /v3/auth/billing` and `POST /v3/auth/billing/auto-topups` also require an org **admin or owner**.

 Base: `https://api.supermemory.ai`  
 Auth: `Authorization: Bearer YOUR_API_KEY`
@ -234,7 +236,7 @@ Typical fields:
    "tokens": { "used": 120000, "limit": 0 },
    "queries": { "used": 4200, "limit": 0 }
  },
-  "credits": {},
+  "credits": { "balance": 14.62, "label": "USD" },
  "resetDate": "2026-08-01T00:00:00.000Z",
  "orgName": "Acme",
  "billingEmail": "billing@acme.com"
--- a/apps/docs/overview/security.mdx
+++ b/apps/docs/overview/security.mdx
@ -41,7 +41,7 @@ Supermemory is infrastructure for *your* agents. Your customer content is never
 ### Data residency and deployment options

 - **Managed cloud** — default multi-tenant SaaS.
- **Self-hosted binary** — full engine on your machine or VPC; embeddings and storage stay where you run it. See [Self-hosting](/self-hosting/overview).
+- **Self-hosted binary** — the engine, storage, and default local embeddings run on your machine or VPC. If you configure remote LLM or embedding providers, their processing inputs are sent to those providers. See [Self-hosting](/self-hosting/overview).
 - **Enterprise / dedicated** — for stricter residency, air-gap, or custom deployment requirements. See [Local vs Enterprise](/self-hosting/local-vs-enterprise).

 ## Privacy operations you should design for
@ -51,10 +51,10 @@ Supermemory is infrastructure for *your* agents. Your customer content is never
 The practical GDPR-style path for app builders:

 1. Scope each end-user (or tenant) to a **namespace**.
-2. When the user requests deletion, delete that namespace’s content via the API / console workflows for documents and memories under that namespace.
+2. When the user requests deletion, use `DELETE /ns/{namespace}` with an org admin or owner credential that has write access. It deletes the namespace, its namespace-owned memory records, and documents exclusive to it; documents shared with other namespaces are retained. The default `sm_project_default` namespace cannot be deleted.
 3. Revoke any **scoped keys** issued for that user.

-Designing isolation up front makes erasure a single boundary operation instead of a forensic search.
+Designing isolation up front still makes identifying the user's content easier.

 ### Connectors and third-party sources