API Reference

The MindWiki API has two surfaces:

  • A REST API at https://api.mindwiki.io for direct read/write to your vault from scripts, automations, and external services.
  • An MCP endpoint at https://api.mindwiki.io/mcp for AI clients (Claude.ai, Claude Desktop, Claude Code, ChatGPT, Codex, Cursor, custom clients) to access the vault as tool calls.

Both access the same user vault, but external MCP OAuth credentials are restricted to MCP. External REST integrations use personal API keys.

Muse connector support is in development; its reviewed directory launch and live verification are pending. See the Muse guide and the separate Muse Code guide.

Base URL

https://api.mindwiki.io

Authentication

Every request authenticates with one of:

  • OAuth Bearer for AI clients connecting via remote MCP. The flow is browser-based and returns the user-approved MCP scopes. See Authentication.
  • Personal API key (mw_*) for REST clients and for AI clients that don't speak remote MCP. Mint at mindwiki.io/account/api-keys. Scopes are explicit at creation.

Scopes

Personal API keys use two scopes:

  • `read` — search, read pages, list pages, ask, similar, graph, lint, export, stats.
  • `write` — capture, create or update pages, delete pages, rebuild index, create proposals.

OAuth uses mcp:read, mcp:capture, and mcp:write; legacy mcp allows all three. Write includes capture. Vault agent permissions also apply. REST scope failures return HTTP 403 with code: "INSUFFICIENT_SCOPE"; MCP clients must inspect the MCP error response.

Rate limits

The API enforces rate limits per user. If you hit a limit, you get HTTP 429 with Retry-After. Headers X-RateLimit-Limit and X-RateLimit-Remaining are included on every response so clients can track usage.

REST endpoints (summary)

Read (read scope):

  • GET /vault/pages
  • GET /vault/page/{path}
  • GET /vault/search
  • GET /vault/graph
  • GET /vault/health
  • GET /vault/stats
  • GET /vault/export
  • POST /vault/ask

Write (write scope):

  • POST /vault/capture
  • POST /vault/page
  • DELETE /vault/page/{path}
  • POST /vault/index/rebuild

Sync:

  • GET /vault/changes (read)
  • POST /vault/changes/ack (device clients only)

MCP endpoint

https://api.mindwiki.io/mcp

For OAuth-aware clients, use the URL alone. For clients that need a key in the URL, use https://api.mindwiki.io/mcp?token=YOUR_API_KEY.

The MCP endpoint exposes 27 tools across read, write, agent layer, context pack, and guide categories. See the sections below for each tool.

OAuth metadata

Discovery and metadata endpoints for client implementers:

  • https://api.mindwiki.io/.well-known/oauth-protected-resource
  • https://api.mindwiki.io/.well-known/oauth-authorization-server
  • https://api.mindwiki.io/oauth/register (Dynamic Client Registration)
  • https://mindwiki.io/oauth/authorize
  • https://api.mindwiki.io/oauth/token
  • https://api.mindwiki.io/oauth/revoke

PKCE (S256) is required. Request the MCP resource https://api.mindwiki.io/mcp and only the scopes needed. See Authentication for grant behavior.