HTTP API

The Imprint container runs a FastAPI server on port 8420. Everything the built-in dashboard does — search, ingest, retag, graph walks, sync, chat — is available over plain HTTP for any external client: a backend service pushing data, a CI job retagging after a merge, your own UI, or a quick curl to see what’s in memory.

Note

The API is designed to run on localhost or behind a reverse proxy that handles auth. There is no built-in authentication. Don’t expose port 8420 to the public internet without one (TLS examples).

Get started

Postman

Download collection →

Import into Postman, Insomnia, or Bruno. Covers every endpoint below with example bodies and a {{base_url}} variable preset.

OpenAPI

Live schema at /openapi.json →

Auto-generated by FastAPI on every boot. Import into any OpenAPI-aware tool, or open /docs for interactive Swagger UI.

Quick tour

# 1. Confirm the server is up
curl -s http://localhost:8420/api/version

# 2. Search the corpus
curl -s "http://localhost:8420/api/search?q=chunking+system&limit=5"

# 3. Enqueue an ingest job — returns {job_id, position}
curl -s -X POST http://localhost:8420/api/commands/ingest \
  -H "Content-Type: application/json" \
  -d '{"args": ["/workspace"], "project": "my-project"}'

# 4. Tail job output live (Server-Sent Events)
curl -N http://localhost:8420/api/jobs/<job_id>/stream

If you’re running in Docker, swap localhost:8420 for your container or proxy host — the base URL is the only thing that changes.

Endpoint reference

Endpoints are grouped by responsibility. The Postman collection mirrors this structure folder-for-folder so you can scan the reference and the collection side by side.

Overview & stats

Method	Path	Purpose
GET	/api/version	Installed imprint CLI version — cheap healthcheck.
GET	/api/stats	Aggregate counts per project, type, and language.
GET	/api/overview	Bubble-chart overview. Repeat ?type= for multi-filter.
GET	/api/timeline	Recent activity feed. ?project=, ?limit=.
GET	/api/cross-project	Project-to-project similarity matrix.

Search & retrieval

Method	Path	Purpose
GET	/api/search	Semantic search. Filters: q, project, type, limit.
GET	/api/neighbors	KNN over embeddings. ?id=<memory_id>&k=10.
GET	/api/memory/{id}	Full payload for a single memory.
GET	/api/nodes	Graph node list (positions + clusters) for visualization.

# Search only decisions in one project
curl -s "http://localhost:8420/api/search?q=chunking&project=imprint&type=decision&limit=10"

Sources

Method	Path	Purpose
GET	/api/sources	All indexed files with chunk counts.
GET	/api/sources/summary/{source_key}	Summary metadata for one source.
GET	/api/source/{source_key}	Chunks + tags + neighbors for one source.

Projects & topics

Method	Path	Purpose
GET	/api/project/{name}	Stats + top sources + top topics per project.
GET	/api/topics	Topic facet counts.
GET	/api/topic/{name}	Projects + memories tagged with one topic.
GET	/api/graph	Graph walk. ?scope=root|project:X|topic:X|source:X|chunk:X&depth=1..3.

Knowledge graph

Method	Path	Purpose
GET	/api/kg	Facts list. ?subject= partial match.
GET	/api/kg/entity/{entity}	Facts about one entity.

Workspaces

Method	Path	Purpose
GET	/api/workspaces	List all workspaces + active one.
POST	/api/workspace/switch	Switch active workspace. Body: {"name": "..."}.
POST	/api/workspace/create	Create a new workspace. Body: {"name": "..."}.

CLI commands (async jobs)

Every queue-safe imprint CLI command is reachable here. The endpoint enqueues a background job, returns {job_id, position} immediately, and the job runs through the same single-slot queue the dashboard uses.

Method	Path	Purpose
POST	/api/commands/{command}	Enqueue a command. See below for the allowlist.
GET	/api/queue	Active + queued + recent jobs.
GET	/api/jobs/{id}	Job status + exit code.
GET	/api/jobs/{id}/stream	SSE stream of live stdout/stderr.
POST	/api/jobs/{id}/cancel	SIGTERM the job (SIGKILL after 3 s).

