open-context open-context
October 25, 2026 · 6 min read

The open-context REST API: A Full Endpoint Reference

open-context ships a full REST API on port 3000 — the exact same API its own web UI calls — covering conversation conversion, preferences, MCP contexts, bubbles, and database management. Every route lives under /api and returns JSON, so you can script context-store operations or build your own tooling against the same local store Claude's MCP server reads from, without touching the UI at all.

Key takeaways

  • The REST API isn't a separate product bolted onto the UI — it's the literal interface open-context's React app in ui/src/ consumes; anything the Dashboard or ContextViewer can do, a script can do over plain HTTP.
  • Six endpoint groups cover the whole product: health and Ollama diagnostics, the /api/convert pipeline, preferences, contexts (the MCP store's CRUD), bubbles (project workspaces), and database management.
  • There's no built-in authentication. The API assumes it's running on localhost or inside a trusted Docker network — the same assumption documented for the stdio MCP server.
  • Switching backends with PUT /api/db/config can't take the server down — it only replaces the active connection once the new one opens successfully.
  • Every database-facing response, including /api/db/status, returns a redacted connection string — raw credentials never leave the process.

Why open-context has a REST API at all

open-context already ships a CLI for one-shot conversion and an MCP server that gives Claude persistent memory across sessions. The REST API, defined in src/server.ts as a plain Express app, is what makes the web UI possible at all. Rather than build a UI-specific backend, the project exposed its context store and conversion pipeline as one HTTP API that the React app consumes with ordinary fetch calls. That means every button in the Dashboard, ContextViewer, PreferencesEditor, and VendorExport maps to a documented route below — nothing in the UI has a private shortcut the API doesn't also expose.

Endpoint reference

Every route is prefixed with /api, returns JSON, and requires no API key.

Health and Ollama diagnostics

GET /api/health returns { status, ollamaHost, store }, where store is the redacted connection string from the active database resolution. GET /api/ollama/models proxies to whichever Ollama host the server is configured with — OLLAMA_HOST, defaulting to http://host.docker.internal:11434 so a container can reach a model running on its host machine — and returns a 503 if Ollama isn't reachable, rather than hanging.

Conversion

POST /api/convert accepts a multipart file upload (your ChatGPT export ZIP) plus optional model, ollamaHost, and skipPreferences fields. It runs the full pipeline server-side — extract, parse, normalize, then analyze — and returns the normalized conversations plus generated preferences and memory text. If AI analysis fails or skipPreferences is true, it falls back to a template-based generator instead of erroring, so a bad or missing Ollama connection never breaks the conversion itself.

Contexts

Full CRUD over the MCP store: GET /api/contexts (optional ?tag= filter), POST /api/contexts (content, tags, source, bubbleId), GET /api/contexts/search?q=, and GET/PUT/DELETE /api/contexts/:id. This is the same store the MCP server's save_context and recall_context tools write to — a context you save through the API shows up the next time Claude calls list_contexts, and vice versa.

Bubbles

CRUD for project workspaces: GET /api/bubbles returns every bubble with a contextCount, POST creates one, GET/PUT/DELETE /api/bubbles/:id manage a single bubble, and GET /api/bubbles/:id/contexts lists everything saved inside it. Deleting a bubble takes a ?deleteContexts=true flag to decide whether its contexts are removed along with it or just detached.

Database management

GET /api/db/status reports the active adapter, whether OPENCONTEXT_DB_URL has it locked, and context/bubble counts. GET /api/db/adapters lists all 15 supported backends and whether each one's driver package is installed. POST /api/db/test opens a candidate connection string, pings it, and closes it again without touching the live store. PUT /api/db/config switches the live store, keeping the previous one running if the new connection string fails to open, and POST /api/db/migrate copies contexts and bubbles into a different backend, read-only on the source.

A worked example

Save a context, search for it, and check which database is currently backing the store:

curl -X POST http://localhost:3000/api/contexts \
  -H "Content-Type: application/json" \
  -d '{"content": "Prefers TypeScript, writes tests before refactors", "tags": ["preferences"], "source": "manual"}'

curl "http://localhost:3000/api/contexts/search?q=typescript"

curl http://localhost:3000/api/db/status

The search endpoint does a case-insensitive substring match over content, tags, and source — the exact search semantics the project's conformance suite locks in identically across every one of the 15 backends, so the same curl command behaves the same way whether the store is a local JSON file or a managed Postgres instance.

Keeping it safe beyond localhost

None of these routes check a credential, because the API is built around the same assumption as open-context's MCP server: it runs on your own machine, or inside a Docker network you control. That's fine for the default docker run -p 3000:3000 setup, but if you bind it to a shared network or expose it over the internet, put a reverse proxy with its own authentication in front of it rather than relying on the API itself to gate access. Credential handling for the database layer is already covered — every connection-string response goes through the same redaction the rest of the project uses — but network exposure is a separate concern the API intentionally leaves to you.

Point your own scripts at the same API that drives the open-context UI.

Get started with open-context →

FAQ

Does the open-context REST API require an API key or auth token?

No. The API has no built-in authentication — it's designed to run on localhost or inside a trusted Docker network, the same assumption documented for open-context's stdio MCP server. If you expose it beyond that, put it behind a reverse proxy that handles auth itself.

What's the difference between the REST API and the MCP server?

The MCP server talks to Claude over stdio using six fixed tools (save_context, recall_context, and so on). The REST API is a general HTTP interface over the same context store, used by open-context's own web UI and available for any script or custom integration you write yourself.

Can I manage bubbles entirely through the REST API?

Yes. GET, POST, PUT, and DELETE on /api/bubbles and /api/bubbles/:id cover creating, renaming, and removing project workspaces, and GET /api/bubbles/:id/contexts lists everything saved inside one — the same operations the Dashboard's bubble UI performs.

Does switching database backends through the API risk losing data?

No. PUT /api/db/config only replaces the live connection once the new one opens successfully, so a bad connection string can't take the server down. /api/db/migrate is read-only on the source store, copying into the target rather than modifying what's already there.