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/convertpipeline, 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/configcan'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.