Reference

REST API

HTTP endpoints exposed by gno serve for search, documents, graph data, models, jobs, and workspace automation.

The REST API is the HTTP version of the local GNO engine. Start it with gno serve, then call /api/* from curl, scripts, desktop launchers, internal dashboards, or small apps. It is best when you want automation without embedding the SDK or installing an MCP client.

What this is

• Search API — BM25, vector, hybrid query, and cited ask endpoints.
• Workspace API — documents, folders, collections, tags, links, graph, note presets, and autocomplete.
• Operations API — status, sync, jobs, model pull status, and connector detection.

Launch the server

gno serve # default port 3000
gno serve --port 8080
gno serve --detach # browser workspace + API in background

Read endpoints

• GET /api/health — basic liveness check.
• GET /api/status — index stats, collection health, model state, background watcher state, and onboarding state.
• GET /api/capabilities — feature availability for the active install.
• GET /api/collections, GET /api/tags, GET /api/docs, GET /api/doc — enumerate and fetch local content.
• GET /api/doc/:id/links, GET /api/doc/:id/backlinks, GET /api/doc/:id/similar, GET /api/graph — graph and relationship data.
• GET /api/events — server-sent document change events for live UIs.

Search endpoints

curl -X POST localhost:3000/api/search -d '{"q":"exact term"}'
curl -X POST localhost:3000/api/vsearch -d '{"q":"concept"}'
curl -X POST localhost:3000/api/query -d '{"q":"research question"}'
curl -X POST localhost:3000/api/ask -d '{"q":"what changed?"}'

Search bodies mirror the CLI: collection, limit, since, until, category, author, intent, exclude, tags_any, tags_all, and mode-specific controls such as noExpand, noRerank, candidateLimit, and queryModes.

curl localhost:3000/api/query \
  -H 'content-type: application/json' \
  -d '{
    "q": "authentication",
    "collection": "notes",
    "limit": 20,
    "tags_any": ["security"]
  }'

Write and job endpoints

• POST /api/collections and DELETE /api/collections/:name — add or remove indexed folders.
• POST /api/sync — trigger reindexing from the browser or an automation.
• POST /api/docs, PUT /api/docs/:id, POST /api/docs/:id/move, POST /api/docs/:id/duplicate, POST /api/docs/:id/deactivate — create and manage editable documents.
• POST /api/folders — create a folder inside a collection.
• POST /api/models/pull, GET /api/models/status, GET /api/jobs/active, GET /api/jobs/:id — model downloads and long-running job polling.

Security model

• Localhost by default. The server is designed for your own machine. If you expose it to a network, put authentication in front.
• CSRF protection. Mutating browser requests need a same-origin local origin or an API token.
• Optional token. Set GNO_API_TOKEN and send X-GNO-Token from non-browser clients.

export GNO_API_TOKEN="secret"
gno serve
curl -H "X-GNO-Token: secret" localhost:3000/api/status