API Endpoints

This page documents the routes exposed by omni-edge-proxy/src/index.ts:33-348 and the modern PKMS routes registered in omni-edge-proxy/src/routes/pkms.ts:1150-1679.

Use Legacy Notes Compatibility for the workspace-scoped compatibility routes that the current desktop client still uses for note CRUD.

Authentication and headers

Most PKMS routes require:

Authorization: Bearer <token>

The proxy accepts several token forms through the shared auth pipeline described in omni-edge-proxy/src/index.ts:75-97 and omni-edge-proxy/src/routes/pkms.ts:319-336.

CORS-allowed headers

The edge proxy explicitly allows these request headers:

Content-Type
Authorization
X-Appwrite-Project
X-Appwrite-Key
X-Proxy-Decrypt
X-Client-Key

See omni-edge-proxy/src/index.ts:35-41.

Response decryption controls

PKMS responses are only transformed when the caller opts in with:

X-Proxy-Decrypt: true

You may also provide a client key directly:

X-Client-Key: <client-key>

Behavior from omni-edge-proxy/src/routes/pkms.ts:122-153 and omni-edge-proxy/src/routes/pkms.ts:222-233:

1. If X-Proxy-Decrypt is not true, the proxy returns the stored response unchanged.
2. If X-Proxy-Decrypt: true is present, the proxy resolves a client key.
3. Client key precedence is:
   1. X-Client-Key
   2. escrowed key resolved through getClientKey in omni-edge-proxy/src/index.ts:75-97
4. If no client key is available, the response is still returned unchanged.

The response transformer can decrypt:

• envelope objects with format: "omni.om.encrypted"
• encrypted blob strings shaped like iv:tag:ciphertext
• nested arrays and objects containing those values

See omni-edge-proxy/src/routes/pkms.ts:137-220.

Route inventory

Inventory grounded to omni-edge-proxy/src/index.ts:43-348, omni-edge-proxy/src/routes/pkms.ts:1150-1679, and omni-edge-proxy/src/routes/ai.ts.

Shared schemas

Error response

Most PKMS route failures use:

{
  "error": {
    "code": "error | unauthorized | not_found",
    "message": "string"
  }
}

See omni-edge-proxy/src/routes/pkms.ts:236-238.

Encrypted envelope

{
  "format": "omni.om.encrypted",
  "ciphertext": "iv_hex:auth_tag_hex:ciphertext_hex"
}

See omni-edge-proxy/src/routes/pkms.ts:137-139.

Unified document record

{
  "id": "doc_123",
  "project_id": "project_123",
  "workspace_id": "ws_123",
  "document_type": "note",
  "title": "My document",
  "slug": "my-document",
  "root_block_id": "root_123",
  "document_payload": {},
  "blocks_payload": [],
  "markdown": "# My document",
  "metadata": {},
  "created_at": "2026-06-18T00:00:00.000Z",
  "updated_at": "2026-06-18T00:00:00.000Z"
}

Grounded to omni-edge-proxy/src/routes/pkms.ts:90-104 and omni-edge-proxy/src/routes/pkms.ts:500-529.

Document summary

Workspace-scoped list routes return summaries shaped like:

{
  "id": "doc_123",
  "workspaceId": "ws_123",
  "notebookId": "nb_123",
  "title": "My document",
  "slug": "my-document",
  "rootBlockId": "root_123",
  "createdAt": "2026-06-18T00:00:00.000Z",
  "updatedAt": "2026-06-18T00:00:00.000Z",
  "_meta": {}
}

See omni-edge-proxy/src/routes/pkms.ts:439-451.

Core proxy routes

GET /health

Returns:

{ "status": "ok" }

Grounded to omni-edge-proxy/src/index.ts:43.

GET /v1/me

Verifies the caller token, resolves the user identity, and reports stored profile plus whether escrowed client key material exists.

Required headers:

• Authorization

Success response:

{
  "ok": true,
  "userId": "string",
  "profile": {
    "userName": "string | null",
    "display_name": "string | null",
    "age": 0
  },
  "clientKeyEscrow": {
    "present": true
  },
  "verifiedAt": "ISO8601 timestamp"
}

Failure response:

