# How to Use Hister API Endpoints for Search and Configuration

> Discover Hister API endpoints for powerful search and server configuration. Learn how to use GET /search and GET /api/config to integrate Hister into your applications.

- Repository: [Adam Tauber/hister](https://github.com/asciimoo/hister)
- Tags: api-reference
- Published: 2026-08-27

---

**Hister exposes two public HTTP endpoints—`GET /search` for executing queries and `GET /api/config` for retrieving server configuration—both defined in [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go) and implemented in [`server/endpoints.go`](https://github.com/asciimoo/hister/blob/main/server/endpoints.go).**

The `asciimoo/hister` repository provides a lightweight search engine with a minimal public API surface. Understanding these **Hister API endpoints** allows developers to integrate full-text search capabilities and read runtime configuration without authentication. Both endpoints are registered centrally and support modern protocols including WebSocket streaming for real-time results.

## Hister Search API Endpoint

The search endpoint provides flexible query execution through both traditional HTTP requests and persistent WebSocket connections.

### Endpoint Specification

**`GET /search`** serves as the primary interface for document retrieval. According to the source code in [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go) (lines 77‑82), this route accepts standard HTTP GET requests and operates as a **public endpoint** requiring no authentication or session tokens.

The endpoint behavior branches based on request parameters:

- **With query parameters**: Returns JSON search results immediately
- **Without query parameters**: Upgrades the connection to a WebSocket for streaming queries

### Implementation Details

In [`server/endpoints.go`](https://github.com/asciimoo/hister/blob/main/server/endpoints.go), the `serveSearch` handler orchestrates request processing. The function calls `parseSearchQueryParams` (defined at lines 32‑44) to extract URL parameters and construct an `indexer.Query` object. This query builder handles filters, pagination, and semantic search options.

The handler delegates to two specific implementations:

- **`serveSearchHTTP`**: Serializes results as JSON when a `q` or `query` parameter is present
- **`serveSearchWebSocket`**: Manages persistent connections for interactive search sessions

### HTTP Search Example

Execute a simple JSON search by providing the `q` parameter:

```go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

type SearchResult struct {
	Documents []struct {
		Title string `json:"title"`
		URL   string `json:"url"`
	} `json:"documents"`
}

func main() {
	resp, err := http.Get("http://localhost:8080/search?q=golang+openapi")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result SearchResult
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		panic(err)
	}
	for _, d := range result.Documents {
		fmt.Printf("%s – %s\n", d.Title, d.URL)
	}
}

```

### WebSocket Streaming Example

For real-time updates, omit query parameters to trigger the WebSocket upgrade:

```go
package main

import (
	"encoding/json"
	"log"

	"github.com/gorilla/websocket"
)

func main() {
	ws, _, err := websocket.DefaultDialer.Dial("ws://localhost:8080/search", nil)
	if err != nil {
		log.Fatal(err)
	}
	defer ws.Close()

	query := map[string]string{"text": "hister go"}
	if err := ws.WriteJSON(query); err != nil {
		log.Fatal(err)
	}

	var result map[string]any
	if err := ws.ReadJSON(&result); err != nil {
		log.Fatal(err)
	}
	log.Printf("Results: %+v\n", result)
}

```

## Hister Configuration API Endpoint

The configuration endpoint exposes server capabilities and runtime settings to client applications.

### Endpoint Specification

**`GET /api/config`** returns a JSON payload containing server metadata, search capabilities, and authentication modes. Located at lines 66‑73 in [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go), this endpoint is **publicly accessible** but **CSRF-protected** to prevent cross-site request forgery attacks. The response includes a fresh CSRF token for subsequent state-changing operations.

### Implementation Details

The `serveConfig` handler in [`server/endpoints.go`](https://github.com/asciimoo/hister/blob/main/server/endpoints.go) (lines 30‑59) aggregates data from multiple sources:

- **`config.Config`**: Runtime server configuration including base URLs
- **`searchschema.CapabilitiesDefinition`**: Supported search features and semantic search availability
- **Authentication mode**: Current auth configuration and hot-key settings

This endpoint enables clients to discover server capabilities dynamically before executing searches.

### Configuration Retrieval Example

Fetch the server configuration to discover available features:

```go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	resp, err := http.Get("http://localhost:8080/api/config")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var cfg map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&cfg); err != nil {
		panic(err)
	}
	
	fmt.Println("Base URL:", cfg["baseUrl"])
	fmt.Println("Search URL:", cfg["searchUrl"])
	fmt.Println("Semantic search enabled:", cfg["semanticEnabled"])
}

```

## API Registration and Routing

Both endpoints are registered through the `registerEndpoints` function in [`server/endpoints.go`](https://github.com/asciimoo/hister/blob/main/server/endpoints.go) (lines 60‑66). This function iterates over the `Endpoints` slice defined in [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go) and wires each route to the HTTP multiplexer. This centralized registration pattern ensures consistent middleware application and route management across the application.

## Summary

- **`GET /search`** executes full-text queries via JSON or WebSocket, implemented by `serveSearch` in [`server/endpoints.go`](https://github.com/asciimoo/hister/blob/main/server/endpoints.go) with parameter parsing at lines 32‑44.
- **`GET /api/config`** returns runtime configuration and capabilities via `serveConfig`, protected by CSRF tokens but requiring no authentication.
- Both endpoints are defined in the `Endpoints` slice within [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go) (lines 66‑82) and registered via `registerEndpoints`.
- The search endpoint constructs `indexer.Query` objects for the underlying search engine, while the config endpoint serializes `config.Config` and capability definitions.

## Frequently Asked Questions

### What authentication is required for Hister API endpoints?

Both the `/search` and `/api/config` endpoints are public and require no authentication tokens or session cookies. However, the `/api/config` endpoint enforces CSRF protection, meaning clients must obtain and include a valid CSRF token in headers for any non-GET requests, though simple configuration retrieval works without it.

### How does the search endpoint decide between HTTP and WebSocket responses?

The `serveSearch` handler checks for the presence of `q` or `query` URL parameters using `parseSearchQueryParams`. If parameters exist, the handler calls `serveSearchHTTP` to return JSON results immediately. If no query parameters are provided, the handler upgrades the connection to a WebSocket via `serveSearchWebSocket` for streaming interaction.

### Where are the API endpoint routes defined in the source code?

The route definitions exist in the `Endpoints` slice located in [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go) (lines 66‑73 for configuration, lines 77‑82 for search). The concrete HTTP handlers implementing these routes reside in [`server/endpoints.go`](https://github.com/asciimoo/hister/blob/main/server/endpoints.go), specifically the `serveSearch` and `serveConfig` functions.

### Can I use the Hister API from a Go application?

Yes, the repository includes client libraries in [`client/search.go`](https://github.com/asciimoo/hister/blob/main/client/search.go) and [`client/client.go`](https://github.com/asciimoo/hister/blob/main/client/client.go) that wrap these public endpoints. These clients handle HTTP requests, WebSocket connections, and response parsing, providing a programmatic interface to the **Hister API endpoints** without manual HTTP client configuration.