Search

REST endpoints for querying TermFlow's full-text index of terminal history, fetching typeahead suggestions, and clearing the index. All paths are relative to the API base URL, http://127.0.0.1:42031/api.

Part of the REST API

These endpoints share the base URL, ports, error conventions, and authentication model described in Overview & Auth. In the default localhost-only mode every endpoint here is unauthenticated (safe because the server is bound to 127.0.0.1); a bearer token is required only once you expose the server on your LAN.

note

This is not the in-terminal Ctrl/Cmd+F search

The interactive search overlay you open with Ctrl/Cmd+F inside a terminal is a live, client-side match over the visible buffer — a completely separate feature. See In-terminal search for that. The endpoints on this page query a server-side index of stored terminal documents.

Endpoints at a glance

Method	Path	Purpose
POST	/api/search	Full-text query over indexed terminal history
GET	/api/search/suggestions	Typeahead word completions for a prefix
DELETE	/api/search/index	Clear the entire search index

An honest note: These endpoints are wired up and functional, but in the current early-access build nothing automatically feeds terminal output into the search index — the code path that would add documents exists but is not yet connected to live terminal activity. In practice that means POST /api/search returns an empty results array and GET /api/search/suggestions returns an empty list until the index has been populated out of band. Treat this as a stable API surface whose data source is still being wired up, not as a fully populated history you can query today.

POST /api/search

Runs a case-insensitive substring search over every document in the index, applies optional filters, sorts hits newest-first, and returns up to limit matches.

Request body

Send a JSON body (Content-Type: application/json):

Field	Type	Required	Default	Description
query	string	Yes	—	Text to search for. Matching is a case-insensitive substring test against each document's content.
filters	object	No	{}	Narrow the result set. Only the keys listed below are honored; any other key is ignored.
limit	number	No	50	Maximum number of results to return.

Supported filters keys:

Filter key	Matches against	Example values
terminalId	The terminal a document came from	"term-1"
type	The kind of document	"output", "input", "error"

How a query is processed

Example request

curl -X POST http://127.0.0.1:42031/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "connection refused",
    "filters": { "type": "error" },
    "limit": 20
  }'

Response

{
  "results": [
    {
      "document": {
        "id": "3f2a9c7e-1b44-4d0a-9e2f-8c1d6b0a7f31",
        "terminalId": "term-1",
        "type": "error",
        "timestamp": "2026-07-04T10:15:30.123456Z"
      },
      "score": 1.0,
      "matches": [[27, 45]],
      "context": "curl: (7) Failed to connect: connection refused by host"
    }
  ]
}

Each entry in results has the following shape:

Field	Type	Description
document.id	string	Unique document identifier (UUID).
document.terminalId	string	The terminal the document came from.
document.type	string	"output", "input", or "error".
document.timestamp	string	RFC 3339 / ISO 8601 timestamp of when the document was indexed.
score	number	Relevance score. Currently a constant 1.0 for every hit.
matches	array	List of [start, end] character-index pairs marking the matched span within the document's content.
context	string	A text snippet around the first match (roughly 50 characters on either side).

Results are ordered newest-first by document.timestamp, then truncated to limit.

GET /api/search/suggestions

Returns unique words from the index that begin with the given prefix — useful for building a typeahead / autocomplete box.

Query parameters

Parameter	Type	Required	Description
q	string	Yes	The prefix to complete. Passed as a query-string parameter; matching is case-insensitive.

Example request

curl "http://127.0.0.1:42031/api/search/suggestions?q=conn"

Response

{ "suggestions": ["connection", "connect", "connected"] }

The suggestions array contains unique whole words drawn from indexed content that start with q. It is capped at roughly 10 entries and is not sorted by relevance or frequency — treat the order as arbitrary. Word casing is preserved from the source content.

DELETE /api/search/index

Permanently removes every document from the search index and persists the now-empty index.

Example request

curl -X DELETE http://127.0.0.1:42031/api/search/index

Response

{ "status": "cleared" }

If the index cannot be persisted after clearing, the endpoint responds with HTTP 500 and an error body instead:

{ "error": "..." }

This is irreversible

Clearing the index deletes all indexed documents and cannot be undone. There is no per-terminal or per-type scoped delete — this wipes everything.

A related route this reference omits

The running server also exposes GET /api/search/history, but it is a stub that always returns an empty list ({ "history": [] }). It is intentionally left out of this reference — see what the reference does not document for the full list of stub and internal routes.

Next steps

• Overview & Auth — base URL, ports, the auth model, and the API-wide error conventions these endpoints follow.
• In-terminal search — the interactive Ctrl/Cmd+F overlay, which is a separate, live search feature (not backed by these endpoints).