{
  "ok": false,
  "error": "Missing Token | Invalid token",
  "details": "string"
}

Grounded to omni-edge-proxy/src/index.ts:325-347.

POST /api/v1/webhooks/r1xG2bFatcOoQS0A28AQZ/sync

Firebase-backed compatibility webhook for session sync and wrapped-key restoration.

Required headers:

• Authorization

Request body:

{
  "client_temp_public_key": "string"
}

Response:

{
  "secret": "string",
  "userId": "string",
  "status": "new_user | missing_key | incomplete_profile | complete",
  "profile": {
    "userName": "string | null",
    "display_name": "string | null",
    "age": 0
  },
  "wrapped_key": "string | null",
  "debug_log": "Sync complete."
}

Grounded to omni-edge-proxy/src/index.ts:99-225.

POST /api/v1/webhooks/E6K9u35uZUEIJVnp2NivP/sync

Firebase-backed onboarding route for username registration and optional first-time client-key escrow.

Required headers:

• Authorization

Request body:

{
  "userName": "string",
  "display_name": "string",
  "age": 0,
  "clientKey": "string"
}

Response:

{
  "ok": true,
  "userId": "string",
  "profile": {
    "userName": "string",
    "display_name": "string | null",
    "age": 0
  },
  "clientKeyEscrowed": true,
  "encryptedBlobSaved": true
}

Grounded to omni-edge-proxy/src/index.ts:227-323.

Modern PKMS routes

GET /v1/workspaces

Lists workspaces visible to the authenticated identity.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Success response:

[
  {
    "id": "ws_123",
    "name": "Workspace name",
    "createdAt": "ISO8601 timestamp",
    "updatedAt": "ISO8601 timestamp"
  }
]

Grounded to omni-edge-proxy/src/routes/pkms.ts:339-349 and omni-edge-proxy/src/routes/pkms.ts:1151-1158.

POST /v1/workspaces

Creates a workspace.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Request body:

{
  "name": "Untitled Workspace"
}

Success response:

{
  "id": "ws_123",
  "name": "Untitled Workspace",
  "createdAt": "ISO8601 timestamp",
  "updatedAt": "ISO8601 timestamp"
}

Grounded to omni-edge-proxy/src/routes/pkms.ts:1161-1178.

GET /v1/workspaces/:workspaceId

Fetches one workspace.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Success response:

{
  "workspace": {
    "id": "ws_123",
    "name": "Workspace name",
    "createdAt": "ISO8601 timestamp",
    "updatedAt": "ISO8601 timestamp"
  }
}

Grounded to omni-edge-proxy/src/routes/pkms.ts:1180-1188.

POST /v1/documents

Creates a unified document record.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Request body fields accepted by the implementation include:

• workspace_id or workspaceId
• title
• id optional
• root_block_id or rootBlockId optional
• document_payload or documentPayload optional
• blocks_payload or blocksPayload optional
• markdown optional
• metadata or _meta optional
• indexable_blocks or indexableBlocks optional
• notebook_id or notebookId optional
• client_key or clientKey optional

If client_key or clientKey is present, the proxy encrypts documentPayload, blocksPayload, and markdown before storage. See omni-edge-proxy/src/routes/pkms.ts:408-437 and omni-edge-proxy/src/routes/pkms.ts:926-983.

Example request:

{
  "workspace_id": "ws_123",
  "title": "My note",
  "document_payload": {
    "format": "omni.om",
    "title": "My note",
    "type": "document"
  },
  "blocks_payload": [
    {
      "id": "root",
      "type": "page",
      "content": "Hello world"
    }
  ],
  "markdown": "# My note\n\nHello world",
  "metadata": {
    "source": "editor"
  },
  "indexable_blocks": [
    {
      "id": "root",
      "type": "page",
      "content": "Hello world"
    }
  ],
  "client_key": "optional-client-key"
}

Success response:

{
  "document": {
    "id": "doc_123",
    "project_id": "project_123",
    "workspace_id": "ws_123",
    "document_type": "note",
    "title": "My note",
    "slug": "my-note",
    "root_block_id": "root_123",
    "document_payload": {},
    "blocks_payload": [],
    "markdown": "# My note",
    "metadata": {},
    "created_at": "ISO8601 timestamp",
    "updated_at": "ISO8601 timestamp"
  }
}

