From f0d4b265e53f261bab92d5a348631c8d849c4ce2 Mon Sep 17 00:00:00 2001 From: sohamd22 <85427822+sohamd22@users.noreply.github.com> Date: Tue, 6 Oct 2026 16:48:36 +0000 Subject: [PATCH] docs(api): document v5 delete count and search isInference (#1764) Docs for supermemoryai/mono#3415: delete and batch return `count`; ingest `status` is `queued`/`done` (batch adds `error`, files say `queued`); document `system.status` values; search `isInference` and `included.document.system`; `metadata` never null. --- apps/docs/snippets/api-v5-content-management.mdx | 4 +++- apps/docs/snippets/api-v5-document-ingestion.mdx | 8 ++++---- apps/docs/snippets/api-v5-rollout.mdx | 3 ++- apps/docs/snippets/api-v5-search.mdx | 3 ++- 4 files changed, 11 insertions(+), 7 deletions(-) diff --git a/apps/docs/snippets/api-v5-content-management.mdx b/apps/docs/snippets/api-v5-content-management.mdx index 0f197501..93c5140a 100644 --- a/apps/docs/snippets/api-v5-content-management.mdx +++ b/apps/docs/snippets/api-v5-content-management.mdx @@ -19,6 +19,8 @@ Pass `include` as a comma-separated list to return chunks, memories, or both. Ke {"system":{"status":"done","createdAt":"...","updatedAt":"..."}} ``` +`system.status` is one of `unknown`, `queued`, `extracting`, `chunking`, `embedding`, `indexing`, `done`, or `failed`. + ### List documents, chunks, or memories @@ -51,7 +53,7 @@ DELETE /ns/{namespace}/document ``` -The v5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both `deletedCount` and per-ID `errors`; HTTP success can include partial failures. +The v5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both `count` and per-ID `errors`; HTTP success can include partial failures. ### Forget memories diff --git a/apps/docs/snippets/api-v5-document-ingestion.mdx b/apps/docs/snippets/api-v5-document-ingestion.mdx index 79a9e731..87b0a983 100644 --- a/apps/docs/snippets/api-v5-document-ingestion.mdx +++ b/apps/docs/snippets/api-v5-document-ingestion.mdx @@ -25,7 +25,7 @@ POST /ns/user_1/document?dreaming=dynamic ``` -The response remains an acceptance result with `id` and `status`. Repeating the v5 request with `id: "conv_1"` adds or diffs the new content into that document; it does not silently replace the canonical source. +The response remains an acceptance result with `id` and `status`. Its `status` is the document's processing state after the request: `queued` when new work was queued, otherwise the document's current state (for example `done` for an unchanged duplicate, or `failed` for a metadata-only update to a failed document). Possible values: `unknown`, `queued`, `extracting`, `chunking`, `embedding`, `indexing`, `done`, `failed`. Repeating the v5 request with `id: "conv_1"` adds or diffs the new content into that document; it does not silently replace the canonical source. ### Batch ingestion @@ -41,7 +41,7 @@ The response remains an acceptance result with `id` and `status`. Repeating the Send the v5 body to `POST /ns/user_1/document/batch`. The array accepts 1–600 document objects. Namespace, `taskType`, and processing mode apply to the request; document content, ID, context, metadata, grouping, and date stay per item. -Batch results preserve input order. Inspect `success`, `failed`, and every item in `results`; a batch can contain successful and failed items together. +`results` lists accepted documents first, in request order, then failed ones; match each result by `id`, or by `url` for a failed item with no ID. Inspect `count` (accepted), `failed`, and every item in `results`; each item's `status` is a processing state as above, or `error` when that item failed, and a batch can contain successful and failed items together. ### File ingestion @@ -54,7 +54,7 @@ Replace `POST /v3/documents/file` with `POST /ns/{namespace}/document/file`. Con | `metadata`, `group` | JSON-encoded strings | | `fileType`, `mimeType` | Query parameters when inference is insufficient | -The API acknowledges the file after durable acceptance. Extraction, indexing, and memory formation continue asynchronously; poll the document rather than assuming the first response means processing is complete. +The API acknowledges the file after durable acceptance, with `status` set as for a JSON add. Extraction, indexing, and memory formation continue asynchronously; poll the document rather than assuming the first response means processing is complete. ### Processing choices @@ -66,5 +66,5 @@ The API acknowledges the file after durable acceptance. Extraction, indexing, an - Ingest text, a public URL, and a file, then wait for each document to finish processing. - Repeat a caller-defined ID and confirm append/diff behavior instead of replacement. -- Submit a mixed-success batch and verify result order and per-item errors. +- Submit a mixed-success batch and verify each result matches its document by ID, with per-item errors. - Confirm metadata and grouping remain filterable after processing. diff --git a/apps/docs/snippets/api-v5-rollout.mdx b/apps/docs/snippets/api-v5-rollout.mdx index bf468250..e2c6cfa9 100644 --- a/apps/docs/snippets/api-v5-rollout.mdx +++ b/apps/docs/snippets/api-v5-rollout.mdx @@ -9,7 +9,7 @@ Record each legacy request, v5 request, expected semantic result, and intentiona ### Compare writes - Repeated POST appends or diffs; PATCH replaces canonical content. -- Batch outcomes preserve input order and surface partial failures. +- Batch outcomes list accepted documents first, then failures, and surface partial failures; match by ID, not position. - Metadata-only updates leave source content unchanged. - Accepted writes are polled until processing reaches a terminal state. @@ -17,6 +17,7 @@ Record each legacy request, v5 request, expected semantic result, and intentiona - Document includes are absent when omitted and empty arrays when requested without results. - Unified list responses populate only the selected resource array. +- `metadata` is always an object, `{}` when empty; it is never `null`. - Search parity uses explicit v4-equivalent mode and threshold before testing v5 defaults. - Profiles always contain static, dynamic, and bucket sections. diff --git a/apps/docs/snippets/api-v5-search.mdx b/apps/docs/snippets/api-v5-search.mdx index 023189e7..4cf919f9 100644 --- a/apps/docs/snippets/api-v5-search.mdx +++ b/apps/docs/snippets/api-v5-search.mdx @@ -63,9 +63,10 @@ Legacy `include.chunks` has no v5 equivalent. Choose `chunks` or `hybrid` instea | --- | --- | | Result array | `results` | | Timing | `searchTime` | -| Source expansion | `result.included.document` | +| Source expansion | `result.included.document`, with timestamps under its `system` | | Related context | `result.included.related.{parents,children,siblings}` | | Lifecycle fields | `result.system` | +| Version and inference flags | `result.isLatest`, `result.isInference` | Each primary result contains either `memory`, `chunk`, or both only if the contract allows it. Branch on field presence rather than assuming one result shape.