docs(api): publish per-plan limits and the codes refusals carry (PRO-2965)

api-reference/endpoint/add-memory.mdx

@@ -4,6 +4,10 @@
 openapi: "POST /memories/add_memory"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 Use this endpoint to store user-specific context that personalizes recall:
@@ -17,7 +21,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Controlled by `upsert` (default `true` – overwrites existing items with the same `source_id`)
 - **Async:** Yes – memories are queued for processing. Use [`POST /ingestion/verify_processing`](/api-reference/endpoint/verify-processing) to check status.
 
 <Warning>
@@ -39,7 +43,7 @@
         "infer": true,
         "user_name": "Alex",
         "metadata": {"team": "engineering"},
         "additional_metadata": {"source": "onboarding"}
       }
     ]
   }'
@@ -53,7 +57,7 @@
       infer: true,
       user_name: "Alex",
       metadata: { team: "engineering" },
       additional_metadata: { source: "onboarding" }
     }
   ]
 });
@@ -67,7 +71,7 @@
             "infer": True,
             "user_name": "Alex",
             "metadata": {"team": "engineering"},
             "additional_metadata": {"source": "onboarding"},
         }
     ],
 )

api-reference/endpoint/boolean-recall.mdx

@@ -4,20 +4,24 @@
 openapi: "POST /recall/boolean_recall"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 `/recall/boolean_recall` runs a BM25-style full-text search. It's the right tool when:
 
 - **Exact terms matter** – product codes, error codes, legal terms, regulatory IDs
 - **Auditability matters** – compliance searches need provable matches, not "semantically similar"
 - **Speed matters** – no embedding inference, no graph traversal, no reranking
 
 Use this instead of `full_recall` when the query is a literal lookup, not a semantic question.
 
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example
@@ -103,8 +107,8 @@
 | **Match type** | Exact term/phrase | Semantic similarity |
 | **Embeddings** | No | Yes |
 | **Graph traversal** | No | Optional |
 | **Reranking** | No | Yes (in `thinking` mode) |
 | **Best for** | Lookups, audits, compliance | Q&A, exploration, RAG |
 | **Latency** | Lowest | Higher (especially `thinking` mode) |
 
 ## Behavior notes

api-reference/endpoint/create-tenant.mdx

@@ -4,6 +4,10 @@
 openapi: "POST /tenants/create"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 Creating a new tenant is the first step before any ingestion or recall. A tenant is a fully isolated workspace – no tenant can read another tenant's data.
@@ -13,7 +17,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Re-sending with the same `tenant_id` returns `409 CONFLICT`
 - **Async:** Yes – returns `status: accepted`. Poll `/tenants/infra/status` before use.
 
 ## Example

api-reference/endpoint/delete-knowledge.mdx

@@ -4,6 +4,10 @@
 openapi: "POST /knowledge/delete_knowledge"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **Cleanup** – remove outdated documents
@@ -19,7 +23,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Re-sending a previously-deleted ID returns `deleted: false` for that item, but the request as a whole still returns `200`.
 - **Async:** No
 
 <Info>