Grounded to omni-edge-proxy/src/routes/pkms.ts:1227-1235 and omni-edge-proxy/src/routes/pkms.ts:500-529.

PATCH /v1/documents/:id

Partially updates a unified document.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Request body requirements:

• workspace_id or workspaceId is required

Supported update fields include:

• title
• root_block_id or rootBlockId
• document_payload or documentPayload
• blocks_payload or blocksPayload
• markdown
• metadata_patch
• indexable_blocks or indexableBlocks
• notebook_id or notebookId
• client_key or clientKey

metadata_patch merges keys and removes keys whose value is null. Grounded to omni-edge-proxy/src/routes/pkms.ts:986-1066.

DELETE /v1/documents/:id

Deletes the document and derived artifacts.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Required query parameter:

• workspace_id or workspaceId

Success response:

{
  "id": "doc_123",
  "deleted": true
}

Grounded to omni-edge-proxy/src/routes/pkms.ts:1250-1262.

POST /v1/documents/query

Queries documents using buildContext, which returns semantic results when available and keyword fallback otherwise.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Request body:

{
  "workspace_id": "ws_123",
  "query": "billing rollout",
  "top_k": 5,
  "include": {
    "notes": true,
    "memories": true,
    "files": false
  },
  "filter": {
    "eq": {
      "document_type": "note"
    }
  },
  "metadata": {
    "filters": {
      "workspaceId": "ws_123",
      "session_id": "ws_123"
    }
  }
}

Success response shape:

{
  "query": "billing rollout",
  "mode": "semantic",
  "items": [],
  "results": [],
  "contextText": "Relevant context:",
  "query_strategy": "semantic"
}

The implementation returns both items and results. See omni-edge-proxy/src/routes/pkms.ts:1068-1148 and omni-edge-proxy/src/routes/pkms.ts:1265-1273.

GET /v1/workspaces/:workspaceId/documents

Lists workspace document summaries.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Optional query parameter:

• notebookId

Success response:

{
  "documents": [
    {
      "id": "doc_123",
      "workspaceId": "ws_123",
      "notebookId": "nb_123",
      "title": "My note",
      "slug": "my-note",
      "rootBlockId": "root_123",
      "createdAt": "ISO8601 timestamp",
      "updatedAt": "ISO8601 timestamp",
      "_meta": {}
    }
  ]
}

Grounded to omni-edge-proxy/src/routes/pkms.ts:1275-1284.

POST /v1/workspaces/:workspaceId/documents

Creates a workspace-scoped unified document.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Behavior matches POST /v1/documents, except workspace_id is injected from the path. Response contains a summary document instead of the full unified record. Grounded to omni-edge-proxy/src/routes/pkms.ts:1286-1298.

GET /v1/workspaces/:workspaceId/documents/:documentId

Fetches a unified document plus blocks and markdown.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Optional query parameter:

• clientKey

Behavior:

• If clientKey query param is present, the route decrypts document.documentPayload, document.blocksPayload, document.markdown, blocks, and markdown before building the response.
• After that, the shared response transformer may still run if X-Proxy-Decrypt: true is set.

See omni-edge-proxy/src/routes/pkms.ts:1300-1335.

Response shape:

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

PUT /v1/workspaces/:workspaceId/documents/:documentId

Updates a workspace-scoped unified document using the same patch logic as PATCH /v1/documents/:id.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Response shape:

{
  "document": {
    "id": "doc_123",
    "workspaceId": "ws_123"
  }
}

Grounded to omni-edge-proxy/src/routes/pkms.ts:1337-1350.

DELETE /v1/workspaces/:workspaceId/documents/:documentId

Deletes a workspace-scoped unified document.

Required headers:

• Authorization
• optional X-Proxy-Decrypt
• optional X-Client-Key

Success response:

{
  "deleted": true
}

Grounded to omni-edge-proxy/src/routes/pkms.ts:1352-1365.

Supporting PKMS routes

These routes are still implemented and should be documented because they are part of the current proxy surface.

Derived index routes

All require Authorization and optionally accept X-Proxy-Decrypt and X-Client-Key.

