Legacy Notes Compatibility

Legacy Notes Compatibility

These routes remain available for backward compatibility in omni-edge-proxy/src/routes/pkms.ts:1367-1512. They are still used by the current desktop client for note CRUD in web-omni/src/features/desktop-client/lib/documentRepository.ts:317-387 and web-omni/src/features/desktop-client/lib/documentRepository.ts:422-472, but they do not currently go through the same unified create/update/delete helpers used by /v1/documents.

Authentication and headers

All legacy note routes require:

Authorization: Bearer <token>

They also participate in the same response transformation pipeline as the modern routes:

X-Proxy-Decrypt: true
X-Client-Key: <client-key>

Behavior is grounded to omni-edge-proxy/src/routes/pkms.ts:122-233 and omni-edge-proxy/src/routes/pkms.ts:1367-1512:

1. Without X-Proxy-Decrypt: true, encrypted fields are returned unchanged.
2. With X-Proxy-Decrypt: true, the proxy attempts to resolve a client key.
3. X-Client-Key takes precedence over escrowed key lookup.
4. If no client key is available, responses remain encrypted.

Route inventory

Route details

GET /v1/workspaces/:workspaceId/notes

Returns the raw array produced by listLegacyNotes(...), not a wrapped { notes: [...] } object.

Example response:

[
  {
    "id": "doc_123",
    "format": "omni.om.encrypted",
    "ciphertext": "iv:tag:ciphertext",
    "_meta": {
      "updatedAt": "ISO8601 timestamp",
      "notebookId": "nb_123"
    }
  }
]

Behavior:

• The route reads document.om or document.om.enc blobs directly and parses them if possible.
• If meta.om exists, it is merged into _meta on the returned object.
• Stored encrypted note payloads remain ciphertext by default.
• With X-Proxy-Decrypt: true and a client key, encrypted note entries can be transformed by the shared response transformer.

Grounded to omni-edge-proxy/src/routes/pkms.ts:795-836 and omni-edge-proxy/src/routes/pkms.ts:1367-1373.

POST /v1/workspaces/:workspaceId/notes

Creates a compatibility note by directly writing raw note artifacts.

Accepted request fields used by the current implementation include:

• documentPayload
• blocksPayload
• markdown
• indexableBlocks
• notebookId
• documentId optional

Important current behavior:

• documentPayload and blocksPayload are required.
• The handler writes document.om.enc and blocks.om.enc directly as JSON strings.
• It optionally writes markdown.md.
• It writes a plaintext meta.om sidecar built from indexableBlocks and notebookId.
• It does not call createUnifiedDocument(...) or upsertDocumentIndex(...).

Grounded to omni-edge-proxy/src/routes/pkms.ts:1378-1417.

GET /v1/workspaces/:workspaceId/notes/:noteId

Returns one compatibility note detail object:

{
  "document": {},
  "blocks": [],
  "markdown": "# My note"
}

Behavior:

• The route reads raw stored artifacts directly.
• document is parsed from document.om or document.om.enc.
• blocks is parsed from blocks.om or blocks.om.enc when present.
• markdown is returned as the stored string or "".
• There is no outer { note: ... } wrapper in the current implementation.

Grounded to omni-edge-proxy/src/routes/pkms.ts:1423-1440.

PATCH /v1/workspaces/:workspaceId/notes/:noteId

Partially updates a compatibility note by directly rewriting raw artifacts.

Accepted request fields used by the current implementation include:

• documentPayload
• blocksPayload
• markdown
• indexableBlocks
• notebookId

Current behavior:

• If documentPayload is present, the route rewrites document.om.enc.
• If blocksPayload is present, the route rewrites blocks.om.enc.
• If markdown is present, the route rewrites markdown.md.
• If indexableBlocks or notebookId is present, the route updates meta.om.
• It does not call patchUnifiedDocument(...) or upsertDocumentIndex(...).

Grounded to omni-edge-proxy/src/routes/pkms.ts:1446-1494.

DELETE /v1/workspaces/:workspaceId/notes/:noteId

Deletes note artifacts.

Success response:

{
  "success": true
}

Current behavior:

• The route deletes stored document, blocks, markdown, and meta artifacts.
• It does not call removeDocumentIndex(...), so derived block-index cleanup is not part of this legacy delete handler.

Grounded to omni-edge-proxy/src/routes/pkms.ts:1500-1508.

Notebook compatibility routes

Notebook compatibility behavior is split across three routes:

• GET /v1/workspaces/:workspaceId/notebooks returns { ciphertext: string | null } from the legacy encrypted notebook blob.
• POST /v1/workspaces/:workspaceId/notebooks requires { ciphertext: string } and returns { success: true }.
• GET /v1/workspaces/:workspaceId/notebooks/:notebookId returns { notebook } when a structured notebook record exists.

Grounded to omni-edge-proxy/src/routes/pkms.ts:1191-1225.

NOTE: These routes are compatibility-only and new clients should prefer the unified /v1/documents and /v1/workspaces/:workspaceId/documents endpoints documented in core-console/content/docs/api-reference/endpoints.mdx:1-725.