@@ -78,7 +82,7 @@
       "error": "Source not found"
     }
   ],
   "deleted_count": 1
 }
 ```
 

api-reference/endpoint/delete-memory.mdx

@@ -4,6 +4,10 @@
 openapi: "DELETE /memories/delete_memory"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **Right-to-deletion** – remove a specific user's memory upon request
@@ -19,7 +23,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Idempotent - re-sending for an already-deleted memory returns `200` with `user_memory_deleted: false`
 - **Async:** No
 
 ## Example

api-reference/endpoint/delete-tenant.mdx

@@ -4,10 +4,14 @@
 openapi: "DELETE /tenants/delete"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **Offboarding** – a customer has churned and you need to remove their data
 - **Environment teardown** – delete test or staging tenants
 - **Compliance** – right-to-deletion requests under GDPR or similar
 
 <Warning>
@@ -26,7 +30,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Re-sending for a deleted tenant returns `404 TENANT_NOT_FOUND`
 - **Async:** Yes – returns `deletion_scheduled`. Cleanup runs in the background.
 
 ## Example

api-reference/endpoint/fetch-content.mdx

@@ -4,17 +4,21 @@
 openapi: "POST /fetch/content"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **Download original files** – PDFs, DOCX, etc. that you uploaded
 - **Generate temporary share links** – presigned URLs for client-side access
 - **Re-extract content** – rebuild downstream caches from the source of truth
 - **Preview** – display original content alongside recall results
 
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example
@@ -57,15 +61,15 @@
 | `source_id` | string | Yes | – | The source to fetch. |
 | `sub_tenant_id` | string | No | default | Sub-tenant scope. |
 | `mode` | enum | No | `content` | What to return. See [Modes](#modes). |
 | `expiry_seconds` | integer | No | `3600` | Presigned URL expiry (60–604800, i.e., 1 minute to 7 days). Only relevant when `mode` includes `url`. |
 
 ## Modes
 
 | Mode | Returns |
 |---|---|
 | `content` (default) | File content as text, or base64 for binary files |
 | `url` | Presigned URL only |
 | `both` | Content **and** presigned URL |
 
 Use `url` for client-side downloads where you don't want to proxy bytes through your backend.
 
@@ -100,7 +104,7 @@
 ## Behavior notes
 
 <Info>
 **Binary vs text.** For PDFs and other binaries, `content` is empty and the data is in `content_base64`. For markdown, plain text, or extracted text, `content` is populated directly.
 </Info>
 
 <Info>

api-reference/endpoint/full-recall.mdx

@@ -4,6 +4,10 @@
 openapi: "POST /recall/full_recall"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 `/recall/full_recall` is the primary endpoint for retrieving knowledge (documents, app sources). It runs a multi-stage pipeline that combines:
@@ -20,7 +24,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example
@@ -69,7 +73,7 @@
 | `query` | string | Yes | – | Search terms or natural-language question. |
 | `sub_tenant_id` | string | No | default | Sub-tenant scope. |
 | `max_results` | integer | No | – | Maximum number of chunks to return. |
 | `mode` | enum | No | `fast` | `fast` (single query, lower latency) or `thinking` (multi-query with reranking, higher quality). |
 | `alpha` | number\|string | No | `0.8` | Hybrid weight: `0.0` = keyword, `1.0` = semantic, `"auto"` lets the system pick. |
 | `recency_bias` | number | No | `0.0` | Preference for newer content (`0.0`–`1.0`). |
 | `graph_context` | boolean | No | `false` | If `true`, include entity relationships in the response. |
@@ -104,10 +108,10 @@
 
 | Mode | Latency | Quality | When to use |
 |---|---|---|---|
 | `fast` (default) | Lower | Standard | Real-time chat, autocomplete, simple lookups |
 | `thinking` | Higher | Higher | Complex queries, multi-step reasoning, anything customer-facing where quality matters more than ms |
 
 In `thinking` mode, HydraDB runs multiple sub-queries against the index and reranks results before returning.
 
 ## Response
 

api-reference/endpoint/graph-relations.mdx

@@ -4,10 +4,14 @@
 openapi: "GET /list/graph_relations_by_id"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **Debugging graph construction** – verify HydraDB extracted the relationships you expected
 - **Visualizations** – build entity graphs in admin UIs
 - **Audit** – confirm what entities and connections exist for a specific document
 
 This endpoint returns the raw triplets (subject → predicate → object) that HydraDB extracted from a single source.
@@ -15,7 +19,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example
@@ -78,7 +82,7 @@
           "context": "The Q4 pricing strategy was developed and is owned by the Product Team...",
           "confidence": 0.92,
           "relationship_id": "rel_xyz789",
           "chunk_id": "chunk_001"
         }
       ],
       "chunk_id": "chunk_001"

api-reference/endpoint/infra-status.mdx

@@ -4,15 +4,19 @@
 openapi: "GET /tenants/infra/status"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **After tenant creation** – poll until provisioning completes
 - **Diagnostics** – confirm the graph and vectorstore are healthy
 
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example
@@ -59,7 +63,7 @@
 | `org_id` | Organization identifier. |
 | `infra.scheduler_status` | `true` when the ingestion scheduler is ready. |
 | `infra.graph_status` | `true` when the graph database is ready. |
 | `infra.vectorstore_status` | Array of two booleans. `vectorstore_status[0]` is the **Memories** vector store; `vectorstore_status[1]` is the **Knowledge** vector store. **Both must be `true`** before ingesting. |
 
 <Info>
 Receiving a `"status": "accepted"` response from `POST /tenants/create` indicates that the creation process has successfully started -- it does **not** mean the tenant is fully provisioned. Poll this endpoint until all readiness flags are `true` before ingesting.

api-reference/endpoint/ingestion-overview.mdx

@@ -3,6 +3,10 @@
 description: "Quick reference for ingestion endpoints, their lifecycle, and when to use which."
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## Lifecycle
 
 ```mermaid