Grounded to omni-edge-proxy/src/routes/pkms.ts:1514-1553.

File and manifest routes

Grounded to omni-edge-proxy/src/routes/pkms.ts:1555-1642.

Upload session routes

These routes do not require the PKMS auth helper in the current implementation.

Grounded to omni-edge-proxy/src/routes/pkms.ts:1644-1678.

Native Chat API (Phase 1)

The Native Chat API provides dedicated endpoints for managing chat threads and message streams, keeping chat interaction decoupled from standard note documents.

[!IMPORTANT] Chats bypass the createUnifiedDocument and patchUnifiedDocument helpers to prevent vector/file bloat. While standard documents generate block bundles and full markdown sidecars, chat sessions store message DAG streams directly in dedicated storage objects.

POST /v1/workspaces/:workspaceId/chats

Creates a new chat session thread. Initializes the underlying storage files (meta.om, document.om.enc, history.om.enc, and vector_state.om).

Request body:

{
  "title": "New Chat"
}

Response:

{
  "id": "chat_session_id",
  "title": "New Chat",
  "createdAt": "ISO8601 timestamp"
}

PATCH /v1/workspaces/:workspaceId/chats/:threadId

Updates the chat thread title or metadata.

Request body:

{
  "title": "Updated Chat Title"
}

Response:

{
  "success": true
}

GET /v1/workspaces/:workspaceId/chats/:threadId/messages

Fetches the complete array of messages in the chat's DAG array.

Response:

[
  {
    "id": "msg_123",
    "role": "user",
    "encryptedContent": "string",
    "createdAt": "ISO8601 timestamp"
  }
]

POST /v1/workspaces/:workspaceId/chats/:threadId/messages

Appends a new message to the message DAG array and increments the messageCount in the meta.om sidecar.

Request body:

{
  "role": "user | assistant",
  "content": "Message content"
}

Response:

{
  "id": "msg_124",
  "role": "user",
  "createdAt": "ISO8601 timestamp"
}

Spotlight Search Integration

[!NOTE] While Chats use a bespoke, lightweight write-path to optimize database and storage operations, they still write a meta.om sidecar file directly under the documents/ prefix. This ensures they are indexed correctly and can be seamlessly queried using the unified search endpoint (POST /v1/documents/query) via Spotlight Search.

AI & Memory Routes

These routes manage AI models, credit usage, memories, context building, and chat completions with transparent background memory injection.

GET /v1/models

Lists the available models for completions.

Required headers:

• Authorization

Success response:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "owned_by": "llm.ovh"
    }
  ]
}

Grounded to omni-edge-proxy/src/routes/ai.ts:429-446.

GET /v1/usage

Retrieves monthly usage tokens for the current month.

Required headers:

• Authorization

Success response:

{
  "month": "2026-07",
  "usage": {
    "totalTokens": 1500,
    "requestCount": 12
  }
}

Grounded to omni-edge-proxy/src/routes/ai.ts:448-458.

GET /v1/credits

Retrieves remaining monthly token allowance status.

Required headers:

• Authorization

Success response:

{
  "used": 1500,
  "limit": 1000000,
  "remaining": 998500,
  "month": "2026-07"
}

Grounded to omni-edge-proxy/src/routes/ai.ts:460-476.

POST /v1/chat/completions

An OpenAI-compatible chat completion route. If memory is enabled, the gateway automatically performs similarity searches behind the scenes within an 800ms window, injecting user memory context into the system prompt.

Required headers:

• Authorization
• optional X-Omni-Workspace
• optional X-Client-Key (for decrypting biography context if present)

Request body structure: Supports all standard OpenAI chat/completions fields plus:

• memory (object, optional):
  • enabled (boolean, default: true): Controls context retrieval.
  • limit (number, default: 8): Max context results to fetch.

Example request:

{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "user", "content": "What is my favorite technology stack?" }
  ],
  "memory": {
    "enabled": true,
    "limit": 5
  }
}

Success response headers:

• X-Omni-Shimmer: injected | skipped | timeout | no-context
• X-Omni-Memory-Count: Number of memories injected.

Success response (SSE stream or raw JSON): Standard OpenAI completion response.

