Open API and Remote MCP

Dessix provides two external integration surfaces:

• REST API for scripts, automation, and third-party integrations.
• Remote MCP for AI clients such as Cursor, Claude Code, and ChatGPT.

Both surfaces share the same backend services, access token authentication, and resource ownership checks.

Available Capabilities

Open API and Remote MCP expose Dessix content data operations to external tools:

• List workspaces, resolve current workspace, create workspace, and update basic workspace metadata.
• Search blocks by keyword or semantic vector, read, create, update, soft delete, restore, and move blocks.
• Create, rename, move, delete, and list children for folders.

Access Token

REST API and Remote MCP both use:

Authorization: Bearer dx_live_xxx

Permission model:

• A token can only access data owned by the token user.
• External requests cannot pass or override user_id.
• workspace_id is only a resource locator, not a permission grant.
• Cross-user access returns not found style errors to avoid resource enumeration.
• Tokens can be created, listed, and revoked from the App workspace settings advanced panel.

REST API Examples

List workspaces:

curl https://api.dessix.io/v1/open/workspaces \
  -H "Authorization: Bearer dx_live_xxx"

Search blocks semantically:

curl "https://api.dessix.io/v1/open/blocks/search?workspace_id=workspace_xxx&semantic=project%20retro&types=Note&limit=5" \
  -H "Authorization: Bearer dx_live_xxx"

Create a block:

curl https://api.dessix.io/v1/open/blocks \
  -H "Authorization: Bearer dx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "workspace_xxx",
    "patch": {
      "type": "Note",
      "title": "API note",
      "content": "Created from REST API"
    }
  }'

Remote MCP

Remote MCP endpoint:

https://api.dessix.io/v1/mcp

Remote MCP keeps tool names and input schemas compatible with the existing Local MCP. Clients should send the access token as an Authorization header. The semantic argument on dessix_search_blocks uses server-side semantic vector search; query is for keyword search.

Default Workspace

If workspace_id is omitted, the server uses the most recently opened workspace:

ORDER BY last_opened_at DESC NULLS LAST, updated_at DESC

If the user has no workspace, read-style requests return NO_WORKSPACE_SELECTED. Content creation flows can explicitly create a workspace first.

Folder Deletion Semantics

Folder deletion matches the behavior inside the Dessix App. When deleting a folder:

• The target folder and its sub-folders are deleted.
• Content blocks using those folders have their folder reference cleared and are moved to trash.
• The root folder cannot be deleted.

Content Size Limits

• read_block returns at most 20,000 content characters for one block.
• Truncated content includes content_truncated, content_limit, and content_original_length.

Error Codes

Common error codes:

• UNAUTHORIZED
• TOKEN_REVOKED
• TOKEN_EXPIRED
• NO_WORKSPACE_SELECTED
• WORKSPACE_NOT_FOUND
• BLOCK_NOT_FOUND
• FOLDER_NOT_FOUND
• INVALID_ARGUMENT