@@ -71,8 +75,8 @@
 
 | Content | Endpoint |
 |---|---|
 | PDFs, DOCX, CSVs, and other files HydraDB should parse | [`/ingestion/upload_knowledge`](/api-reference/endpoint/upload-knowledge) (`files`) |
 | Slack messages, Notion pages, Gmail threads, webpages with pre-extracted text | [`/ingestion/upload_knowledge`](/api-reference/endpoint/upload-knowledge) (`app_knowledge`) |
 | User preferences, conversation history, inline notes | [`/memories/add_memory`](/api-reference/endpoint/add-memory) |
 
 ## Typical call sequence
@@ -112,7 +116,7 @@
 
 **Multipart form data** – `/ingestion/upload_knowledge` always uses `multipart/form-data`, even when sending only `app_knowledge` (no actual files). Nested JSON fields (`file_metadata`, `app_knowledge`) must be sent as JSON-stringified form values.
 
 **Upsert** – By default, ingesting a source with an existing ID overwrites the previous version. Set `upsert: false` to fail instead.
 
 **Forceful relations** – At ingestion time, you can declare relationships between sources via the `relations` field. These are surfaced in `thinking`-mode recall as `additional_context`.
 

api-reference/endpoint/list-data.mdx

@@ -4,6 +4,10 @@
 openapi: "POST /list/data"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **Admin dashboards** – browse what's been ingested into a tenant
@@ -14,7 +18,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example
@@ -31,9 +35,9 @@
     "page_size": 25,
     "filters": {
       "tenant_metadata": { "category": "engineering" },
       "additional_metadata": { "author": "Alice Smith" }
     },
     "include_fields": ["title", "type", "url", "timestamp"]
   }'
 ```
 ```typescript TypeScript SDK
@@ -44,9 +48,9 @@
   page_size: 25,
   filters: {
     tenant_metadata: { category: "engineering" },
     additional_metadata: { author: "Alice Smith" }
   },
   include_fields: ["title", "type", "url", "timestamp"]
 });
 ```
 ```python Python SDK
@@ -57,7 +61,7 @@
     page_size=25,
     filters={
         "tenant_metadata": {"category": "engineering"},
         "additional_metadata": {"author": "Alice Smith"},
     },
     include_fields=["title", "type", "url", "timestamp"],
 )
@@ -97,8 +101,8 @@
 {
   "filters": {
     "tenant_metadata":     { "department": "Finance" },
     "additional_metadata": { "author": "Alice Smith" },
     "source_fields":       { "type": "slack", "title": "standup notes" }
   }
 }
 ```

api-reference/endpoint/list-overview.mdx

@@ -3,6 +3,10 @@ title: "List – Overview"
 description: "Browse stored knowledge and memories, and inspect their graph relationships."
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## Endpoint reference
 
 | Endpoint | Method | Purpose |

api-reference/endpoint/list-sub-tenant-ids.mdx

@@ -4,6 +4,10 @@
 openapi: "GET /tenants/sub_tenant_ids"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **Audit** – confirm which sub-tenants exist for compliance or usage reporting
@@ -15,14 +19,14 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example
 
 <CodeGroup>
 ```bash cURL
 curl 'https://api.hydradb.com/tenants/sub_tenant_ids?tenant_id=my_first_tenant' \
   -H "Authorization: Bearer <your_api_key>"
 ```
 ```typescript TypeScript SDK

api-reference/endpoint/list-tenant-ids.mdx