Grounded to omni-edge-proxy/src/routes/ai.ts:478-828.

POST /v1/memories

Saves a fact, note, or developer preference to the memory store.

Required headers:

• Authorization

Request body:

• content (string, required): The fact content to save (max 50KB).
• id (string, optional): A custom ID.
• metadata (object, optional): Arbitrary key-value metadata.
• workspaceId / session_id (string, optional)

Example request:

{
  "content": "User prefers Dark Mode and primarily develops using Next.js and TypeScript."
}

Success response (201 Created):

{
  "id": "mem_a29c158d-71b5-4a65-8b3d-71f0dfc39972",
  "ownerId": "user_123",
  "projectId": "user_123",
  "content": "User prefers Dark Mode and primarily develops using Next.js and TypeScript.",
  "metadata": {},
  "status": "active",
  "createdAt": "2026-07-04T12:00:00.000Z",
  "updatedAt": "2026-07-04T12:00:00.000Z"
}

Grounded to omni-edge-proxy/src/routes/ai.ts:837-883.

GET /v1/memories

Lists user memories, sorted by creation date descending.

Required headers:

• Authorization

Optional query parameter:

• limit (number, default 100)

Success response:

{
  "data": [
    {
      "id": "mem_123",
      "content": "User prefers Dark Mode...",
      "createdAt": "2026-07-04T12:00:00.000Z"
    }
  ]
}

Grounded to omni-edge-proxy/src/routes/ai.ts:885-896.

GET /v1/memories/:id

Fetches a specific memory record by ID.

Required headers:

• Authorization

Grounded to omni-edge-proxy/src/routes/ai.ts:898-908.

DELETE /v1/memories/:id

Deletes a memory record.

Required headers:

• Authorization

Success response:

{
  "id": "mem_123",
  "deleted": true
}

Grounded to omni-edge-proxy/src/routes/ai.ts:910-920.

POST /v1/memories/search

Queries the memory vector store for semantic matches.

Required headers:

• Authorization

Request body:

• query (string, required): Semantic search string.
• limit (number, default 10)
• filters (object, optional)

Example request:

{
  "query": "technologies built with",
  "limit": 3
}

Success response:

{
  "data": [
    {
      "id": "mem_123",
      "content": "User prefers Dark Mode and primarily develops using Next.js and TypeScript.",
      "score": 1,
      "metadata": {}
    }
  ],
  "mode": "fulltext_fallback"
}

Grounded to omni-edge-proxy/src/routes/ai.ts:922-955.

POST /v1/context/build

Builds a consolidated Markdown context block containing the relevant matches from notes and memories, perfect for injecting directly into LLM prompts.

Required headers:

• Authorization

Request body:

• query (string, required): The query string.
• workspaceId (string, optional)
• limit (number, optional)
• include (object, optional):
  • memories (boolean, default true): Include vector memories.
  • notes (boolean, default false): Include notes from workspace.
  • files (boolean, default false): Include files.
• filters (object, optional)

Example request:

{
  "query": "Preferences on color schemes",
  "include": {
    "memories": true,
    "notes": true
  }
}

Success response:

{
  "query": "Preferences on color schemes",
  "mode": "fulltext_fallback",
  "items": [
    {
      "type": "memory",
      "id": "mem_123",
      "score": 1,
      "content": "User prefers Dark Mode and primarily develops using Next.js and TypeScript."
    }
  ],
  "contextText": "Relevant user memories:\n- User prefers Dark Mode and primarily develops using Next.js and TypeScript."
}

Grounded to omni-edge-proxy/src/routes/ai.ts:957-1005.

Notes for frontend implementers

• The current desktop client loads workspaces from /v1/workspaces but still performs note CRUD through legacy note routes, not the modern /v1/workspaces/:workspaceId/documents routes. See web-omni/src/features/desktop-client/DesktopClientApp.tsx:23-57 and web-omni/src/features/desktop-client/lib/documentRepository.ts:311-420.
• Search already uses the modern route /v1/documents/query. See web-omni/src/features/desktop-client/lib/documentRepository.ts:389-420.
• If you are building a new client, prefer the unified /v1/documents and /v1/workspaces/:workspaceId/documents routes for new work.