Hister API Endpoints for Document Operations: Complete CRUD Reference

Hister exposes eight HTTP REST endpoints under the /api/ path that enable clients to create, retrieve, update, and delete indexed documents, with support for batch operations, PDF uploads, and legacy compatibility aliases—all registered in server/api.go.

The asciimoo/hister repository implements a lightweight document indexing and retrieval server. This guide details all Hister API endpoints for document operations, including request schemas, available parameters, and Go client implementation patterns derived directly from the source code.

Core Document CRUD Endpoints Overview

All document operations are defined in server/api.go and exposed under the /api/ base path.

Operation	Method	Path	Source Location
Add document	POST	/api/add	api.go: L46-L53
Legacy add	POST	/add	api.go: L25-L33
Add PDF	POST	/api/add_pdf	api.go: L84-L91
Retrieve document	GET	/api/document	api.go: L66-L71
Update label	POST	/api/label	api.go: L28-L33
Batch update	POST	/api/update	api.go: L18-L25
Delete documents	POST	/api/delete	api.go: L27-L34
Batch operations	POST	/api/batch	api.go: L70-L78
Preview HTML	GET	/api/preview	api.go: L87-L94
Raw file	GET	/api/file	api.go: L95-L102

Creating and Indexing Documents

Hister provides three distinct endpoints for adding content to the index, supporting both standard web documents and binary PDF payloads.

Standard Document Addition

The POST /api/add endpoint accepts new documents via application/x-www-form-urlencoded or application/json payloads. Valid fields include url, title, text, html, favicon, label, type, and updated. This handler is implemented at lines 46-53 of server/api.go.

// client/document.go provides a thin wrapper around the /api/add endpoint.
doc := client.Document{
    URL:   "https://example.com/article",
    Title: "Example Article",
    Text:  "Full text of the article …",
}
if err := client.AddDocument(ctx, doc); err != nil {
    log.Fatalf("add failed: %v", err)
}

Legacy Compatibility Endpoint

For backward compatibility, POST /add serves as an alias to /api/add. This endpoint is defined at lines 25-33 in server/api.go and accepts identical payload formats.

PDF Document Upload

To index binary PDF content, use POST /api/add_pdf. This endpoint expects a JSON object containing a document sub-object (with url, title, label) and a base64-encoded pdf payload. The implementation resides at lines 84-91 of server/api.go.

Retrieving Documents

Hister offers three retrieval endpoints that provide different representations of stored documents.

Document Metadata and Content

GET /api/document returns the complete stored record for a specified url parameter. This includes the indexed text, HTML, metadata, and user-defined labels. The endpoint logic is located at lines 66-71 of server/api.go.

doc, err := client.GetDocument(ctx, "https://example.com/article")
if err != nil {
    log.Fatalf("get failed: %v", err)
}
fmt.Printf("Title: %s\nHTML: %s\n", doc.Title, doc.HTML)

HTML Preview and Raw Files

For human-readable rendering, GET /api/preview serves an HTML representation of the stored document. For accessing original binary payloads of locally indexed files, GET /api/file returns the raw file contents. These read-only endpoints are implemented at lines 87-94 and 95-102 of server/api.go, respectively.

Updating Documents

Hister supports both targeted label updates and broad batch modifications of mutable attributes.

Single Document Label Updates

To modify the user-defined label of a specific document, send a POST /api/label request with url and label fields. Setting label to an empty string clears the existing value. This endpoint is defined at lines 28-33 of server/api.go.

payload := map[string]string{
    "url":   "https://example.com/article",
    "label": "research",
}
if err := client.PostJSON(ctx, "/api/label", payload, nil); err != nil {
    log.Fatalf("label update failed: %v", err)
}

Batch Attribute Updates

The POST /api/update endpoint enables modifying fields—owner, label, title, and language—across multiple documents matching a search query. It supports a dry_run mode to preview affected documents before committing changes. See lines 18-25 of server/api.go for the implementation.

Deleting Documents

POST /api/delete removes documents matching a provided search query. The endpoint accepts a query parameter and an optional dry_run boolean flag that returns the deletion count without removing records. This functionality is implemented at lines 27-34 of server/api.go.

payload := map[string]interface{}{
    "query":   "site:example.com tag:old",
    "dry_run": false,
}
var resp struct{ Deleted int `json:"deleted"` }
if err := client.PostJSON(ctx, "/api/delete", payload, &resp); err != nil {
    log.Fatalf("delete failed: %v", err)
}
fmt.Printf("Deleted %d documents\n", resp.Deleted)

Batch Operations

The POST /api/batch endpoint executes up to 100 mixed operations—add, delete, and get—within a single request. Clients submit an ops array where each element specifies an operation type (op field) and its parameters. The server processes these atomically up to a configurable maximum body size. This is implemented at lines 70-78 of server/api.go.

batch := []map[string]interface{}{
    {
        "op":    "add",
        "url":   "https://example.com/new",
        "title": "New Doc",
        "text":  "Content …",
    },
    {
        "op":  "get",
        "url": "https://example.com/new",
    },
}
var result []map[string]interface{}
if err := client.PostJSON(ctx, "/api/batch", map[string]interface{}{"ops": batch}, &result); err != nil {
    log.Fatalf("batch failed: %v", err)
}
fmt.Printf("Batch result: %#v\n", result)

Summary

• Hister API endpoints for document operations are centralized in server/api.go and mounted under /api/* (with a legacy /add alias).
• Creation supports standard JSON/form data via /api/add and base64-encoded PDFs via /api/add_pdf.
• Retrieval offers metadata access (/api/document), HTML previews (/api/preview), and raw file serving (/api/file).
• Updates range from single-label changes (/api/label) to query-based batch modifications (/api/update) with dry-run support.
• Deletion via /api/delete supports query-based matching and dry-run validation.
• Batch processing (/api/batch) enables up to 100 mixed operations per request, optimizing bulk workflows.

Frequently Asked Questions

What content types does the /api/add endpoint accept?

The /api/add endpoint accepts both application/x-www-form-urlencoded and application/json content types. For JSON payloads, include fields such as url, title, text, html, favicon, label, type, and updated according to the schema defined in server/api.go at lines 46-53.

How can I delete multiple documents simultaneously?

Use the POST /api/delete endpoint with a search query parameter to target multiple documents, or use POST /api/batch to bundle up to 100 delete operations with other document actions. Both endpoints support a dry_run flag to preview the operation impact before execution.

What is the maximum number of operations in a batch request?

The POST /api/batch endpoint supports up to 100 operations per request. The maximum request body size is configurable, but each operation in the ops array must specify a valid operation type (add, delete, or get) and its required parameters as implemented at lines 70-78 of server/api.go.

How do I retrieve an HTML preview of a stored document?

Send a GET /api/preview request with the appropriate document identifier. This endpoint returns a rendered HTML representation of the stored content, distinct from the raw file endpoint (/api/file) and the metadata endpoint (/api/document). The preview logic is located at lines 87-94 of server/api.go.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}