API Access

The MindWiki REST API lets external software read from and write to your vault directly. Use it for custom agents, automation platforms, scripts, webhooks, and integrations with tools like Readwise, Notion, ClickUp, Make, Zapier, and Raycast.

API keys also work as authentication for the MCP endpoint when a client doesn't support remote MCP / OAuth.

Where keys come from

Mint, view, and revoke keys at mindwiki.io/account/api-keys. Each key has:

  • A name you give it (e.g. "Readwise capture", "Notion automation", "Local script").
  • Scopes you select at creation: read, write, or both.
  • A creation timestamp and last-used timestamp.

The full key is shown exactly once at creation. Copy it then. MindWiki stores only a hash, so we cannot recover a key after creation.

Base URL

https://api.mindwiki.io

Authentication

Every request authenticates with a Bearer token:

Authorization: Bearer YOUR_API_KEY

Keys start with mw_. The format is opaque — don't try to parse it.

Scopes

Two scopes:

  • `read` — search, read pages, list pages, ask, find similar, view graph, vault health, stats, export.
  • `write` — capture, create or update pages, delete pages, rebuild index.

A request that needs a scope you didn't grant returns:

json
{
  "error": "API key does not include write scope",
  "code": "INSUFFICIENT_SCOPE",
  "required_scope": "write"
}

with HTTP 403.

Read endpoints

EndpointWhat it does
GET /vault/pagesList pages in your vault
GET /vault/page/{path}Read a specific page
GET /vault/search?q=queryFull-text + semantic search
GET /vault/graphKnowledge graph as { nodes, edges }
GET /vault/healthVault integrity check
GET /vault/statsPage count, word count, link count
GET /vault/exportDownload the full vault as a zip
POST /vault/askAsk a question; get a synthesized answer

Write endpoints

EndpointWhat it does
POST /vault/captureQuick capture into capture/
POST /vault/pageCreate or update a page
DELETE /vault/page/{path}Delete a page
POST /vault/index/rebuildRebuild the vault index

Both POST /vault/page and DELETE /vault/page/{path} use optimistic concurrency. Pass base_hash to assert the current hash; if it doesn't match, you get HTTP 409 with code: "CONFLICT" and the actual current hash so you can reconcile.

Sync endpoints

These power native client sync. Most integrations don't need them, but they're documented here for completeness:

EndpointNotes
GET /vault/changesPull events since a sequence cursor
POST /vault/changes/ackDevice clients only — record last-synced cursor

Examples

Search your vault

bash
curl -H "Authorization: Bearer $MINDWIKI_API_KEY" \
  "https://api.mindwiki.io/vault/search?q=onboarding"

Read a specific page

bash
curl -H "Authorization: Bearer $MINDWIKI_API_KEY" \
  "https://api.mindwiki.io/vault/page/projects/onboarding-redesign/spec.md"

Capture from any external tool

bash
curl -X POST "https://api.mindwiki.io/vault/capture" \
  -H "Authorization: Bearer $MINDWIKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Readwise highlight",
    "source": "readwise",
    "content": "A saved highlight or note goes here."
  }'

The capture lands at capture/{date}-{slug}.md automatically.

Create or update a page

bash
curl -X POST "https://api.mindwiki.io/vault/page" \
  -H "Authorization: Bearer $MINDWIKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "capture/external-integration.md",
    "content": "---\ntitle: External Integration\narea: capture\ntype: note\n---\n\n# External Integration\n\nCreated through the API.",
    "message": "Created from API"
  }'

Ask MindWiki a question

bash
curl -X POST "https://api.mindwiki.io/vault/ask" \
  -H "Authorization: Bearer $MINDWIKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What recent notes mention agent-native memory?",
    "max_pages": 5
  }'

Common integration recipes

Readwise → MindWiki

Use Readwise's webhook export to POST highlights into /vault/capture. The content field holds the highlight, source: "readwise" keeps things filterable, title becomes the page title.

Notion → MindWiki

Use a Notion automation or Make / Zapier scenario to POST changed Notion pages to /vault/page. Path them under a folder like notion-mirror/ to keep them separate from native MindWiki pages.

ClickUp → MindWiki

Trigger on ClickUp task creation or status change. POST a summary to /vault/capture for low-friction sync, or to /vault/page for a structured page per task.

Zapier / Make scenarios

Both platforms can call MindWiki via a generic HTTP step. Authenticate with Bearer header. Use /vault/capture for inbound automation and /vault/search to lookup existing pages.

Custom scripts

Any language with HTTP support works. The patterns are stable: Bearer auth, JSON bodies for POST, query params for GET. Keep your key in a secrets manager and rotate when staff change.

Rate limits

The API enforces rate limits per user. If you hit a limit, you get HTTP 429 with Retry-After indicating when to retry.

MCP via API key (legacy fallback)

MCP clients that don't support remote MCP / OAuth can authenticate by appending ?token=YOUR_API_KEY to the MCP URL:

https://api.mindwiki.io/mcp?token=YOUR_API_KEY

The same scope rules apply — a read-only API key cannot call write tools through MCP.

Security guidance

  • Use scoped keys. Mint read-only keys for automations that don't need to write. The minimum-privilege key is the safest one.
  • One key per integration. When you stop using a tool, revoke its key. Granular keys make this painless.
  • Don't commit keys. Use environment variables, secrets managers, or platform-native secrets storage.
  • Rotate after exposure. If a key may have leaked, revoke and re-mint immediately.
  • Audit periodically. The keys list shows last-used timestamps. Keys that haven't been used in months are cleanup candidates.

Where to go next