@@ -3,6 +3,10 @@
 description: "List all tenants registered for your organization."
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **Org-level admin dashboards** – show all tenants belonging to an organization
@@ -14,19 +18,19 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example
 
 <CodeGroup>
 ```bash cURL
 curl 'https://api.hydradb.com/tenants/tenant_ids' \
   -H "Authorization: Bearer <your_api_key>"
 ```
 ```typescript TypeScript SDK
 const response = await client.tenant.getTenantIds();
 const tenantIds = response.tenant_ids;
 ```
 ```python Python SDK
 response = client.tenant.get_tenant_ids()

api-reference/endpoint/memories-overview.mdx

@@ -3,6 +3,10 @@
 description: "Quick reference for all Memories endpoints, their lifecycle, and when to call each."
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## Lifecycle
 
 ```mermaid
@@ -73,7 +77,7 @@
 | | Memories | Knowledge |
 |---|---|---|
 | **Endpoint** | `POST /memories/add_memory` | `POST /ingestion/upload_knowledge` |
 | **Best for** | User preferences, conversation history, inline notes | Documents, PDFs, app-generated content |
 | **Content format** | Text, markdown, conversation pairs | Files, structured app sources |
 | **Retrieval** | `POST /recall/recall_preferences` | `POST /recall/full_recall` |
 | **Metadata fields** | `metadata`, `additional_metadata` (object) | `metadata`, `additional_metadata` (object) |

api-reference/endpoint/monitor-tenant.mdx

@@ -4,6 +4,10 @@
 openapi: "GET /tenants/monitor"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 - **Verify ingestion** – confirm data landed after upload (expect `row_count` to grow)
@@ -13,7 +17,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example
@@ -47,7 +51,7 @@
   "normal_collection": {
     "row_count": 1243
   },
   "memory_collection": {
     "row_count": 87
   },
   "message": "Successfully retrieved tenant collection statistics"

api-reference/endpoint/recall-overview.mdx

@@ -3,6 +3,10 @@
 description: "Quick reference for all Recall endpoints, their differences, and when to call each."
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## Which recall endpoint should I use?
 
 ```mermaid
@@ -55,7 +59,7 @@
 | **Match type** | Semantic + graph | Semantic + graph | Exact term/phrase |
 | **Returns** | Chunks | Chunks | Chunks |
 | **Latency** | Medium | Medium | Lowest |
 | **Best for** | Document Q&A, RAG context | Personalization | Compliance lookups, exact matches |
 
 ## Modes
 
@@ -63,8 +67,8 @@
 
 | Mode | Behavior | When to use |
 |---|---|---|
 | `fast` (default) | Single query pass, no reranking | Real-time chat, autocomplete, simple lookups |
 | `thinking` | Multi-query expansion, reranking, forceful-relation context | Complex queries, customer-facing answers, anything where quality matters |
 
 `boolean_recall` doesn't have modes – it's deterministic by design.
 
@@ -139,7 +143,7 @@
 
 **Graph context** – Entity relationships extracted from your data. Optional. Helps surface "how things connect" in addition to "what's similar."
 
 **`thinking` mode** – Expands the query into multiple sub-queries, retrieves for each, and reranks the combined results. Higher quality, higher latency.
 
 **Forceful relations** – Sources can be explicitly linked at ingestion. In `thinking` mode, recall surfaces context from these linked sources via the `additional_context` field.
 

api-reference/endpoint/recall-preferences.mdx

@@ -4,6 +4,10 @@
 openapi: "POST /recall/recall_preferences"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 `/recall/recall_preferences` retrieves user-specific context that was ingested via [`POST /memories/add_memory`](/api-reference/endpoint/add-memory). Use it when your agent needs to:
@@ -17,7 +21,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example

api-reference/endpoint/tenants-overview.mdx

@@ -3,6 +3,10 @@
 description: "Quick reference for all Tenants endpoints, their lifecycle, and when to call each."
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## Lifecycle
 
 ```mermaid
@@ -82,7 +86,7 @@
 GET /tenants/monitor        → check storage growth
 ```
 
 For teardown:
 
 ```
 DELETE /tenants/delete → schedule deletion (irreversible)

api-reference/endpoint/upload-knowledge.mdx

