docs: fix drift in Admin Operations

[jack-arturo]

Docs-accuracy audit of /docs/reference/api/admin (never previously reviewed). 5 proven discrepancies fixed. This page is largely accurate — most of the drift is in error-path documentation.

Claim	Current state	Fix	Evidence
Error Responses table gives bodies as {"error": "Unauthorized"}, {"error": "Admin authorization required"}, {"error": "Admin token not configured"}	abort() raises an HTTPException that the global @app.errorhandler(Exception) converts to {"status": "error", "code": <n>, "message": <description>}. No error key is ever emitted.	Rewrote the three bodies to the real envelope and added the reachable 503 row	automem@8ff266e:app.py#L471, automem@8ff266e:automem/api/auth_helpers.py#L31
"All errors are logged with structured context: logger.exception("Failed to generate embeddings for batch", extra={"batch_ids": ids})"	That call does not exist. The only batch-failure log is logger.error(f"Failed to process batch starting at index {i}: {e}") — no logger.exception, no extra=, no ID list.	Replaced with the real log call	automem@8ff266e:automem/api/admin.py#L196
Error Handling table: Qdrant failure → "embedding writes are skipped for this batch and the operation continues"; missing content → "Logged, skipped"	generate_real_embeddings_batch() and qdrant_client.upsert() are inside one try, so a Qdrant write error is caught by the same handler that does failed += len(batch) and extends failed_ids — the batch is counted as failed, not silently skipped. Null/empty content is dropped by the if content: filter during enumeration with no log at all.	Rewrote the table, added the vector-count-mismatch row, and stated the shared-try behavior up front	automem@8ff266e:automem/api/admin.py#L155, automem@8ff266e:automem/api/admin.py#L124
/admin/reembed Response Schema documents 7 fields and one example	Missing failed_ids_truncated (set when >10 IDs fail). The no-work path returns an entirely different, smaller object — {status, message, processed, total} with no failed, batch_size, or metadata_preserved.	Added the truncation field and the short-circuit example	automem@8ff266e:automem/api/admin.py#L143, automem@8ff266e:automem/api/admin.py#L207
/admin/sync batch_size documented as "Default: 32" with no ceiling, and no response schema	min(int(payload.get("batch_size", 32)), 100) — same cap as /admin/reembed. The dry_run and already_synced response shapes were undocumented.	Documented the max and both response shapes	automem@8ff266e:automem/api/admin.py#L246, automem@8ff266e:automem/api/admin.py#L262

Also repinned the automem/api/admin.py source note from 0720da2 to 8ff266e (+13/−30 since the old pin). automem/api/enrichment.py and automem/api/backup.py are byte-identical between the two commits, so those two links — including the #L29-L100 anchor, which still spans create_backup_blueprint — were left alone.

Verified correct and untouched: the dual-token auth model and both header/query forms; the auth mermaid diagram; the entire GET /enrichment/status response schema and field table; the POST /enrichment/reprocess request/202 response and its processing flow; /admin/reembed batch_size default 32 / max 100, limit, and force semantics — including the subtle "force=true drops the WHERE m.content IS NOT NULL filter but the Python if content: check still excludes empty content"; the Phase 1 Cypher block; EMBEDDING_MODEL default text-embedding-3-small; and the /backup admin-only behavior and archive layout.

Verified against: automem@8ff266e62e65cb2e81719a765b05f64a2361a127

Questions

• The "Performance Considerations" table gives identical ~$0.06 cost across all four batch sizes with wall-clock times from ~30 seconds to ~5 minutes. The flat cost is right (token count is batch-size independent), but the timings are unsourced estimates — left alone.
• Security Model claims a compromised API token could "enumerate all memory IDs via reprocess endpoint". /enrichment/reprocess requires the admin token and echoes back only the IDs the caller submitted, so it does not enumerate anything. This reads like it was written against an older handler — worth a maintainer decision on whether to drop the bullet.

Unverified

• The Embedding Model Migration section says text-embedding-3-small is "1024-d, set by VECTOR_SIZE". EMBEDDING_MODEL's default is confirmed, but whether 1024 is the right worked example depends on deployment config, so the number was left as-is.

Follow-ups

• POST /enrichment/reprocess also accepts ids as a comma-separated string and as an ?ids= query parameter, and de-duplicates via a set (which is why the response IDs come back sorted). The request schema documents only the JSON array form.
• The Operational Patterns recall example uses ?query=*, which is not a documented wildcard for /recall. Not verified either way; not touched.

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying automem-website with    Cloudflare Pages

Latest commit:	3ee6969
Status:	✅  Deploy successful!
Preview URL:	https://24474325.automem-website.pages.dev
Branch Preview URL:	https://docs-audit-reference-api-adm-in8m.automem-website.pages.dev

View logs