REST API

~2 min read

REST API

lettuce serve exposes a plain HTTP API at http://127.0.0.1:51234/api/v1 alongside the MCP endpoint at /mcp. They share the same VaultService, so semantics, auth, and error codes are identical.

Use REST when you’re integrating from a language or service that doesn’t speak MCP, or for a quick curl check.

Auth

All endpoints require Authorization: Bearer <api-key>. The key prints in the server banner; you can also see it in Settings → General → API keys or generate a new one there.

A few example calls

BASE=http://127.0.0.1:51234/api/v1
AUTH="Authorization: Bearer $LETTUCE_API_KEY"

# Vault info
curl -sH "$AUTH" "$BASE/vault"

# List notes under a folder, non-recursive
curl -sH "$AUTH" "$BASE/notes?folder=Inbox&recursive=false"

# Read a note
curl -sH "$AUTH" "$BASE/notes/Inbox/Triage.md"

# Search
curl -sH "$AUTH" "$BASE/search?q=lettuce"

# Backlinks
curl -sH "$AUTH" "$BASE/backlinks/Linking%20and%20Tags.md"

# Tags
curl -sH "$AUTH" "$BASE/tags"

# Lint
curl -sH "$AUTH" "$BASE/lint"

# Write (create)
curl -sH "$AUTH" -H "Content-Type: application/json" -X PUT \
     -d '{"content":"# Hello\n","mode":"create"}' \
     "$BASE/notes/Hello.md"

# Move (and update inbound links: [[wikilinks]] and [text](path.md))
curl -sH "$AUTH" -X POST -d '{"from":"Old.md","to":"New.md","updateLinks":true}' \
     "$BASE/move"

For the full operation set, prefer the MCP tool list since everything there is also reachable over REST under the same VaultService surface.