@@ -4,11 +4,15 @@
 openapi: "POST /ingestion/upload_knowledge"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 Use this endpoint to add knowledge that your agents will recall later:
 
 - **Files** – PDFs, DOCX, Markdown, CSVs, and other documents you want HydraDB to parse and chunk
 - **App knowledge** – structured content from connected apps (Slack messages, Notion pages, Gmail threads, tickets, CRM records, etc.) where you already have the text, IDs, metadata, and relations, sent as the `app_knowledge` multipart field (JSON string)
 
 For user-specific context (preferences, conversations), use [`POST /memories/add_memory`](/api-reference/endpoint/add-memory) instead.
@@ -17,7 +21,7 @@
 
 - **Auth:** Bearer token
 - **Content type:** `multipart/form-data` (always – even when sending only `app_knowledge`)
 - **Idempotency:** Controlled by `upsert` (default `true` – overwrites existing items with the same ID)
 - **Async:** Yes – returns **`200`** with a JSON body (`SourceUploadResponse` in OpenAPI) including one `source_id` per queued item. Use [`POST /ingestion/verify_processing`](/api-reference/endpoint/verify-processing) to check status.
 
 <Note>
@@ -42,7 +46,7 @@
   -F "tenant_id=my_first_tenant" \
   -F "files=@/path/to/contract.pdf" \
   -F "files=@/path/to/policy.pdf" \
   -F 'file_metadata=[
     { "file_id": "contract_q4", "metadata": { "category": "legal" } },
     { "file_id": "policy_2025", "metadata": { "category": "legal" } }
   ]'
@@ -63,8 +67,8 @@
 ```python Python SDK
 import json
 
 with open("/path/to/contract.pdf", "rb") as f1, \
      open("/path/to/policy.pdf", "rb") as f2:
     response = client.upload.knowledge(
         tenant_id="my_first_tenant",
         files=[
@@ -252,7 +256,7 @@
 | `additional_metadata` | object | Document-level metadata. Stored per-source. Filterable at recall by nesting under `"additional_metadata"` (canonical) or `"document_metadata"` (legacy alias) in `metadata_filters`. Post-retrieval (the engine over-fetches and filters). See [Full recall → Metadata filters](/api-reference/endpoint/full-recall#metadata-filters). |
 | `relations` | array | Typed app-source relations such as `reply_to`, `child_of`, `linked_to`, or `blocks`. |
 | `kind` | string | App object kind: `email`, `message`, `ticket`, `knowledge_base`, or `custom`. |
 | `provider` | string | Provider namespace such as `slack`, `gmail`, `jira`, `notion`, or `salesforce`. |
 | `external_id` | string | Stable provider ID for this source. Used for exact ID search and relation resolution. |
 | `fields` | object | Kind-specific structured fields. Include `kind` inside this object. |
 | `attachments` | array | Attachments connected to this app source. Include `content.text` or `content.markdown` when you already have extracted attachment text. |
@@ -264,7 +268,7 @@
 
 ### Content formats
 
 For typed app sources, primary searchable text belongs in `fields`, such as `fields.body` for messages/emails or `fields.description` for tickets. The top-level `content` object remains available for legacy or untyped app knowledge payloads.
 
 The `content` object supports multiple content types. Use the field that matches your source - only one needs to be set:
 

api-reference/endpoint/verify-processing.mdx

@@ -4,6 +4,10 @@
 openapi: "POST /ingestion/verify_processing"
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## When to use it
 
 Both `/ingestion/upload_knowledge` and `/memories/add_memory` are asynchronous. After ingesting, use this endpoint to check whether content is fully indexed and ready to be recalled.
@@ -17,7 +21,7 @@
 ## Endpoint
 
 - **Auth:** Bearer token
 - **Idempotency:** Read-only
 - **Async:** No
 
 ## Example

api-reference/error-responses.mdx

@@ -3,6 +3,10 @@
 description: "HTTP error codes, response shapes, and handling patterns across all HydraDB endpoints."
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 {/*
   PRO-1276 — DEFERRED, NOT FIXED.
 
@@ -51,7 +55,7 @@
 | `403` | Forbidden | Authenticated, but lacks permission |
 | `404` | Not Found | Resource does not exist |
 | `409` | Conflict | Resource already exists |
 | `422` | Unprocessable Entity | Well-formed request, semantic validation failed |
 | `429` | Too Many Requests | Rate limit exceeded |
 | `500` | Internal Server Error | Unexpected server-side failure |
 | `503` | Service Unavailable | Temporary service unavailability |
@@ -168,7 +172,7 @@
 
 ---
 
 ### 422 Unprocessable Entity
 
 Request is well-formed, but contains semantic errors.
 
@@ -211,9 +215,9 @@
 
 **How to handle:**
 
 Implement exponential backoff. See [Retry pattern](#retry-pattern) below.
 
-For current rate limit values, contact [founders@hydradb.com](mailto:founders@hydradb.com).
+The numbers are published in [Limits per plan](/api-reference/v2/error-responses#limits-per-plan).
 
 ---
 
@@ -231,7 +235,7 @@
 }
 ```
 
 **How to handle:** Retry with exponential backoff. If the error persists, contact support with the response payload.
 
 ---
 
