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 use the same authentication and the same scope model.

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 grants both read and write scopes by default. 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

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.

Calling a tool or endpoint that requires a scope your token doesn't include returns HTTP 403 with code: "INSUFFICIENT_SCOPE".

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 20 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. Scope is mcp.