Allowlisted commands: status, ingest, ingest-url, refresh, refresh-urls, retag, learn, config, wipe, sync, migrate, workspace.

# Ingest a URL in the "docs" project
curl -s -X POST http://localhost:8420/api/commands/ingest-url \
  -H "Content-Type: application/json" \
  -d '{"args": ["https://example.com/article"], "project": "docs"}'

Tip

For inline content that doesn’t live at a URL or filesystem path (API uploads, pasted transcripts, generated logs), prefer the ingest_content MCP tool over /api/commands/ingest-url — it takes the bytes inline, handles dedup/replace by name, and avoids a trip through the job queue. See MCP tools.

Sync

Method	Path	Purpose
POST	/api/sync/export	Write a snapshot bundle to a server-side path.
POST	/api/sync/import	Restore from a server-side bundle path.
GET	/api/sync/export/download	Stream a zipped snapshot to the browser.
POST	/api/sync/import/upload	Multipart upload of a zip bundle.
POST	/api/sync/cancel	Cancel an active peer-sync session by session_id.
POST	/api/sync/approve	Resolve the provider-side [y/n/t] prompt. Body: {"session_id": "...", "decision": "accept" | "trust" | "reject"}.
GET	/api/desktop-learn/history	Previously-indexed Claude Desktop / ChatGPT Desktop export zips (SHA-keyed).
POST	/api/desktop-learn/scan	One-shot Downloads scan for new desktop-app conversation exports. Body (optional): {"paths": ["/extra/dir", ...]}. Returns the structured scan result used by the dashboard.

Peer sync between two machines still uses the CLI’s imprint sync command — see sync. The HTTP endpoints above cover snapshot-based sync (export → transfer zip → import) for cases where a direct WS connection isn’t available.

Config

Method	Path	Purpose
GET	/api/config	All resolved config values + their source.
PUT	/api/config/{key}	Set a config key. Body: {"value": ...}.

# Turn on LLM tagging
curl -s -X PUT http://localhost:8420/api/config/tagger.llm \
  -H "Content-Type: application/json" \
  -d '{"value": true}'

Chat

Method	Path	Purpose
GET	/api/chat/status	Configured provider + model + readiness.
GET	/api/chat/sessions	List chat sessions.
POST	/api/chat/sessions	Create a new session.
GET	/api/chat/sessions/{sid}	Session transcript.
POST	/api/chat/sessions/{sid}/rename	Rename session.
DELETE	/api/chat/sessions/{sid}	Delete session.
POST	/api/chat	Send a message. Returns an SSE stream of tokens + tool calls.

Streams & long-polling

Three endpoints return Server-Sent Events:

• /api/jobs/{id}/stream — live stdout/stderr for a background job
• /api/chat — agent tokens + tool call events
• /api/sync/serve and /api/sync/receive — peer-sync progress events

Use EventSource in the browser, sseclient in Python, or curl -N to consume. Postman shows raw bytes — useful for inspecting events but not for interactive streaming.

MCP vs HTTP

The HTTP API and the MCP server expose similar capabilities through different transports. Pick the one that matches your integration:

	MCP (stdio)	HTTP API
Consumer	Coding agents (Claude Code, Cursor, Copilot, Cline, OpenClaw)	Anything that speaks HTTP
Transport	JSON-RPC over stdio	REST + SSE
Auth	None (local process)	None by default — terminate TLS + auth at a proxy
Ingest content	ingest_content	POST /api/commands/ingest* (job queue)
Search	search	GET /api/search
Streaming	Native	SSE
Best for	Agent integrations	External services, CI, dashboards

Versioning

The API follows the same release channel as the rest of Imprint — see installation. The Postman collection in this repo is versioned alongside the code; the live OpenAPI schema at /openapi.json always matches the running container.