@@ -249,7 +253,7 @@
 }
 ```
 
 **How to handle:** Retry with exponential backoff. Most 503s resolve within seconds.
 
 ---
 
@@ -298,7 +302,7 @@
 
 ## Retry pattern
 
 For transient errors (`429`, `500`, `503`), implement exponential backoff:
 
 <CodeGroup>
 ```typescript TypeScript (SDK)
@@ -306,7 +310,7 @@
 
 async function withRetry<T>(
   operation: () => Promise<T>,
   maxRetries = 3
 ): Promise<T> {
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
     try {
@@ -494,7 +498,7 @@
 1. **Use bulk endpoints** when possible (e.g., delete by array of IDs rather than one at a time)
 2. **Implement exponential backoff** for `429` responses
 3. **Cache recall results** when query patterns repeat
-4. Contact [founders@hydradb.com](mailto:founders@hydradb.com) for current limits
+4. The numbers are in [Limits per plan](/api-reference/v2/error-responses#limits-per-plan)
 
 ## Related sections
 

api-reference/index.mdx

@@ -3,10 +3,14 @@
 description: "Complete reference for every HydraDB endpoint, organized by group."
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 ## Quick links
 
 - **New to HydraDB?** Start with the [Quickstart](/get-started/quickstart)
 - **Prefer SDKs?** See the [Python and TypeScript SDKs](#sdks) below
 - **Authentication:** Every endpoint requires `Authorization: Bearer $HYDRA_DB_API_KEY`
 - **Base URL:** `https://api.hydradb.com`
 - **Errors:** See [Error Responses](/api-reference/error-responses)
@@ -47,9 +51,9 @@
     style G fill:#0f172a,stroke:#334155,stroke-width:2px,color:#f8fafc
 ```
 
 ## SDKs
 
 HydraDB publishes official SDKs for Python and TypeScript/Node. They wrap every endpoint in this reference with typed methods and IDE autocomplete.
 
 | Language | Package | Install |
 |---|---|---|
@@ -128,7 +132,7 @@
 
 | Endpoint | Method | Purpose |
 |---|---|---|
 | [`/fetch/content`](/api-reference/endpoint/fetch-content) | `POST` | Retrieve original file content or presigned URL |
 
 ### Knowledge Deletion
 
@@ -146,7 +150,7 @@
 
 **Pagination.** Listing endpoints (`/list/data`) return a `pagination` object with `page`, `page_size`, `total`, `total_pages`, `has_next`, and `has_previous`.
 
 **Parameter casing.** The REST API uses snake_case (`tenant_id`). The TypeScript SDK accepts the same snake_case keys; method names are camelCase (`fullRecall`, `addMemory`). The Python SDK uses snake_case throughout.
 
 **Status codes.** Successful responses return `200` (or `202` for async accepts). Errors follow standard HTTP semantics:
 
@@ -168,7 +172,7 @@
 
 ## Rate limits
 
-Rate limits apply per API key. For production deployments, build retry logic with exponential backoff against the `429` response. Contact [founders@hydradb.com](mailto:founders@hydradb.com) for current limit values.
+Limits are per workspace and per plan; the numbers are published in [Limits per plan](/api-reference/v2/error-responses#limits-per-plan). A `429` carries `Retry-After`; back off for that long before retrying.
 
 ## Next steps
 

api-reference/sdks.mdx

@@ -1,8 +1,12 @@
 ---
 title: "SDKs – Node and Python"
 description: "Official TypeScript/Node.js and Python SDKs for the HydraDB platform."
 ---
 
+import V1Retired from '/snippets/v1-retired.mdx';
+
+<V1Retired />
+
 {/*
   PRO-1276 — DEFERRED, NOT FIXED.
 
@@ -57,19 +61,19 @@
 
 ## Naming conventions
 
 The REST API uses **snake_case** for all request and response fields. The SDKs adapt this to native idioms:
 
 | | Method naming | Parameter field naming | Example |
 |---|---|---|---|
 | **Raw HTTP / cURL** | - | snake_case | `tenant_id`, `sub_tenant_id` |
 | **TypeScript SDK** | camelCase | snake_case | method: `fullRecall()`, params: `tenant_id`, `sub_tenant_id` |
 | **Python SDK** | snake_case | snake_case | method: `full_recall()`, params: `tenant_id`, `sub_tenant_id` |
 
 <Info>
 **TypeScript SDK uses snake_case for all parameter field names.** Only method names are camelCase (e.g., `client.recall.fullRecall({tenant_id: "...", max_results: 5})`). This applies to every request object passed to an SDK method.
 </Info>
 
 The TypeScript SDK transparently maps camelCase parameters to snake_case on the wire. You can rely on your IDE's autocomplete and type checking – if a field is optional in the API, it's optional in the SDK.
 
 ## SDK method structure
 
@@ -84,7 +88,7 @@
 | `/list/*`, `/fetch/*` | `client.fetch` | Browse and retrieve |
 | `/knowledge/*` | `client.data` | Bulk knowledge delete |
 
 Additional clients available: `client.key` for API key management, `client.ingestionPipeline` for pipeline operations, `client.graphHealth` for health checks, and `client.metrics` for metrics, `client.passthrough` for passthrough operations.
 
 ## Method reference
 
@@ -131,9 +135,9 @@
 | Method | Endpoint |
 |---|---|
 | `client.data.delete()` | `POST /knowledge/delete_knowledge` |
 In TypeScript, snake_case method names use camelCase: `client.tenant.getInfraStatus()`, `client.recall.fullRecall()`, etc.
 
 In Python, all method names use snake_case: `client.tenant.get_infra_status()`, `client.recall.full_recall()`, etc.
 
 ### Additional clients
 
@@ -175,7 +179,7 @@
   const status = await client.tenant.getInfraStatus({
     tenant_id: "my_first_tenant"
   });
   const { graph_status, vectorstore_status } = status.infra;
   if (graph_status && vectorstore_status.every(Boolean)) break;
   await new Promise(r => setTimeout(r, 2000));
 }
@@ -261,9 +265,9 @@
     {
       text: "User prefers detailed technical explanations and dark mode",
       infer: true,
       user_name: "Alex",
       metadata: { team: "engineering" },
       additional_metadata: { source: "onboarding" }
     }
   ]
 });
@@ -334,7 +338,7 @@
 });
 
 // Hybrid recall over user memories
 const prefs = await client.recall.recallPreferences({
   tenant_id: "my_first_tenant",
   sub_tenant_id: "user_alex",
   query: "What are this user's display preferences?",
@@ -394,7 +398,7 @@
   source_id: "doc_12345"
 });
 
 // Fetch original file content or get a presigned URL
 const file = await client.fetch.content({
   tenant_id: "my_first_tenant",
   source_id: "doc_12345",
@@ -428,7 +432,7 @@
 ## Type safety
 
 <Check>
 Both SDKs are fully typed:
 
 - **Autocomplete** for all method names and parameters
 - **Type checking** for request and response objects
@@ -445,7 +449,7 @@
 
 ## Error handling
 
 Both SDKs throw exceptions for non-2xx responses. Error objects expose the API's `detail` payload:
 
 <CodeGroup>
 ```typescript TypeScript SDK